agent-arch-system-design

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

1.00x

Quality

26%

Does it follow best practices?

Impact

88%

1.00x

Average score across 3 eval scenarios

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-arch-system-design/SKILL.md

Quality

Content

28%Weight 40%Scale 1-5

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

The body is dominated by an embedded agent-configuration YAML block that provides no instructions, followed by a generic system-architect prompt that relies on knowledge Claude already has. There is no executable workflow, no validation guidance, and no references or code examples, so the skill offers little actionable value.

Suggestions

Remove the embedded agent-config YAML block (or move it to a separate reference file) — configuration like emoji_usage, batch_size, and decorative hooks does not instruct the model.

Replace generic advice ('Consider non-functional requirements', 'Think about future extensibility') with a concrete workflow: gather requirements → identify quality attributes → evaluate options → produce C4 diagrams and an ADR template.

Add actionable artifacts, e.g., an ADR template skeleton and a minimal C4/PlantUML diagram example the agent can fill in for a user's system.

Dimension	Reasoning	Score
Conciseness	The body inlines a ~128-line agent-config YAML block (emoji_usage, batch_size, memory_limit, decorative echo hooks) that adds no instructional value, and the markdown section restates generic knowledge Claude already has ('Consider non-functional requirements', 'Think about future extensibility') — noticeably verbose with several padded sections (anchor 2).	2 / 5
Actionability	No executable code, commands, or concrete steps appear anywhere; the closest to concrete guidance is naming deliverables ('Architecture diagrams (C4 model preferred)', 'Use standard diagramming notations (C4, UML)'), which is a high-level hint without the specific steps to execute (anchor 2).	2 / 5
Workflow Clarity	There is no sequenced process: 'Key responsibilities' is a capability list and 'Decision framework' is an unordered question list, with no validation checkpoints anywhere — a rough implicit ordering exists via the decision questions, so this sits at anchor 2 rather than 1.	2 / 5
Progressive Disclosure	The markdown tail is well-sectioned and short, but the large inline agent-config YAML block is content that clearly belongs in a separate file (anchor-2 behavior), while the rest has reasonable section structure — netting to anchor 3 ('Some structure but could be better organized; content that should be separate is inline').	3 / 5
	Total	9 / 20 Passed

Description

23%Weight 40%Scale 1-5

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-like invocation string rather than a capability description: it names the domain, describes no concrete actions, provides no use-when trigger guidance, and uses imperative rather than third-person voice. It would rarely be selected correctly by a model choosing among skills.

Suggestions

Rewrite in third person listing concrete capabilities, e.g., 'Designs scalable system architectures, documents decisions as ADRs, and produces C4/UML diagrams for high-level technical decisions.'

Add an explicit trigger clause: 'Use when the user asks about system design, architecture, scalability, microservices, or architectural trade-offs.'

Replace the slug-based keywords ('$agent-arch-system-design') with natural user phrases like 'system architecture', 'design a system', and 'architecture review'.

Dimension	Reasoning	Score
Specificity	The description only names the domain ('arch-system-design') with a single generic action ('invoke with $agent-arch-system-design'), matching the anchor-2 example of minimal actions; the judging guideline's third-person requirement is violated by the imperative 'invoke with' phrasing, reducing specificity by 1 to 1.	1 / 5
Completeness	'Agent skill for arch-system-design' is a vague 'what' and there is no 'when'/trigger clause at all, exactly matching anchor 2 ('Has a vague what and no when'). It cannot reach 3 because no concrete capability is stated.	2 / 5
Trigger Term Quality	The only keywords are the literal slug 'arch-system-design' and '$agent-arch-system-design' — technical jargon rather than natural phrases a user would say (e.g., 'architecture', 'system design'), matching anchor 2's 'one or two generic keywords; missing the natural phrases users say'.	2 / 5
Distinctiveness Conflict Risk	'arch-system-design' is a somewhat specific niche, but the absence of any trigger terms means it could overlap with sibling architecture/design skills, matching anchor 3 ('Somewhat specific but could still overlap with similar skills').	3 / 5
	Total	8 / 20 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/ruflo
Path: .agents/skills/agent-arch-system-design/SKILL.md
Commit: b14c79e

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.