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

70%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/pdf-brain-ingest/SKILL.md

Quality

Content

57%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 dense, command-rich operator guide for the joelclaw docs ingest pipeline with strong actionability and clear sequencing, undermined by unsignaled bundle files, inline duplication of the operator guide, and time-sensitive version detail outside a deprecated section.

Suggestions

Link references/operator-guide.md from the body (e.g., a 'See operator-guide.md for troubleshooting and maintenance' line) and move duplicated operator/troubleshooting detail there instead of inlining it.

Move version-specific details (opendataloader-pdf v2.0.0, nomic-embed-text-v1.5, OpenJDK 25, ADR-0234) into a dedicated versions/deprecated section so they don't penalize conciseness as they age.

Add an explicit validation checkpoint to the batch-reindex workflow (e.g., verify artifact counts and check OTEL for errors after the batch completes) to lift workflow clarity above the batch-op cap of 3.

Dimension	Reasoning	Score
Conciseness	Mostly command-dense and operational, but it carries time-sensitive version numbers (opendataloader-pdf v2.0.0, nomic-embed-text-v1.5, OpenJDK 25, ADR-0234) outside any deprecated section and duplicates material also found in references/operator-guide.md, so it could be tightened.	3 / 5
Actionability	Provides copy-paste-ready joelclaw commands with flags across the full workflow (add, reindex-v2, batch-reindex, monitor, inspect, retrieve, reconcile), with only minor gaps and placeholder args like <doc-id>.	4 / 5
Workflow Clarity	The Core Workflow is clearly sequenced into numbered sections 1–9, but batch operations lack an embedded validation checkpoint, so per the batch/destructive cap workflow clarity cannot exceed 3.	3 / 5
Progressive Disclosure	Section headers give reasonable structure, but references/operator-guide.md and the assets/ logos are never linked or signaled from the body, and operator/troubleshooting detail is duplicated inline rather than split out.	3 / 5
	Total	13 / 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 clearly states what the skill does and when to use it, with an explicit triggers list and concrete actions; its only weaknesses are slight architectural framing and a few generic trigger terms.

Dimension	Reasoning	Score
Specificity	Names the domain and lists several concrete actions ('Ingest PDF/Markdown/TXT files', 'adding docs, running batch reindex, reconciling coverage, or recovering stuck runs'), but the framing leans architectural (durability, NAS, OTEL) rather than enumerating all discrete user actions, leaving minor gaps.	4 / 5
Completeness	It explicitly answers both 'what' (ingest files into joelclaw's docs memory pipeline with Inngest durability, NAS artifacts, OTEL verification) and 'when' ('Use when adding docs, running batch reindex, reconciling coverage, or recovering stuck runs' plus a concrete triggers list), matching the 5-anchor example.	5 / 5
Trigger Term Quality	An explicit 'Triggers on:' list supplies eight natural phrases plus synonyms (reindex docs / batch reindex / backfill books), but it omits extension-style terms (e.g., '.pdf') and a few natural phrasings like 'search docs'.	4 / 5
Distinctiveness Conflict Risk	Tying triggers to the named 'joelclaw' docs memory pipeline gives it a clear niche, but generic phrases like 'docs add' carry minor overlap risk with other document-management 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: d952451

Reviewed: 4 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.