Content
81%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.
An unusually disciplined process skill: a clearly gated four-phase workflow, concrete conventions down to temp-file naming and literal prompts, and pointers placed precisely where each stage needs them. The main weakness is packaging rather than writing — every sidecar and script the body depends on is missing from the bundle, which breaks progressive disclosure in practice and leaves a few operational steps unexecutable.
Suggestions
Ship the referenced bundle files (LANGUAGE.md, PRESENTING.md, DEEPENING.md, INTERFACE-DESIGN.md, ../grill-with-docs/GLOSSARY-FORMAT.md and ADR-FORMAT.md, and scripts/agents.config.sh / agents.lib.sh) alongside SKILL.md, or inline the irreducible minimum of each so the skill is self-sufficient when they are absent.
State the shared invariants (§10 behaviour-preserving commits, §7 propose-don't-land) once in the preamble and reference them by number elsewhere; the current three restatements cost tokens without adding guidance.
Trim the glossary to the terms used in the body's own prose and defer full definitions entirely to LANGUAGE.md, since the section already tells the reader the full list lives there.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes competence — it never explains what a module or ADR is, and nearly every sentence carries a rule or a pointer. Minor over-explanation could be trimmed: the §10 behaviour-preserving invariant is stated three times (preamble, 'What this skill does not do', 'Hand off'), and the 8-term glossary duplicates definitions that LANGUAGE.md already holds, matching the 4 anchor rather than the every-token-earns-its-place 5. | 4 / 5 |
Actionability | Highly concrete for an instruction skill: exact friction questions to explore, the deletion test, a precise report path convention ('$TMPDIR' falling back to '/tmp', '<tmpdir>/architecture-review-<timestamp>'), enumerated card fields, a fixed recommendation-strength enum, and a literal prompt to ask ('Which of these would you like to explore?'). Not a 5 because some operational detail is deferred to assets that are not in the bundle — 'scripts/agents.config.sh' and 'sh scripts/agents.lib.sh <tier>' cannot be executed as shipped, and 'walk back a stretch of the commit history' gives no concrete command. | 4 / 5 |
Workflow Clarity | A four-phase process (scope/explore → present report → grilling loop → hand off) with explicit gates at every transition: 'Do NOT propose interfaces yet. After the file is written, ask...', 'Once the human picks a candidate, drop into a grilling conversation', and 'The session ends at an agreed design, not at a diff'. The card field list is a checklist, and edge cases get explicit handling (decision-record conflicts, unmapped capability tier as 'a working state, not a failure'). This matches the 5 anchor's clear sequence with explicit checkpoints; the skill is read-only plus human-gated conversation, so the destructive-operation cap does not apply. | 5 / 5 |
Progressive Disclosure | The design is textbook progressive disclosure: a concise overview body with well-signaled, one-level-deep references deployed exactly at the point of need — [LANGUAGE.md] for vocabulary, [PRESENTING.md] for the report contract, [DEEPENING.md] for dependency classification, [INTERFACE-DESIGN.md] for design-twice, plus two ../grill-with-docs format files. Scored against the actual bundle, however, none of these six referenced files (nor scripts/agents.config.sh) exist in the provided skill directory, so the deferred content is unreachable as staged — a real gap that keeps it below the 5 anchor's 'easy navigation'. | 4 / 5 |
Total | 17 / 20 Passed |