Content
85%Weight 40%Scale 1-5Reviews 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, well-sequenced diagnostic workflow with excellent validation loops and executable commands throughout — no concept padding, every token carries operational specifics. The main weakness is packaging: all reference material lives inline in one long file and one cited path (docs/minsync-setup.md) is missing from the bundle.
Suggestions
Move the diagnostic-codes table and the repair-playbook detail into references/ files (e.g. references/diagnostic-codes.md, references/repair-playbook.md) and keep SKILL.md as a lean overview with well-signaled one-level-deep links.
Fix or remove the dangling reference to docs/minsync-setup.md, since no bundle file exists at that path.
Trim the embedder-history narrative (Q8_0 gateway compatibility details) to the actionable rule — rebuild or re-embed — or relocate it to a reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious operational detail (null-vs-[] semantics, lock ownership rules, identity-mismatch history) and never explains concepts Claude already knows, but at ~280 lines sections like the embedding-model-mismatch narrative and the long diagnostic-codes table could be trimmed or split. Not 5 because a few passages (e.g., the Q8_0 gateway history paragraph) run longer than the instruction strictly needs; not 3 because there is no padding or generic explanation. | 4 / 5 |
Actionability | Guidance is fully executable throughout: exact triage commands ('autorag status --json', 'autorag setup --format json'), a per-datasource table of native check and re-sync commands, concrete MCP probe payloads ('autorag.search {"query":"a word that certainly appears","topK":3}'), and copy-paste repair commands including exact cargo install pins. Coverage of common failure cases is essentially complete. | 5 / 5 |
Workflow Clarity | A clear four-phase sequence (triage core → probe datasources → prove searchability → repair playbook) with explicit validation: 'Searchable must come from an actual query in step 3, never inferred from index state', 're-run the failing check', 'Re-run autorag status --json afterwards to confirm inFlight: false', and a completion condition checklist. Destructive operations (kill orphan, delete lock, index rebuild) each carry confirm-first guards, giving strong feedback loops. | 5 / 5 |
Progressive Disclosure | Section structure and tables are good, but the skill is a single ~280-line monolith with no bundle: reference material (the 25-row diagnostic-codes table, per-datasource repair detail, embedder history) is inlined where a references/ file would keep SKILL.md a lean overview. It also points to 'docs/minsync-setup.md', which does not exist in the bundle. Not 2 because headers and tables make it navigable; not 4 because content that should be separate is inline and one reference is dangling. | 3 / 5 |
Total | 17 / 20 Passed |