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 is an extremely weak description that fails on every dimension. It provides no information about what the skill does, when it should be used, or what types of user requests should trigger it. It reads more like a stub or placeholder than a functional skill description.
Suggestions
Add concrete actions describing what 'swarm-issue' actually does (e.g., 'Creates and manages swarm issues, assigns tasks to agents, tracks issue resolution').
Add an explicit 'Use when...' clause with natural trigger terms that users would actually say when they need this skill.
Replace the invocation instruction ('invoke with $agent-swarm-issue') with functional details—invocation syntax belongs in the skill body, not the description used for skill selection.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description contains 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, not a natural term a user would say. There are no natural language trigger terms that would help Claude match user requests to this skill. | 1 / 3 |
Distinctiveness Conflict Risk | The description is so generic ('agent skill') that it provides no distinguishing characteristics. Without knowing what it does, it could conflict with any other agent-based skill. | 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 extremely verbose and largely aspirational rather than actionable. It references a hypothetical 'npx ruv-swarm' CLI tool extensively without any setup instructions or verification that it exists, making the vast majority of code examples non-executable. The content reads more like a product feature wishlist or marketing document than a practical skill for Claude to follow, with no validation steps, error handling, or clear workflow sequencing.
Suggestions
Remove or drastically reduce all 'npx ruv-swarm' commands unless the tool is real and installed - replace with actual executable gh CLI commands and MCP tool calls that Claude can use
Cut content by 80%+ to a focused overview with the core workflow: analyze issue → decompose tasks → spawn agents → track progress, with one concrete example for each step
Add explicit validation checkpoints (e.g., verify issue exists before processing, check command exit codes, validate swarm initialization succeeded before spawning agents)
Fix MCP tool call syntax to use proper JSON format and move detailed automation examples (stale issues, triage, duplicate detection) to separate reference files
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 400+ lines with massive amounts of speculative/aspirational content. Most commands reference a non-standard 'npx ruv-swarm' CLI that Claude cannot actually execute. Huge sections of bash scripts, YAML configs, and JavaScript hooks that are largely redundant variations of the same pattern. Explains concepts Claude already knows and includes extensive boilerplate. | 1 / 3 |
Actionability | Almost none of the code is actually executable by Claude. The 'npx ruv-swarm' commands appear to reference a hypothetical/proprietary tool with no installation or setup instructions. The MCP tool calls at the bottom use invalid syntax (not proper JSON). The gh CLI commands are the only potentially real commands but are buried in speculative workflows. Most content describes rather than instructs. | 1 / 3 |
Workflow Clarity | Despite having many multi-step bash scripts, there are no validation checkpoints or error recovery steps. The workflows are presented as aspirational sequences without verification that any step succeeded before proceeding. No feedback loops for destructive operations like closing issues or editing issue bodies. The overall flow between sections is unclear - it's a grab bag of loosely related commands. | 1 / 3 |
Progressive Disclosure | The content has section headers and ends with cross-references to related files (swarm-pr.md, sync-coordinator.md, workflow-automation.md). However, the main file is a monolithic wall of content that should have been split into separate reference files. Sections like 'Automation Examples', 'Integration Patterns', and 'Metrics & Analytics' could easily be separate documents referenced from a concise overview. | 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/ruflo
- Commit
398f7c2
- 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.