Content
70%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 dense, well-sequenced process skill with a hard human-yes gate, genuine feedback loops, and concrete commands and paths throughout. Its weaknesses are token cost from the ornate prose style and repetition between the procedure and anti-patterns sections, and a broken load-bearing reference: the BRIEF-FORMAT.md file the recording step depends on is missing from the bundle.
Suggestions
Ship BRIEF-FORMAT.md in the skill bundle (or inline the exact shapes of the three writes) so step 5's 'in the shapes [BRIEF-FORMAT.md] gives exactly' resolves — currently the bundle has no references/ or scripts/ directories at all, including the referenced scripts/trace.sh and scripts/agents.config.sh.
Tighten the prose and de-duplicate the yes-gate and convergence rules, which are stated in 'What this skill does not do', step 4, step 5, and Anti-patterns — stating each once and cross-referencing would cut meaningful tokens.
Consider moving the 'Two states to check before starting' and 'Entry points' sections into a short reference file so SKILL.md reads as the procedure plus its guards, keeping the main file leaner.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and most tokens carry real information (file paths, rules, ordering), but the ornate nested-clause style, rhetorical framing ("This skill is the decision made deliberately, twice"), and rules restated across 'What this skill does not do', steps 4-5, and Anti-patterns (the yes-gate appears four times) mean it could be noticeably tightened. | 3 / 5 |
Actionability | Guidance is largely executable — exact paths (docs/domain-glossary.md, constitution/local-engineering.md), copy-paste trace commands with argument shapes, anchor line labels, commit message format, and temp-file naming — but the actual output shapes are delegated to BRIEF-FORMAT.md, which is absent from the bundle, leaving a gap in the most concrete part of the skill. | 4 / 5 |
Workflow Clarity | Six clearly sequenced steps with an explicit hard validation gate ("Stop here for a human yes before writing anything into the repo") guarding the irreversible write, feedback loops for error recovery (revise-and-present on a no; identical candidates send you back to step 3 with sharper constraints), and edge-case handling (unstamped article, existing brief, single subdomain). | 5 / 5 |
Progressive Disclosure | In-body section structure is good and references are clearly signaled as links, but the load-bearing referenced file BRIEF-FORMAT.md — which step 5 says gives the output shapes 'exactly' — does not exist in the bundle (nor do scripts/trace.sh, scripts/agents.config.sh, or .agents/prompts/cheap-reads.md), and entry-points/two-states detail is inlined in one ~200-line file. | 3 / 5 |
Total | 15 / 20 Passed |