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 reviews architectural decisions.'

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

Clarify the domain of architecture (software, cloud, enterprise, etc.) to reduce conflict risk with other potentially overlapping 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, cloud?) 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 many other skills related to software design, system design, cloud infrastructure, or even building architecture. Nothing distinguishes this skill's 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 a large, generic architecture template dump rather than actionable guidance for Claude. It spends most of its token budget on example configurations (Kubernetes, SQL, OpenAPI, security YAML) that Claude already knows how to generate, while lacking a clear workflow for how to actually perform the architecture phase—no decision criteria, no validation steps, no input/output specifications. The content would benefit from drastic reduction and restructuring into a concise process guide.

Suggestions

Replace the bulk example templates with a concise step-by-step workflow that tells Claude exactly how to gather requirements, make architecture decisions, and produce deliverables—with explicit validation checkpoints at each stage.

Remove or move to a separate reference file the generic examples (SQL schemas, Kubernetes manifests, OpenAPI specs) that Claude already knows how to produce; keep only project-specific patterns or constraints.

Add clear input/output specifications: what information the agent expects to receive (e.g., from the pseudocode phase) and what artifacts it must produce, with acceptance criteria.

Include decision frameworks (e.g., when to choose microservices vs monolith, SQL vs NoSQL) rather than showing a single hardcoded technology stack as if it's the only option.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~350+ lines. The bulk is a generic example architecture (auth service, Kubernetes manifests, SQL schemas, OpenAPI specs) that Claude already knows how to produce. The content reads like a template dump rather than targeted instructions for what Claude should do differently.	1 / 3
Actionability	Contains concrete code examples (SQL, YAML, Mermaid diagrams), but they are generic illustrative examples rather than executable guidance for a specific task. The skill never tells Claude what to actually do when invoked—it shows what an architecture might look like but doesn't provide a clear process for producing one from user input.	2 / 3
Workflow Clarity	The five-step SPARC Architecture Phase list is vague ('Defining system components and boundaries', 'Selecting technology stacks') with no validation checkpoints, decision criteria, or feedback loops. There's no clear sequence for how to go from input (specifications/pseudocode) to output (architecture document), and no verification steps.	1 / 3
Progressive Disclosure	Monolithic wall of content with no references to external files. Hundreds of lines of example YAML, SQL, and OpenAPI specs are inlined that could easily be split into separate reference files. The 'Architecture Deliverables' and 'Best Practices' sections are buried at the bottom with no navigation structure.	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/ruflo
Commit: 398f7c2

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.