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 ('invoke with $agent-architecture') adds no value for Claude's skill selection process.

Suggestions

Specify what kind of architecture this skill handles (e.g., software architecture, system design, cloud infrastructure) and list concrete actions like 'designs component diagrams, evaluates system trade-offs, creates architecture decision records'.

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

Remove the invocation instruction ('invoke with $agent-architecture') from the description and replace it with distinctive capability details that differentiate this skill from other design or engineering 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 skill. It consists mostly of boilerplate examples (auth service YAML, SQL schemas, Kubernetes manifests, OpenAPI specs) that Claude can already generate on demand, providing almost no novel or project-specific guidance. It lacks a clear workflow, validation steps, and any progressive disclosure structure.

Suggestions

Replace the generic example templates with a concise, actionable workflow: define the specific steps Claude should follow when asked to architect a system (e.g., 1. Gather requirements, 2. Define components, 3. Validate constraints, 4. Output specific deliverables).

Add explicit validation checkpoints, such as 'Verify all components have defined interfaces before proceeding to deployment architecture' or 'Confirm technology choices align with stated constraints.'

Remove or extract the lengthy example YAML/SQL/Mermaid blocks into separate reference files (e.g., EXAMPLES.md, TEMPLATES.md) and reference them from a concise overview.

Eliminate best practices and deliverable lists that state things Claude already knows (e.g., 'Design for Failure', 'Loose Coupling') and replace with project-specific constraints or decision frameworks.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~300+ 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 and deliverables sections are platitudes Claude inherently understands. Almost nothing here is novel or project-specific information that earns its token cost.	1 / 3
Actionability	The content includes concrete code examples (SQL, YAML, Mermaid), but they are illustrative templates for a generic auth service rather than executable, actionable instructions Claude can follow for a real task. There are no clear commands to run, no tool usage instructions, and no guidance on how to actually produce architecture artifacts for a given project.	2 / 3
Workflow Clarity	The SPARC Architecture phase lists 5 high-level steps but provides no sequenced workflow with validation checkpoints. There's no feedback loop, no verification steps, and no clear process for how Claude should actually conduct an architecture review or produce deliverables. The numbered list under 'SPARC Architecture Phase' is vague and not operationalized.	1 / 3
Progressive Disclosure	Monolithic wall of content with no references to external files. Hundreds of lines of example YAML, SQL, and Mermaid diagrams are inlined that could be split into reference files. No bundle files exist to support progressive disclosure, and the content makes no attempt to organize into overview vs. detail layers.	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: 9d4a9ea

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