CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

agent-swarm-issue

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

Quality

38%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-swarm-issue/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

38%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 an exhaustive, repetitive catalog of ruv-swarm CLI snippets with genuinely concrete gh/npx commands, but it is far too long, contains systematically corrupted paths and redirects plus pseudo-syntax MCP/JS blocks, and opens with a stray duplicate YAML frontmatter block. Batch and destructive automations lack validation checkpoints, and the trailing 'See also' links dangle because none of the referenced files ship in the bundle.

Suggestions

Trim the body to a lean overview and move the command catalogs (Issue Types & Strategies, Integration Patterns, Metrics & Analytics, Automation Examples) into one-level-deep reference files under references/, replacing the inlined walls of commands with clearly signaled links.

Fix the corrupted syntax throughout — '2>$dev$null' should be '2>/dev/null', '.github$workflows$issue-swarm.yml' should be '.github/workflows/issue-swarm.yml', 'ruvnet$swarm-action@v1' should be 'ruvnet/swarm-action@v1' — and either make the MCP tool-call and JS 'hooks' blocks real executable code or remove them.

Add validation/verification to batch and destructive workflows (e.g., dry-run and confirmation before auto-closing stale issues, verifying the issue body was updated before posting progress comments), and remove or actually create the missing swarm-pr.md, sync-coordinator.md, and workflow-automation.md files.

DimensionReasoningScore

Conciseness

The ~540-line body catalogs near-duplicate 'npx ruv-swarm github ...' invocations across 'Issue Types & Strategies', 'Integration Patterns', 'Automation Examples', and 'Examples', repeating the same get-issue/run-command/update-issue pattern many times, plus marketing prose like 'Transform GitHub Issues into intelligent swarm tasks'. This is noticeably verbose with several padded/redundant sections (anchor 2), beyond anchor 3's 'some unnecessary explanation'.

2 / 5

Actionability

Concrete commands are abundant (e.g., 'gh issue view 456 --json title,body,labels,assignees,comments', 'npx ruv-swarm github issue-decompose 456 --body "$ISSUE_BODY"'), but several scripts are broken as written — '2>$dev$null' instead of '2>/dev/null', paths like '.github$workflows$issue-swarm.yml' and 'ruvnet$swarm-action@v1' — and the 'Swarm Coordination Features' section uses non-executable pseudo-syntax ('mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 8 }') alongside JS hooks calling undefined functions. The gaps exceed anchor 4's 'minor gaps', fitting anchor 3 (pseudocode mixed with real commands, missing key details).

3 / 5

Workflow Clarity

Sequences are present and commented within each script (e.g., the stale-issue flow: find stale issues, analyze, then case-split close/keep/needs-info), but batch and destructive operations — 'issues-batch --parallel' and auto-closing issues stale 37+ days via 'gh issue close $num' — include no validation, dry-run, or verification checkpoints. Per the rubric's cap for destructive/batch workflows without validation, this cannot exceed 3.

3 / 5

Progressive Disclosure

No references/, scripts/, or assets/ directories exist in the bundle, yet the body inlines ~540 lines of command catalogs that clearly belong in separate files, and the only cross-references — 'See also: [swarm-pr.md](.$swarm-pr.md), [sync-coordinator.md](.$sync-coordinator.md), [workflow-automation.md](.$workflow-automation.md)' — point at non-existent files via corrupted paths. This matches anchor 2 (content that belongs in separate files is inlined; references effectively broken) rather than anchor 3, whose references are at least present and usable.

2 / 5

Total

10

/

20

Passed

Description

11%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 frontmatter description is invocation boilerplate that communicates no capability, trigger, or use case, so it would rarely be selected based on user intent. The file compounds the problem with a duplicate second YAML block in the body containing a far more informative description ('GitHub issue-based swarm coordination agent that transforms issues into intelligent multi-agent tasks with automatic decomposition and progress tracking') that never surfaces where descriptions are actually read. The frontmatter description needs to be rewritten as a what-plus-when statement.

Suggestions

Replace the boilerplate frontmatter description with a capability statement — e.g., promote the body's embedded description: 'Transforms GitHub issues into multi-agent swarm tasks with automatic decomposition, agent assignment, and progress tracking.'

Add an explicit 'Use when...' clause with concrete triggers, e.g., 'Use when the user wants to decompose a GitHub issue into agent subtasks, run swarm agents on issues, automate issue triage, or track multi-agent progress on an issue.'

Remove the duplicate second YAML frontmatter block from the body and consolidate name/description into the single top-level frontmatter so parsers and skill listings see one consistent, informative description.

DimensionReasoningScore

Specificity

The description is 'Agent skill for swarm-issue - invoke with $agent-swarm-issue' — the only verb is the meta-instruction 'invoke', and no capability of the skill is stated. It does not reach anchor 2 ('Processes PDF files'), which at least names a domain action, so it matches anchor 1: no concrete actions, pure abstract language.

1 / 5

Completeness

Neither 'what' nor 'when' is answered: the description never states what the skill does and contains no 'Use when...' clause or equivalent trigger guidance. Anchor 1 ('missing both what and when') is the closest match; anchor 2 would require at least a vague 'what', which is absent.

1 / 5

Trigger Term Quality

The only on-topic terms, 'swarm' and 'issue', appear solely embedded inside the skill name 'swarm-issue' and the invocation token '$agent-swarm-issue'; no natural phrases a user would say (e.g., 'GitHub issue', 'multi-agent', 'decompose', 'triage') are present. This fits anchor 2 (one or two generic keywords, missing the natural phrases) rather than anchor 1, since 'swarm'/'issue' are genuine topic words rather than pure jargon.

2 / 5

Distinctiveness Conflict Risk

The pattern 'Agent skill for swarm-issue - invoke with $agent-swarm-issue' is wrapper boilerplate that would read identically for any sibling agent skill, creating high overlap risk; only the proper name 'swarm-issue' provides any distinction. This matches anchor 2 (very broad, high overlap risk with many similar skills) better than anchor 1, whose example is entirely generic content-wise.

2 / 5

Total

6

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (578 lines); consider splitting into references/ and linking

Warning

relative_links

Relative link issues: 3 missing

Warning

Total

14

/

16

Passed

Repository

ruvnet/ruflo

Path

.agents/skills/agent-swarm-issue/SKILL.md

Revision

d000e27

Reviewed

Table of Contents

DiscoveryImplementationValidation

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.

Claim skill