agent-swarm-issue
Agent skill for swarm-issue - invoke with $agent-swarm-issue
37
3%
Does it follow best practices?
Impact
97%
2.93xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/agent-swarm-issue/SKILL.mdQuality
Discovery
0%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 problem domain it addresses. It reads as a placeholder rather than a functional description.
Suggestions
Add a clear statement of what the skill does with concrete actions (e.g., 'Triages and assigns issues across swarm agents' or whatever the actual functionality is).
Add an explicit 'Use when...' clause with natural trigger terms that describe the scenarios in which this skill should be selected.
Include domain-specific keywords that users would naturally use when they need this skill's functionality, rather than relying solely on the internal name 'swarm-issue'.
| 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 a technical/internal term, not something a user would naturally say. There are no natural language trigger terms. | 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 |
Implementation
7%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is an extremely verbose, largely non-actionable document that reads more like a product marketing spec than an executable agent skill. The vast majority of commands reference a hypothetical `npx ruv-swarm` CLI with invented subcommands, making almost nothing copy-paste executable. The content would need to be reduced by 80%+ and grounded in real, working tools to be useful.
Suggestions
Remove all references to `npx ruv-swarm` commands unless this is a real, documented tool — replace with actual working commands using `gh` CLI and the listed MCP tools
Reduce content to under 100 lines focusing on the core workflow: read issue → decompose → spawn agents → track progress → update issue, with one concrete executable example for each step
Add explicit validation checkpoints (e.g., verify issue exists before decomposing, check agent spawn success before orchestrating) and error handling for failed operations
Fix MCP tool invocation syntax to match actual callable format rather than pseudo-JSON notation
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 400+ lines with massive amounts of speculative CLI commands for a tool (ruv-swarm) that may not exist. Repeats similar patterns endlessly (issue-init, decompose, progress, etc.), includes sections Claude already knows (best practices, security bullet points), and explains concepts like issue templates and label strategies that add no unique value. | 1 / 3 |
Actionability | Nearly all code examples reference a hypothetical `npx ruv-swarm` CLI tool with invented subcommands that are not validated or documented elsewhere. The MCP tool invocations use incorrect syntax (JSON-like objects instead of proper function calls). None of the code is copy-paste executable — it's aspirational pseudocode dressed up as bash scripts. | 1 / 3 |
Workflow Clarity | Despite showing many multi-step bash sequences, there are no validation checkpoints, no error handling guidance, no feedback loops for when commands fail, and no clear sequencing of what order to perform operations. The skill dumps dozens of disconnected command snippets without a coherent workflow an agent could follow. | 1 / 3 |
Progressive Disclosure | The skill does reference related files (swarm-pr.md, sync-coordinator.md, workflow-automation.md) at the end, and has section headers that organize content into categories. However, the massive inline content should be split into separate files, and no bundle files are provided to support the references. | 2 / 3 |
Total | 5 / 12 Passed |
Validation
90%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/claude-flow
- Commit
9d4a9ea
- Reviewed
Table of Contents
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.