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 description is critically underspecified. It provides no concrete actions, no trigger guidance, and no domain specificity beyond the single word 'architecture.' It would be nearly impossible for Claude to reliably select this skill from a pool of available skills, and it risks conflicting with many other skills.

Suggestions

Define concrete actions the skill performs, e.g., 'Designs system architecture diagrams, evaluates component dependencies, and proposes 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 layout, service boundaries, or design patterns.'

Clarify the specific 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 describe what the skill does, what actions it performs, or what outputs it produces.	1 / 3
Completeness	Neither the 'what' nor the 'when' is meaningfully addressed. There is no explanation of what the skill does and no guidance on when Claude should select it. The description fails both criteria entirely.	1 / 3
Trigger Term Quality	The only keyword is 'architecture,' which is overly generic and could refer to software architecture, building architecture, system design, etc. The invocation command '$agent-architecture' is not a natural user term. No natural trigger terms are present.	1 / 3
Distinctiveness Conflict Risk	'Architecture' is extremely broad and could conflict with any skill related to software design, system design, infrastructure, building design, or code structure. There are no distinguishing details to carve out a clear niche.	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 dump of generic architecture templates (Kubernetes, OpenAPI, SQL, security YAML) that Claude already knows how to produce, rather than actionable instructions for performing the Architecture phase of SPARC. It lacks a clear workflow, validation steps, and any progressive disclosure structure. The content would be more effective as a concise set of instructions telling Claude what to do, what inputs to expect, what outputs to produce, and how to validate the results.

Suggestions

Replace the generic template examples with concise instructions describing what the agent should do when invoked: what inputs to gather, what decisions to make, and what artifacts to produce.

Add a clear sequenced workflow with validation checkpoints, e.g., 1) Review specifications → 2) Identify components → 3) Define interfaces → 4) Validate with user → 5) Document decisions.

Remove boilerplate content Claude already knows (Kubernetes manifests, OpenAPI specs, SQL DDL, generic security patterns) or move them to separate reference files with clear links.

Add specific guidance on how to handle ambiguity, make technology selection trade-offs, and what questions to ask the user during the architecture phase.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~300+ lines. Most content is generic architecture boilerplate (Kubernetes manifests, OpenAPI specs, SQL schemas, mermaid diagrams) that Claude already knows how to produce. The skill explains basic concepts like RBAC, caching layers, and horizontal scaling that add no new knowledge. Nearly every token could be cut.	1 / 3
Actionability	Contains concrete code examples (SQL, YAML, Kubernetes manifests) that are technically executable, but they are generic templates not tied to any specific task the agent should perform. The skill never tells Claude what to actually do when invoked — it shows example outputs rather than providing instructions for how to analyze a user's project and produce architecture artifacts.	2 / 3
Workflow Clarity	The SPARC Architecture phase lists 5 high-level steps but provides no sequenced workflow with validation checkpoints. There's no guidance on how to gather inputs, when to validate designs, how to handle ambiguity, or what constitutes a complete architecture. The 'Deliverables' section is a checklist with no process for producing or verifying them.	1 / 3
Progressive Disclosure	Monolithic wall of text with no references to external files and no bundle files provided. All content — high-level architecture, data architecture, API specs, Kubernetes configs, security architecture, scalability patterns — is inlined in a single massive file with no navigation structure or layering.	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: 2b9e2de

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