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'.
90
88%
Does it follow best practices?
Impact
Pending
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 specific technology names (Inngest, NAS, OTEL) and a comprehensive trigger term list makes it highly distinctive and easy for Claude to match. The only minor concern is that some terms like 'OTEL verification' and 'durable NAS artifacts' are quite technical, but given the specialized nature of this skill, that's appropriate.
| 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, 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: joelclaw's specific docs memory pipeline with Inngest durability and OTEL verification. 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
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with excellent workflow clarity and concrete CLI commands for every operation. Its main weakness is that it packs too much reference-level detail (chunking strategy rationale, embedding model comparisons, extraction benchmarks) inline rather than splitting into referenced files, making it longer than necessary for the primary use case of guiding ingest operations.
Suggestions
Move Extraction Details, Embedding Model, and Chunking Strategy sections into a separate REFERENCE.md file and link to it, keeping only the essential facts inline (e.g., 'Uses nomic-embed-text 768-dim via ollama; see REFERENCE.md for details').
Trim the architecture section by removing explanatory properties (durable, resumable, recoverable descriptions) — the artifact-chain diagram already makes these properties self-evident.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient with good use of code blocks and tables, but includes some unnecessary detail like embedding model benchmarks, extraction speed stats, and chunking strategy rationale (ADR findings) that Claude doesn't need inline. The architecture diagram and artifact chain explanation are useful but could be tighter. | 2 / 3 |
Actionability | Highly actionable with concrete, copy-paste-ready CLI commands for every workflow step — single ingest, batch reindex, monitoring, artifact inspection, recovery, and retrieval. Commands include specific flags and paths. | 3 / 3 |
Workflow Clarity | Clear numbered sequence from preflight through ingest, monitoring, inspection, retrieval, reconciliation, and recovery. Includes explicit validation via OTEL monitoring, artifact checks, and a recovery section with retry guidance and error checking commands. | 3 / 3 |
Progressive Disclosure | Content is well-structured with clear sections and headers, but it's a long monolithic file. Detailed sections like Chunking Strategy, Embedding Model comparisons, and Extraction Details could be split into referenced files. The Inngest events table and acquisition pipeline could also be separate references. | 2 / 3 |
Total | 10 / 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
ce9ca8e
- 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.