Content
7%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads as a generic software engineering best-practices document that explains concepts Claude already knows thoroughly. It lacks concrete, executable examples, defined workflows, and actionable specificity. Nearly every guideline (early returns, separation of concerns, DDD, avoiding utils files) is standard knowledge that doesn't warrant inclusion without project-specific context or novel implementation patterns.
Suggestions
Replace abstract principles with concrete, executable code examples showing the preferred patterns (e.g., a before/after refactoring example demonstrating early returns, or a concrete Clean Architecture folder structure with file contents).
Add a decision-tree or step-by-step workflow for architectural decisions, such as: 1) Identify bounded contexts → 2) Define domain entities → 3) Validate separation → 4) Review against anti-patterns checklist.
Remove content Claude already knows (what DDD is, what separation of concerns means, what early returns are) and focus only on project-specific conventions, preferred libraries, or non-obvious architectural decisions unique to this codebase.
Add specific, named library recommendations with version constraints and usage examples rather than generic advice like 'check npm for existing libraries'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is verbose and explains many concepts Claude already knows well—Clean Architecture, DDD, separation of concerns, early returns, avoiding code duplication, error handling. Much of this is general software engineering wisdom that doesn't add novel value. The anti-patterns section largely restates the best practices section in negative form, and the boilerplate 'When to Use' and 'Limitations' sections add no actionable content. | 1 / 3 |
Actionability | The skill provides no concrete code examples, no executable commands, no specific architectural templates, and no copy-paste-ready patterns. It reads as a collection of abstract principles and guidelines (e.g., 'Follow domain-driven design and ubiquitous language') without showing Claude how to actually implement them in practice. | 1 / 3 |
Workflow Clarity | There is no defined workflow or sequence of steps. The skill is a flat list of principles and rules with no process for how to apply them when designing architecture or writing code. There are no validation checkpoints, no decision trees, and no feedback loops for iterating on architectural decisions. | 1 / 3 |
Progressive Disclosure | The content is organized into sections with headers and sub-headers, which provides some structure. However, there are no references to external files for deeper content, and the document is a monolithic set of guidelines that could benefit from splitting detailed topics (e.g., DDD patterns, naming conventions) into separate reference files. Given no bundle files exist, the lack of references is somewhat expected but the inline content is still too flat. | 2 / 3 |
Total | 5 / 12 Passed |