Content
7%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is dominated by an inline agent-configuration YAML block and generic best-practice bullets rather than actionable, skill-specific guidance. It lacks concrete workflows, examples, or references that would tell Claude exactly what to do.
Suggestions
Remove the inline agent-config YAML block from the SKILL.md body or move it to a separate reference file; keep only the instruction markdown.
Replace generic best-practice platitudes with concrete, actionable guidance (e.g. an ADR template, a C4 diagram skeleton, a technology-evaluation matrix format).
Add a sequenced workflow with explicit checkpoints (gather quality attributes → propose options → document trade-offs in an ADR → review with stakeholder) rather than listing output categories.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body opens with a ~120-line inline YAML agent-config block and follows with generic platitudes Claude already knows ('Consider non-functional requirements', 'Use standard diagramming notations'), making it verbose and padded with unnecessary context. | 1 / 3 |
Actionability | The body describes responsibilities and deliverables ('Design scalable architectures', 'Document ADRs') but provides no executable code, commands, or concrete templates — it describes rather than instructs. | 1 / 3 |
Workflow Clarity | The numbered lists are categories of responsibilities and output artifacts, not a sequenced procedure, and there are no validation checkpoints or feedback loops for the design process. | 1 / 3 |
Progressive Disclosure | The markdown is organized into clear sections, but a large YAML configuration block is inlined in the body that should be separate, and no external reference files are signaled (none exist in the bundle). | 2 / 3 |
Total | 5 / 12 Passed |