architecture-design
When the user needs to design or evaluate system architecture — service boundaries, data models, API contracts, infrastructure topology, database selection, or dependency analysis. Also activate for "design the system", "how should I architect this", "monolith vs microservices", or architecture decision records.
78
73%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/architecture-design/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description that clearly communicates both what the skill does and when to activate it, with strong natural trigger terms. Its main weaknesses are that the capability verbs are somewhat generic ('design or evaluate') rather than listing specific concrete actions, and the broad scope could create overlap with more specialized skills in adjacent domains.
Suggestions
Replace generic verbs with more specific actions, e.g., 'Designs service boundaries, evaluates trade-offs between monolith and microservices, defines API contracts, recommends database technologies, and produces architecture decision records.'
Consider narrowing scope or adding explicit boundary statements to reduce overlap, e.g., 'Not for detailed database schema design or API endpoint implementation — focus is on high-level architectural decisions.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (system architecture) and lists several areas like service boundaries, data models, API contracts, infrastructure topology, database selection, and dependency analysis. However, it describes topics/areas rather than concrete actions (e.g., 'design', 'evaluate' are somewhat vague verbs compared to 'extract', 'fill', 'merge'). | 2 / 3 |
Completeness | Clearly answers both 'what' (design or evaluate system architecture across multiple dimensions) and 'when' (explicit trigger phrases like 'design the system', 'how should I architect this', 'monolith vs microservices', plus the opening 'When the user needs to...' clause). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'design the system', 'how should I architect this', 'monolith vs microservices', 'architecture decision records', plus domain terms like 'service boundaries', 'API contracts', 'database selection'. These are phrases users would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | While system architecture is a reasonably distinct domain, terms like 'data models', 'API contracts', and 'database selection' could overlap with database-specific skills, API design skills, or data modeling skills. The description covers a broad scope that might conflict with more specialized skills. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, comprehensive architecture design skill with strong actionability—concrete decision tables, clear output format, and realistic examples make it immediately useful. Its main weaknesses are moderate verbosity (some well-known principles restated) and a workflow that, while well-sequenced, lacks explicit validation checkpoints or feedback loops for verifying architectural decisions against requirements. The content would benefit from splitting reference material into linked files and adding review/validation steps.
Suggestions
Add explicit validation checkpoints in the workflow, e.g., after step 4 (pattern selection) verify the choice against non-functional requirements, and after step 8 (diagram) review for single points of failure before proceeding to ADRs.
Move detailed reference material (decision tables, database selection guide, ADR format template) into separate linked files to improve progressive disclosure and reduce the main skill's token footprint.
Trim 'Key Design Principles' to only project-specific or non-obvious guidance—Claude already knows standard practices like API versioning, consistent error shapes, and UUID usage.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly comprehensive but includes some content that Claude already knows (e.g., basic definitions of when to use monolith vs microservices, general database descriptions). The decision tables and checklists are useful but could be tighter. Some sections like 'Key Design Principles' list well-known best practices (UUIDs, API versioning, idempotency) that Claude would already know. | 2 / 3 |
Actionability | The skill provides highly concrete guidance: specific decision tables for pattern selection, a clear 10-step workflow, concrete output format with named sections, ADR format with specific fields, example prompts with realistic output snippets, and specific technology recommendations (PostgreSQL as default, etc.). The examples are detailed and copy-paste ready. | 3 / 3 |
Workflow Clarity | The 10-step workflow is clearly sequenced and comprehensive, but it lacks explicit validation checkpoints or feedback loops. For architecture design—which involves consequential decisions—there's no step to validate the architecture against requirements, no review checkpoint, and no guidance on what to do if the assessment reveals conflicting requirements or if the selected pattern doesn't fit after deeper analysis. | 2 / 3 |
Progressive Disclosure | The skill references related skills (tech-stack-eval, security-review, code-review) which is good, but the main content is a long monolithic document (~150+ lines) that could benefit from splitting detailed reference material (decision tables, database selection guide, ADR format) into separate files. The inline examples are well-placed but the overall document is dense. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- shawnpang/startup-founder-skills
- Commit
4ad31b4
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.