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.

Quality

73%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/architecture-design/SKILL.md

Quality

Content

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

Description

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

Validation

90%

Warnings & errors only

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: 3 months ago

Table of Contents

Discovery Implementation Validation

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.