agent-architecture
Agent skill for architecture - invoke with $agent-architecture
38
7%
Does it follow best practices?
Impact
88%
1.49xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/agent-architecture/SKILL.mdQuality
Discovery
0%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) does not help Claude decide when to select this skill.
Suggestions
Specify what kind of architecture this skill handles (e.g., software architecture, system design, cloud infrastructure) and list concrete actions like 'creates architecture diagrams, evaluates design patterns, reviews system components'.
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about system design, component diagrams, microservices layout, or architectural decision records.'
Remove the invocation instruction ('invoke with $agent-architecture') from the description and replace it with capability and trigger information that helps Claude distinguish this skill from others.
| 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 overly verbose, generic architecture template that explains concepts Claude already knows well (microservices, RBAC, caching, Kubernetes deployments). It lacks a clear actionable workflow with validation steps, instead providing hardcoded example configurations that aren't tailored to any specific project. The content would benefit enormously from being condensed to a concise workflow with references to separate template files.
Suggestions
Reduce the content to a concise workflow (under 50 lines) describing the steps Claude should follow during the Architecture phase, with explicit validation checkpoints (e.g., 'verify all component interfaces are defined before proceeding to infrastructure design').
Move the example templates (SQL schemas, Kubernetes manifests, OpenAPI specs, security configs) into separate reference files and link to them from the main skill with clear descriptions of when each is needed.
Remove explanations of concepts Claude already knows (RBAC, horizontal scaling, caching layers, TLS, etc.) and focus on project-specific decision criteria and constraints.
Add a clear decision framework or checklist for technology selection and architecture validation rather than hardcoded technology choices.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~350+ lines. The content is a generic architecture template with hardcoded example values (specific services, specific tech stacks, specific SQL schemas) that Claude already knows how to produce. It explains basic concepts like RBAC, horizontal scaling, and caching strategies that Claude is deeply familiar with. The mermaid diagrams, full OpenAPI specs, and Kubernetes manifests are boilerplate examples, not project-specific guidance. | 1 / 3 |
Actionability | The content provides concrete code examples (SQL, YAML, Kubernetes manifests) that are technically executable, but they are generic templates rather than actionable instructions for a specific task. There's no guidance on how to adapt these templates to an actual project, and the skill reads more like a reference document than step-by-step instructions Claude should follow. | 2 / 3 |
Workflow Clarity | The numbered list in 'SPARC Architecture Phase' (defining components, designing interfaces, etc.) is vague and lacks validation checkpoints. There's no clear workflow for how to actually perform architecture design — no decision points, no validation steps, no feedback loops. The 'Architecture Deliverables' section lists outputs but doesn't explain how to produce or validate them. | 1 / 3 |
Progressive Disclosure | This is a monolithic wall of text with everything inline. Hundreds of lines of example YAML, SQL, and Kubernetes configs that should be in separate reference files are all embedded in the main skill file. There are no references to external files for detailed specs, and no clear navigation structure beyond sequential headings. | 1 / 3 |
Total | 5 / 12 Passed |
Validation
100%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/ruflo
- Commit
ccb062f
- Reviewed
Table of Contents
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.