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'.

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, command-dense skill whose workflow is clearly sequenced with monitoring and recovery guidance. Its two weaknesses are unsignaled bundle content (an entire operator-guide reference the body never mentions, with duplicated sections) and version/machine-specific detail inline that inflates token cost without aiding execution.

Suggestions

Reference the operator guide explicitly from the body (e.g., a 'Troubleshooting & run shapes: See [references/operator-guide.md]' section) and remove the duplicated preflight/reconcile/acquisition sections from one of the two files so each has a single home.

Move machine- and version-specific details ('opendataloader-pdf v2.0.0', 'OpenJDK 25 installed on panda', '~2.5s per book on M4 Pro', benchmark accuracy claims) out of the body into the reference, keeping only what Claude needs to execute commands.

Add an explicit validation checkpoint after single-file ingest (e.g., 'verify the run completed and all 3 artifacts exist before reporting success') to close the workflow gap between fire-and-forget dispatch and later batch monitoring.

Dimension	Reasoning	Score
Conciseness	The body is dominated by lean, annotated command blocks with almost no explanation of concepts Claude already knows, but it carries trimmable environment-specific detail ('opendataloader-pdf v2.0.0 (Java-based, #1 in benchmarks, 0.90 accuracy)', 'OpenJDK 25 installed on panda', '~2.5s per book on M4 Pro', '~150x faster than Typesense CPU auto-embed') — version/machine specifics that penalize conciseness since they are not in a deprecated/reference section.	4 / 5
Actionability	Nearly every section is copy-paste-ready executable commands with real flags and example arguments ('joelclaw docs add "/absolute/path/to/file.pdf" --title "Title" --tags "tag1,tag2" --category programming', 'joelclaw docs context <chunk-id> --mode snippet-window'), covering single ingest, batch, monitoring, inspection, retrieval, reconcile, and recovery.	5 / 5
Workflow Clarity	A clearly sequenced 9-step workflow (Preflight through Recovery) with verification present (monitor artifact counts, OTEL event searches, `joelclaw docs status`) and an error-recovery feedback loop ('Check OTEL for errors: `joelclaw otel list --level error --hours 4`' then 'Individual retry'). It falls short of the top anchor because there is no explicit checkpoint telling Claude to confirm a single ingest's artifacts/run before proceeding, and no checklist for the batch operation.	4 / 5
Progressive Disclosure	The body itself is well-sectioned, but the bundle's references/operator-guide.md — which contains substantial operator material (healthy run shape, path alias behavior, EINTR troubleshooting) and duplicates body sections (preflight, reconcile, acquisition) — is never referenced or signaled anywhere in the body, so the skill reads as a monolith and the reference is undiscoverable.	3 / 5
	Total	16 / 20 Passed

Description

83%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description that explicitly states both capability and usage conditions with a concrete trigger list, in third person. Its main weaknesses are trigger phrases skewed toward exact CLI commands rather than natural user language, and some infrastructure buzzwords that carry little discriminative information.

Dimension	Reasoning	Score
Specificity	Names the domain ('PDF/Markdown/TXT files into joelclaw's docs memory pipeline') and several concrete actions ('adding docs, running batch reindex, reconciling coverage, or recovering stuck runs') with minor gaps — it leans on infrastructure jargon ('Inngest durability', 'OTEL verification') rather than comprehensively covering user-facing operations.	4 / 5
Completeness	Clearly answers both 'what' ('Ingest PDF/Markdown/TXT files into joelclaw's docs memory pipeline with Inngest durability, durable NAS artifacts, and OTEL verification') and 'when' ('Use when adding docs, running batch reindex, reconciling coverage, or recovering stuck runs') with an additional explicit trigger-phrase list — matching the anchor for concrete trigger phrases.	5 / 5
Trigger Term Quality	Lists eight explicit trigger phrases ('ingest pdf', 'docs add', 'backfill books', 'docs reconcile', 'reindex docs', 'batch reindex') with good coverage, but they are mostly CLI-command-shaped rather than the natural synonyms a user would say ('add books', 'PDFs', '.pdf', 'load documents').	4 / 5
Distinctiveness Conflict Risk	Scoped to a specific personal system ('joelclaw's docs memory pipeline') with niche triggers ('pdf-brain ingest', 'docs reconcile'), giving a clear niche; minor overlap risk remains since generic phrases like 'ingest pdf' or 'docs add' could also match general PDF/document skills.	4 / 5
	Total	17 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: joelhooks/joelclaw
Path: skills/pdf-brain-ingest/SKILL.md
Commit: aa0116c

Reviewed: 8 days ago

Table of Contents

Discovery Implementation Validation

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.