pdf-brain-ingest
Ingest PDF/Markdown/TXT files into joelclaw's docs memory pipeline with Inngest durability, durable NAS artifacts, and OTEL verification. Use when adding docs, running batch reindex, reconciling coverage, or recovering stuck runs. Triggers on: 'ingest pdf', 'ingest markdown', 'docs add', 'pdf-brain ingest', 'backfill books', 'docs reconcile', 'reindex docs', 'batch reindex'.
69
85%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly defines its scope, lists concrete actions, and provides explicit trigger guidance. The inclusion of both a 'Use when' clause and a 'Triggers on' list with multiple natural keyword variations makes it highly effective for skill selection. The only minor concern is that some terms are quite technical (Inngest, OTEL, NAS) which adds specificity but may be jargon-heavy for less technical users.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: ingesting PDF/Markdown/TXT files, batch reindex, reconciling coverage, recovering stuck runs. Also names specific technologies (Inngest durability, NAS artifacts, OTEL verification). | 3 / 3 |
Completeness | Clearly answers both 'what' (ingest PDF/Markdown/TXT files into docs memory pipeline with specific technologies) and 'when' (explicit 'Use when...' clause plus a 'Triggers on' list with specific phrases). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms explicitly listed: 'ingest pdf', 'ingest markdown', 'docs add', 'pdf-brain ingest', 'backfill books', 'docs reconcile', 'reindex docs', 'batch reindex'. These cover multiple variations a user might naturally say. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: it's specifically about joelclaw's docs memory pipeline with Inngest, NAS, and OTEL. The trigger terms are domain-specific ('pdf-brain ingest', 'docs reconcile') and unlikely to conflict with generic document processing skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a highly actionable skill with excellent workflow clarity and concrete CLI commands for every step. Its main weakness is that it's monolithic — detailed implementation specifics (chunking strategy, embedding model comparisons, extraction benchmarks, Inngest event tables) are inlined rather than split into reference files, which hurts both conciseness and progressive disclosure. The content would benefit from being restructured into a lean overview SKILL.md with pointers to supporting reference documents.
Suggestions
Extract 'Chunking Strategy', 'Embedding Model', 'Extraction Details', and 'Inngest Events' sections into separate reference files (e.g., CHUNKING.md, MODELS.md, EVENTS.md) and link to them from the main skill.
Trim the architecture section to just the pipeline diagram and key properties; move artifact path details to a reference file.
Remove or relocate the 'Acquisition Pipeline' section — it describes a separate workflow (book download) that could be its own skill or a linked reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly dense with useful information, but includes some sections that over-explain (e.g., embedding model comparisons, chunking strategy details, extraction benchmarks) that could be offloaded to reference files. The architecture diagram and artifact descriptions are efficient, but the overall length (~150 lines) could be tightened. | 2 / 3 |
Actionability | Every workflow step includes concrete, copy-paste-ready CLI commands with flags and arguments. Commands cover the full lifecycle from preflight through ingest, monitoring, inspection, retrieval, reconciliation, and recovery. The Inngest events table is a useful concrete reference. | 3 / 3 |
Workflow Clarity | The 9-step workflow is clearly sequenced from preflight through recovery. Validation checkpoints are present (monitor progress via OTEL, artifact inspection, status checks). Recovery includes a clear feedback loop: check OTEL for errors → retry individual files → skip-existing handles idempotency. The pipeline's resumable/recoverable properties are explicitly stated. | 3 / 3 |
Progressive Disclosure | Everything is in a single monolithic file with no references to supporting documents. The chunking strategy details, embedding model comparisons, extraction details, and acquisition pipeline could all be separate reference files. There are no bundle files and no cross-references, making this a wall of text that mixes overview with deep implementation details. | 1 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- joelhooks/joelclaw
- Commit
03f0a59
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.