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

Quality

Content

50%

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

The body combines a verbose agent-configuration YAML block with a concise but abstract architecture-design guide. It lists relevant deliverables and frameworks but lacks executable examples, a sequenced workflow, and any progressive-disclosure structure.

Suggestions

Move or remove the large YAML configuration block from the body; keep only instructionally relevant content in SKILL.md.

Add a concrete worked example or template (e.g. a sample ADR format or a C4 context diagram description) so guidance is copy-paste ready.

Provide a sequenced design workflow with explicit checkpoints, e.g. gather quality attributes -> propose options -> evaluate trade-offs -> write ADR -> validate against constraints.

Dimension	Reasoning	Score
Conciseness	The instructional markdown (responsibilities, best practices, deliverables) is reasonably tight, but the body opens with a ~120-line YAML configuration block (triggers, capabilities, hooks, optimization) that is largely framework metadata Claude does not need, padding the context.	2 / 3
Actionability	It names concrete artifacts and frameworks (C4 model, UML, ADRs, technology evaluation matrix, data flow diagrams), but gives no executable commands, templates, or worked examples — guidance stays at the level of 'Design scalable architectures' and 'Document decisions with rationale.'	2 / 3
Workflow Clarity	A 'Decision framework' supplies a useful ordered set of questions, but there is no end-to-end sequenced workflow for producing an architecture, and no validation/review checkpoints despite the multi-step nature of the task.	2 / 3
Progressive Disclosure	Content is organized into clear sections, but it is a monolithic single file with no bundle references; the large inline YAML config block is content that would be better separated or removed rather than kept inline.	2 / 3
	Total	8 / 12 Passed

Description

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is a placeholder-quality invocation string rather than a capability description: it tells Claude how to call the skill but not what it does or when to use it. It fails on specificity, trigger terms, and completeness.

Suggestions

Replace the description with concrete actions, e.g. 'Designs scalable system architectures, produces C4/UML diagrams, and writes Architecture Decision Records.'

Add an explicit trigger clause such as 'Use when the user asks to design, review, or document system architecture, microservices, or scalability.'

Include natural keyword variations users would say (architecture, system design, scalability, design patterns, ADRs) instead of the '$agent-arch-system-design' invocation token.

Dimension	Reasoning	Score
Specificity	The description 'Agent skill for arch-system-design - invoke with $agent-arch-system-design' names no concrete actions at all, only the invocation syntax; it is abstract rather than descriptive of capabilities.	1 / 3
Completeness	It neither states concretely what the skill does nor provides any 'Use when...' trigger guidance, so both the 'what' and 'when' are effectively missing.	1 / 3
Trigger Term Quality	It contains only the technical slug 'arch-system-design' and the invocation token '$agent-arch-system-design'; no natural phrases a user would say (e.g. 'system architecture', 'scalability', 'design pattern') are present.	1 / 3
Distinctiveness Conflict Risk	It does name the architecture domain ('arch-system-design'), giving it a narrow niche, but the generic 'Agent skill for' framing and absent triggers mean it could still overlap with related design skills.	2 / 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/claude-flow
Commit: 03d4f84

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