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 fails on every dimension. It provides no information about what the skill does, when to use it, or what kinds of user requests should trigger it. It reads as a placeholder or auto-generated stub rather than a functional skill description.

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 design, software architecture, scalability, microservices, distributed systems, or infrastructure planning.'

Remove the invocation instruction ('invoke with $agent-arch-system-design') from the description since it doesn't help Claude decide when to select this skill and wastes space that should be used for capability and trigger information.

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 impossible to distinguish it from any other architecture or design-related skill. The only distinguishing element is the invocation command, which doesn't help Claude select it based on user intent.	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 overwhelmingly YAML configuration with a thin body of generic, abstract advice that Claude already knows. The actual instructional content lacks any concrete steps, executable examples, templates, or specific architectural workflows. It reads more like a role description than an actionable skill.

Suggestions

Replace the generic bullet points with a concrete, step-by-step workflow for performing architecture design (e.g., 1. Analyze existing codebase structure, 2. Identify bounded contexts, 3. Create ADR using this template: [provide template], 4. Generate C4 diagram)

Add a concrete ADR template and a C4 diagram example (e.g., PlantUML snippet) that Claude can directly use as copy-paste starting points

Remove or drastically reduce the YAML frontmatter—most of it (triggers, hooks, optimization, integration) is not standard SKILL.md content and wastes tokens on configuration that has no runtime effect

Add explicit validation steps such as 'Review the ADR against this checklist before presenting to the user: [checklist items]' to provide workflow clarity and error prevention

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') and explains basic concepts like ADRs and C4 models without adding novel, specific guidance.	1 / 3
Actionability	The body content provides only vague, abstract guidance with no concrete commands, executable code, templates, or specific examples. Bullet points like 'Design scalable, maintainable system architectures' and 'Consider operational aspects' describe rather than instruct, giving Claude nothing it doesn't already know how to do.	1 / 3
Workflow Clarity	There is no clear multi-step workflow or sequenced process. The content lists responsibilities and deliverables but provides no ordered steps for how to actually perform an architecture design task, no validation checkpoints, and no feedback loops.	1 / 3
Progressive Disclosure	The content is a monolithic mix of an enormous YAML frontmatter block and a short, flat body with no references to external files, no navigation structure, and no separation of overview from detailed content. The YAML contains hooks, examples, and configuration that bloat the file without clear organization.	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: ccb062f

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.