agent-swarm-issue

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

2.93x

Quality

21%

Does it follow best practices?

Impact

97%

2.93x

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

Quality

Content

35%

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 overstuffed, monolithic feature catalog with mostly concrete but frequently non-executable code and no validation checkpoints, capped further by dead bundle-file references that should hold the overflow content.

Suggestions

Trim the body to a lean overview and move the exhaustive feature catalogs (Advanced Features, Metrics & Analytics, Examples, Swarm Coordination Features) into actual bundle files referenced one level deep.

Fix the systematic path/syntax errors that break executability (e.g. '.github$workflows$...' -> '.github/workflows/...', '2>$dev$null' -> '2>/dev/null') and replace pseudocode MCP invocations with real tool-call syntax.

Add explicit validation/verification checkpoints before destructive or batch operations, e.g. confirm before 'gh issue close' in the stale-issue flow.

Dimension	Reasoning	Score
Conciseness	The ~570-line body is a monolithic catalog of speculative feature variants and fabricated-looking 'npx ruv-swarm github ...' commands that massively exceeds the token budget a SKILL.md overview should occupy, matching the 'verbose; padded with unnecessary context' anchor.	1 / 3
Actionability	There is abundant concrete guidance with real 'gh' CLI commands, but much is not actually executable due to systematic errors such as '.github$workflows$issue-swarm.yml' and '2>$dev$null' (broken paths/redirects) and pseudocode MCP invocations like 'mcp__claude-flow__swarm_init { topology: ... }', fitting the 'some concrete guidance but incomplete / pseudocode' anchor.	2 / 3
Workflow Clarity	Multi-step sequences (issue-init, decomposition, progress tracking, stale-issue processing) are present and commented, but destructive/batch operations like the stale-issue auto-close flow lack any validation or verify-before-proceed checkpoint, which per the rubric caps workflow clarity at 2.	2 / 3
Progressive Disclosure	Section headings provide some structure, but content that should live in bundle files (Advanced Features, Metrics & Analytics, Examples, Swarm Coordination Features) is all inline, and the three references at the end point to files that do not exist, so references are present but poorly signaled and broken.	2 / 3
	Total	7 / 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.

The description is boilerplate placeholder text that fails to convey what the skill concretely does or when to use it, relying on a tautological self-reference and invocation syntax instead of capabilities and triggers.

Suggestions

Rewrite the description to state concrete actions, e.g. 'Decompose GitHub issues into parallel subtasks, assign swarm agents, and track progress via issue comments and checklists.'

Add an explicit 'Use when...' trigger clause with natural terms users would say, e.g. 'Use when the user wants to break a GitHub issue into multi-agent subtasks or coordinate swarm work on an issue.'

Drop the 'invoke with $agent-swarm-issue' boilerplate and add distinguishing trigger terms so it does not collide with sibling swarm skills.

Dimension	Reasoning	Score
Specificity	The description 'Agent skill for swarm-issue - invoke with $agent-swarm-issue' names no concrete actions at all; it only labels the skill and gives invocation syntax, matching the 'vague or no actions' anchor rather than the score-2 anchor which at least names some actions.	1 / 3
Completeness	The 'what' is circular/tautological ('agent skill for swarm-issue') and the 'when' is entirely absent with no 'Use when...' clause, so both what and when are very weak, matching the score-1 anchor.	1 / 3
Trigger Term Quality	The only terms are 'swarm-issue' and '$agent-swarm-issue', which are technical jargon / invocation syntax a user would not naturally say; there are no natural keywords like 'GitHub issues', 'decompose', 'subtasks', or 'multi-agent'.	1 / 3
Distinctiveness Conflict Risk	'swarm-issue' names a specific niche, but the templated 'Agent skill for X - invoke with $X' boilerplate and total absence of distinguishing trigger terms means it could overlap with the sibling swarm skills referenced in the body (swarm-pr, sync-coordinator, workflow-automation).	2 / 3
	Total	5 / 12 Passed

Validation

87%

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 — 14 / 16 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
relative_links	Relative link issues: 3 missing	Warning

	Total	14 / 16 Passed

Repository: ruvnet/ruflo
Path: .agents/skills/agent-swarm-issue/SKILL.md
Commit: 26c35b5

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