Content
0%Scale 1-3Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is almost entirely YAML frontmatter configuration with a thin body of generic, high-level advice that Claude already knows. It lacks any concrete, actionable guidance—no templates, no executable examples, no specific workflows, and no validation steps. The content reads more like a job description than an instructional skill.
Suggestions
Replace the generic responsibilities and best practices with a concrete, step-by-step workflow (e.g., 1. Analyze requirements → 2. Draft C4 context diagram using specific PlantUML syntax → 3. Write ADR using provided template → 4. Validate completeness against checklist).
Add a concrete ADR template and a PlantUML diagram example that Claude can copy and adapt, rather than just naming these as deliverables.
Remove or drastically reduce the YAML frontmatter—most of it (triggers, hooks, examples, capability lists) is not actionable instruction and wastes token budget.
Add explicit validation checkpoints (e.g., 'Before finalizing, verify: all components have defined interfaces, failure modes are documented, data flow covers all user journeys').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The vast majority of the file is YAML frontmatter that duplicates concepts Claude already knows (what architecture is, what microservices are, trigger patterns, hook scripts). The body content itself is generic advice about system architecture that Claude inherently understands—listing responsibilities like 'design scalable architectures' and 'consider non-functional requirements' adds no novel information. | 1 / 3 |
Actionability | The body contains only vague, abstract guidance with no concrete commands, executable code, specific file templates, or copy-paste-ready examples. Instructions like 'Create system diagrams' and 'Document ADRs' describe what to do without showing how—no ADR template, no diagram syntax example, no specific tool commands. | 1 / 3 |
Workflow Clarity | There is no clear multi-step workflow or sequenced process. The content lists categories of deliverables and a decision framework as bullet points, but provides no ordered steps, no validation checkpoints, and no feedback loops for iterating on architectural designs. | 1 / 3 |
Progressive Disclosure | The content is a monolithic mix of an enormous YAML frontmatter block and a flat body with no references to supporting files. There are no links to detailed guides, templates, or examples. No bundle files exist to support progressive disclosure, and the body doesn't organize content into overview vs. detail layers. | 1 / 3 |
Total | 4 / 12 Passed |