architect-review

Master software architect specializing in modern architecture

Quality

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/architect-review/SKILL.md

Quality

Content

0%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill is essentially a persona description and knowledge taxonomy rather than an actionable skill. It lists hundreds of concepts Claude already knows (SOLID principles, design patterns, distributed systems theory) without providing any concrete tools, templates, checklists, or executable guidance for performing architectural reviews. The content is extremely verbose yet paradoxically lacks any specific, actionable instructions.

Suggestions

Replace the massive 'Capabilities' taxonomy with a concrete architectural review checklist containing specific evaluation criteria and scoring rubrics that Claude can apply to actual code/designs.

Add a concrete ADR (Architecture Decision Record) template and an example of a completed architectural review output so Claude knows exactly what format to produce.

Provide specific, actionable decision criteria (e.g., 'Flag as high-risk if: service has >3 synchronous downstream dependencies, data model changes affect >2 bounded contexts') instead of abstract guidance like 'Evaluate architecture decisions and identify risks'.

Remove the 'Behavioral Traits', 'Knowledge Base', 'Example Interactions', and most of the 'Capabilities' sections — these describe things Claude already knows and waste token budget.

Dimension	Reasoning	Score
Conciseness	Extremely verbose and padded with information Claude already knows. The massive 'Capabilities' section is essentially a taxonomy of software architecture concepts (SOLID principles, design patterns, cloud-native patterns, etc.) that Claude is already deeply familiar with. The 'Behavioral Traits', 'Knowledge Base', and 'Example Interactions' sections add no actionable value. This skill could be reduced by 80%+ without losing any useful guidance.	1 / 3
Actionability	Contains zero concrete code, commands, templates, or executable examples. The 'Instructions' section is four vague bullet points ('Gather system context', 'Evaluate architecture decisions'). No specific review checklists, no ADR templates, no example architectural review output, no concrete criteria for evaluating designs. Everything is abstract description rather than actionable instruction.	1 / 3
Workflow Clarity	The four-step 'Instructions' workflow is extremely vague ('Gather system context, goals, and constraints' — how? from where?). The 'Response Approach' section lists 8 steps but they are generic and lack validation checkpoints, decision criteria, or feedback loops. No guidance on what constitutes a 'high-risk change' or how to validate architectural decisions.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files and no bundle structure. All content is inline in a single massive file. The extensive capability listings could be split into reference documents, and the skill would benefit from separate files for review checklists, ADR templates, and pattern references.	1 / 3
	Total	4 / 12 Passed

Description

0%Scale 1-3

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 description is essentially a title or role label rather than a functional skill description. It lacks any concrete actions, trigger terms, or usage guidance. It uses a title-like first/second-person-adjacent framing ('Master software architect') rather than describing what the skill does in third person.

Suggestions

Replace the role label with specific actions the skill performs, e.g., 'Designs system architectures, evaluates trade-offs between microservices and monoliths, creates architecture diagrams and documentation.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about system design, architecture decisions, scalability patterns, or service decomposition.'

Narrow the scope to a distinct niche to reduce conflict risk—specify which aspects of 'modern architecture' this covers (e.g., cloud-native, event-driven, domain-driven design).

Dimension	Reasoning	Score
Specificity	The description uses vague, abstract language ('Master software architect') with no concrete actions listed. It doesn't describe what the skill actually does—no verbs like 'designs', 'reviews', 'generates' are present.	1 / 3
Completeness	Neither 'what does this do' nor 'when should Claude use it' is answered. There is no 'Use when...' clause and no description of capabilities—just a vague title-like statement.	1 / 3
Trigger Term Quality	The only potentially relevant terms are 'software architect' and 'modern architecture', which are overly generic and not natural phrases users would say when seeking help. Missing terms like 'system design', 'microservices', 'design patterns', etc.	1 / 3
Distinctiveness Conflict Risk	'Modern architecture' is extremely broad and could overlap with any coding, design, or engineering skill. There is nothing to distinguish this from general software development skills.	1 / 3
	Total	4 / 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: popey/claude-code-skills
Path: skills/architect-review/SKILL.md
Commit: a5a6601

Reviewed: 5 days 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.