agent-swarm-issue

Agent skill for swarm-issue - invoke with $agent-swarm-issue

2.93x

Quality

Does it follow best practices?

Impact

97%

2.93x

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-swarm-issue/SKILL.md

Quality

Content

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

This skill is extremely verbose and largely non-actionable, consisting primarily of hypothetical CLI commands for what appears to be a fictional `ruv-swarm` tool with no installation or setup instructions. The content reads more like a product feature wishlist or marketing document than an executable skill guide. It lacks validation steps, error handling, and any verification that the referenced tools actually exist or work as described.

Suggestions

Remove all references to `npx ruv-swarm` commands unless this is a real, installable tool — replace with actual executable commands using `gh` CLI and the MCP tools listed in the frontmatter

Reduce content to under 100 lines focusing on the core workflow: fetching an issue, decomposing it into tasks, spawning agents, and tracking progress — using only the tools declared in the frontmatter

Add explicit validation checkpoints (e.g., verify issue exists before decomposing, confirm agent spawn succeeded before orchestrating, validate checklist updates before posting comments)

Fix MCP tool call syntax to use proper JSON format and provide concrete, executable examples that match the tools listed in the frontmatter (mcp__github__get_issue, mcp__claude-flow__swarm_init, etc.)

Dimension	Reasoning	Score
Conciseness	Extremely verbose at 400+ lines with massive amounts of speculative CLI commands for a tool (ruv-swarm/npx ruv-swarm) that appears hypothetical. Enormous sections on stale issue handling, duplicate detection, metrics, and best practices that explain concepts Claude already knows. Most content is aspirational rather than instructional.	1 / 3
Actionability	Nearly all commands reference `npx ruv-swarm` which appears to be a non-standard/hypothetical tool with no installation or verification instructions. The bash scripts mix real `gh` CLI commands with fictional tool invocations, making them non-executable. The MCP tool calls at the end use invalid syntax (not proper JSON arguments). Nothing is copy-paste ready.	1 / 3
Workflow Clarity	Despite showing many multi-step processes (issue decomposition, progress tracking, stale issue handling), there are no validation checkpoints or error recovery steps. The workflows assume every command succeeds and provide no guidance on what to do when things fail. Destructive operations like closing issues and editing issue bodies lack any verification steps.	1 / 3
Progressive Disclosure	The content has section headers and references other skill files (swarm-pr.md, sync-coordinator.md, workflow-automation.md) at the bottom, but no bundle files are provided to verify these exist. The main file itself is a monolithic wall of content that should have been split into separate reference files for the many subsections (automation examples, integration patterns, metrics, etc.).	2 / 3
	Total	5 / 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.

This description is critically deficient across all dimensions. It provides no information about what the skill does, when it should be used, or what types of tasks it handles. It reads as a placeholder rather than a functional description that Claude could use for skill selection.

Suggestions

Add a clear statement of what the skill does with specific concrete actions (e.g., 'Triages and assigns issues across multiple repositories' or whatever the actual functionality is).

Add an explicit 'Use when...' clause with natural trigger terms that describe the scenarios and user language that should activate this skill.

Replace the generic 'Agent skill for swarm-issue' with a domain-specific description that distinguishes this skill from other agent or issue-related skills.

Dimension	Reasoning	Score
Specificity	The description provides no concrete actions whatsoever. 'Agent skill for swarm-issue' 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 keyword is 'swarm-issue', which is technical jargon and not a natural term a user would say. There are no natural language trigger terms included.	1 / 3
Distinctiveness Conflict Risk	The description is so vague that it's impossible to distinguish it from other skills. 'Agent skill' is entirely generic and provides no niche or distinct triggers.	1 / 3
	Total	4 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (578 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Repository: ruvnet/ruflo
Commit: 28c81c0

Reviewed: about 18 hours 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.