agent-architecture

Agent skill for architecture - invoke with $agent-architecture

1.49x

Quality

Does it follow best practices?

Impact

88%

1.49x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

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

Quality

Discovery

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 an extremely weak description that provides almost no useful information for skill selection. It names only a vague domain ('architecture') without specifying concrete actions, trigger conditions, or the type of architecture involved. The inclusion of the invocation command ('$agent-architecture') adds no value for Claude's skill selection process.

Suggestions

Specify concrete actions the skill performs, e.g., 'Designs software architecture diagrams, evaluates system component relationships, recommends design patterns and microservice boundaries.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about system design, architecture diagrams, component layouts, design patterns, or service boundaries.'

Clarify the domain of architecture (software, cloud infrastructure, building, etc.) to reduce conflict risk with other skills.

Dimension	Reasoning	Score
Specificity	The description provides no concrete actions whatsoever. 'Agent skill for architecture' is extremely vague—it doesn't specify what kind of architecture (software, system, building?) or what actions it performs.	1 / 3
Completeness	The description fails to answer both 'what does this do' and 'when should Claude use it.' There is no 'Use when...' clause and no meaningful explanation of capabilities.	1 / 3
Trigger Term Quality	The only keyword is 'architecture,' which is overly generic and could refer to many domains. There are no natural user-facing trigger terms like 'design system,' 'component diagram,' 'microservices,' etc.	1 / 3
Distinctiveness Conflict Risk	'Architecture' is extremely broad and could conflict with software design skills, infrastructure skills, building/construction skills, or any number of other domains. Nothing distinguishes this skill from others.	1 / 3
	Total	4 / 12 Passed

Implementation

14%

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

This skill is an extremely verbose, generic architecture reference document rather than an actionable agent skill. It dumps hundreds of lines of example YAML, SQL, and Mermaid diagrams for a hypothetical auth service that Claude could generate on its own, while providing almost no guidance on the actual workflow, tool usage, or decision-making process the agent should follow. The content would benefit from being drastically shortened to focus on what Claude doesn't already know.

Suggestions

Replace the generic example templates with a concise workflow describing exactly what steps the architecture agent should take, what tools to invoke, and what outputs to produce—keep it under 50-80 lines.

Add explicit validation checkpoints (e.g., 'Verify all component interfaces are defined before proceeding to infrastructure design') and feedback loops for error recovery.

Move the detailed example templates (SQL schemas, Kubernetes YAML, OpenAPI specs) into separate reference files and link to them from a concise overview section.

Remove best practices and concept explanations that Claude already knows (loose coupling, high cohesion, design for failure) and focus on project-specific constraints or non-obvious architectural decisions.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~350+ lines. The bulk is generic example YAML/SQL/Mermaid diagrams for a hypothetical auth service that Claude already knows how to produce. The best practices section lists platitudes ('Design for Failure', 'Loose Coupling') that Claude inherently understands. Almost nothing here is project-specific or adds knowledge Claude lacks.	1 / 3
Actionability	The content includes concrete code examples (SQL, Kubernetes YAML, OpenAPI specs), but they are generic templates for a fictional auth service rather than actionable instructions Claude can execute in a real workflow. There are no commands to run, no tool usage patterns, and no guidance on how to actually produce architecture artifacts for a given project.	2 / 3
Workflow Clarity	The numbered list in 'SPARC Architecture Phase' is vague ('Defining system components and boundaries', 'Designing interfaces and contracts') with no validation checkpoints, no sequencing of tool use, and no feedback loops. There's no clear process for how the agent should actually conduct an architecture review or produce deliverables.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files. All content—high-level architecture, data architecture, API specs, Kubernetes configs, security, scalability—is inlined in a single massive document with no navigation structure or links to separate detailed references.	1 / 3
	Total	5 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/claude-flow
Commit: f547cec

Reviewed: 4 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.