agent-arch-system-design

Agent skill for arch-system-design - invoke with $agent-arch-system-design

1.00x

Quality

Does it follow best practices?

Impact

88%

1.00x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/agent-arch-system-design/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 virtually no useful information for skill selection. It reads as a placeholder or auto-generated stub, containing only the skill's internal identifier and invocation command. It fails on every dimension by not describing capabilities, triggers, or use cases.

Suggestions

Add concrete actions the skill performs, e.g., 'Designs system architectures, creates component diagrams, evaluates scalability trade-offs, and proposes infrastructure layouts.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about system architecture, distributed systems design, scalability planning, microservices layout, or infrastructure decisions.'

Remove the invocation instruction ('invoke with $agent-arch-system-design') from the description and replace it with functional content that helps Claude distinguish this skill from others.

Dimension	Reasoning	Score
Specificity	The description contains no concrete actions whatsoever. 'Agent skill for arch-system-design' is entirely vague and does not describe what the skill actually does.	1 / 3
Completeness	Neither 'what does this do' nor 'when should Claude use it' is answered. The description only states it's an agent skill and how to invoke it, providing no functional or contextual information.	1 / 3
Trigger Term Quality	The only potentially relevant term is 'arch-system-design' which is a technical identifier, not a natural keyword a user would say. No natural language trigger terms like 'architecture', 'system design', 'design patterns', etc. are present.	1 / 3
Distinctiveness Conflict Risk	The description is so vague that it's unclear what domain it covers. 'arch-system-design' hints at architecture/system design but without specifics, it could overlap with any design, architecture, or planning skill.	1 / 3
	Total	4 / 12 Passed

Implementation

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

This skill is almost entirely YAML frontmatter configuration with a very thin body that provides only generic, high-level advice Claude already knows. The actual instructional content lacks any concrete examples, templates, executable guidance, or structured workflows. It reads more like a job description than an actionable skill.

Suggestions

Replace generic advice with concrete, actionable templates — e.g., provide an actual ADR template with filled-in example, a C4 diagram template in PlantUML syntax, and a technology evaluation matrix format.

Add a clear step-by-step workflow for performing architecture design: e.g., 1) Analyze existing codebase structure, 2) Identify bounded contexts, 3) Draft component diagram, 4) Write ADR, 5) Review with stakeholder — with validation checkpoints at each step.

Remove or drastically reduce the YAML frontmatter, which consumes most of the token budget without providing actionable guidance to Claude.

Add concrete examples of deliverables (e.g., a sample ADR markdown file, a sample PlantUML diagram) so Claude knows exactly what format to produce.

Dimension	Reasoning	Score
Conciseness	The vast majority of the file is YAML frontmatter configuration that is not actionable skill content. The actual body content is generic advice Claude already knows (e.g., 'consider non-functional requirements', 'think about future extensibility') with no novel or project-specific information.	1 / 3
Actionability	The body content provides only vague, abstract guidance like 'Design scalable, maintainable system architectures' and 'Use standard diagramming notations.' There are no concrete commands, executable code, specific templates, or copy-paste-ready examples of ADRs, diagrams, or evaluation matrices.	1 / 3
Workflow Clarity	There is no sequenced workflow for how to actually perform an architecture design task. The content lists responsibilities and deliverables but provides no step-by-step process, no validation checkpoints, and no feedback loops for iterating on designs.	1 / 3
Progressive Disclosure	The content is a flat list of bullet points with no structure beyond basic headings. There are no references to external files for detailed templates, examples, or guides. The massive YAML frontmatter bloats the file without contributing to progressive disclosure of useful content.	1 / 3
	Total	4 / 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.