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 name 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 non-functional YAML frontmatter with aspirational metadata that Claude cannot enforce, combined with a body that offers only generic, high-level advice Claude already knows. There are no concrete examples, templates, executable commands, or step-by-step workflows. The skill would need to be fundamentally rewritten to provide actionable architectural guidance.

Suggestions

Replace the generic best practices with concrete, actionable templates—e.g., provide an actual ADR template in markdown format, a C4 diagram template in PlantUML, and a technology evaluation matrix structure.

Add a clear step-by-step workflow for performing architecture design (e.g., 1. Gather requirements → 2. Identify components → 3. Draft diagram → 4. Write ADR → 5. Review trade-offs) with validation checkpoints.

Remove or drastically reduce the YAML frontmatter—most of it (triggers, hooks, examples, optimization settings) is not enforceable configuration and wastes token budget.

Include at least one concrete, complete example showing an input request and the expected architecture output (e.g., a sample ADR or a sample C4 PlantUML diagram).

Dimension	Reasoning	Score
Conciseness	The vast majority of the file is YAML frontmatter that is not actionable configuration—it's aspirational metadata (triggers, hooks, examples, constraints) that Claude cannot actually enforce or use. The body content itself is generic advice Claude already knows (e.g., 'consider non-functional requirements', 'think about future extensibility') and explains obvious concepts.	1 / 3
Actionability	The body provides only vague, high-level guidance with no concrete commands, executable code, templates, or specific examples. Bullet points like 'Design scalable, maintainable system architectures' and 'Consider operational aspects' are abstract descriptions rather than actionable instructions.	1 / 3
Workflow Clarity	There is no clear multi-step workflow or sequenced process. The content lists responsibilities and deliverables but never describes how to actually perform the architecture design process step by step, nor includes any validation checkpoints.	1 / 3
Progressive Disclosure	The content is a monolithic mix of excessive YAML frontmatter and a thin body with no references to supporting files. There are no bundle files, no linked resources, and no structured navigation despite the complexity of the topic warranting detailed sub-documents (e.g., ADR templates, diagram guides).	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/claude-flow
Commit: e6dc21f

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