Content
92%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.
A high-quality conventions skill: concrete commands and paths throughout, explicit verification gates with feedback loops, and clean progressive disclosure into three well-signaled reference files. Its only weakness is minor redundancy between the concept-model table (§1) and the terminology table (§2), plus a longish cross-project vocabulary paragraph, which keep it just short of maximal token efficiency.
Suggestions
Merge or cross-reference the overlapping bead/proto/molecule/gate rows between the §1 concept table and the §2 terminology table so each concept is defined once.
Trim the Gas City cross-project paragraph to the operative rule (never import Gas City's definitions; state which project's sense is meant) and move the per-project contrasts into a reference file.
Cut 'the claimable frontier' and similar appositive restatements in table cells where the 'Key idea' column already states the definition.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and almost entirely project-specific (storage paths, commands, generator pipeline, pin policy) with no explanation of concepts Claude already knows. However, §1's concept table and §2's terminology table restate overlapping bead/proto/molecule/gate definitions, and the Gas City cross-project paragraph runs long — minor over-explanation that could be trimmed, matching anchor 4 rather than the 'every token earns its place' of anchor 5. | 4 / 5 |
Actionability | Guidance is fully executable: copy-paste gates ('bazel test //test/docsync:docsync_test --config=ci', './scripts/generate-cli-docs.sh --check', './scripts/check-doc-freshness.sh', 'make docs-dev'), concrete paths ('.beads/embeddeddolt/', 'docs/cli-docs.pin', 'docs/diagrams/excalidraw/'), and Use/Not-this terminology tables. As an instruction-only skill its specific commands and rules cover the common editing cases, matching the anchor-5 'copy-paste ready… specific examples cover the common cases'. | 5 / 5 |
Workflow Clarity | The skill provides explicit validation steps with commands (§9's gate list), feedback loops for error recovery (§8: drift gates 'fail or auto-fix any hand edit'; regenerate from the pin), and checklists for complex processes (§9's move/remove-a-page procedure, §10's review→commit sequencing with commit grouping). All three elements of the anchor-5 description are present; verification is explicit, so no destructive/batch cap applies. | 5 / 5 |
Progressive Disclosure | The body is a well-organized overview that pushes depth to three real, one-level-deep bundle files, each clearly signaled with its purpose: terminology.md ('The full prose-vs-literal rename discipline is in…'), simplification.md ('the per-page loop and the two guardrails'), and verification.md ('Run the gates in…' with only a short list kept inline). This matches the anchor-5 clear-overview pattern with easy navigation and no nested references. | 5 / 5 |
Total | 19 / 20 Passed |