agent-swarm-issue

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

2.93x

Quality

28%

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

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 a sprawling, monolithic command dump with a duplicated frontmatter block, corrupted path syntax, and dead cross-references. It offers a rough sense of the intended workflows but no reliably executable guidance and no validation before destructive batch operations.

Suggestions

Remove the duplicated second YAML frontmatter block and trim the body to the core workflow (init → decompose → track), moving the per-issue-type command catalogs (bug/feature/debt/epic/milestone swarms) into separate reference files that actually exist.

Fix corrupted syntax — "$" used for "/" in paths like "2>$dev$null" and ".github$workflows$issue-swarm.yml" — and replace MCP-call pseudocode with real, executable invocations.

Add validation checkpoints before destructive batch operations: verify a candidate issue is truly stale/inactive before closing, and confirm duplicate confidence before "--close-duplicates".

Dimension	Reasoning	Score
Conciseness	The body is ~540 lines of padded command-catalog material: dozens of near-duplicate "npx ruv-swarm github ..." variations (issue-init, bug-swarm, feature-swarm, debt-swarm, epic-swarm, milestone-swarm, cross-repo), plus a duplicated second YAML frontmatter block that adds pure noise. It is beyond anchor 2's "several unnecessary or padded sections" but does not explain known concepts the way anchor 1's example does, so it lands at 2.	2 / 5
Actionability	Many gh CLI blocks look executable, but key examples are pseudocode or corrupted: "mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 8 }" is not valid syntax, and paths are broken by "$" standing in for "/" ("2>$dev$null", ".github$workflows$issue-swarm.yml", "org$repo#456"). This matches anchor 3 (some concrete guidance but incomplete; pseudocode instead of executable code), below anchor 4 because the corruption and invented CLI surface prevent copy-paste execution.	3 / 5
Workflow Clarity	Sequences exist for issue-to-swarm, decomposition, and progress tracking, but there are no validation checkpoints, and destructive batch operations appear without verification — auto-closing stale issues ("gh issue close $num"), "--close-duplicates", and bulk body rewrites edit issues in place with no verify step. Per the guidelines, missing validation in destructive/batch workflows caps this at 3; it is not a 2 because the step ordering itself is readable.	3 / 5
Progressive Disclosure	No bundle files exist (no references/, scripts/, or assets/ directories), yet the monolithic body inlines what is clearly reference material, and its only pointers — "See also: swarm-pr.md, sync-coordinator.md, workflow-automation.md" — target files that do not exist. This fits anchor 2 (content that clearly belongs in separate files is inlined; references buried/broken); it reaches not 3 because the inline bulk is extreme and the navigation links are dead.	2 / 5
	Total	10 / 20 Passed

Description

17%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 description is a placeholder-quality invocation string rather than a capability description: it names the domain but states no actions, no natural trigger terms, and no usage conditions. It would rarely be selected correctly and would conflict with other agent-orchestration skills.

Suggestions

State concrete capabilities in third person, e.g. "Decomposes GitHub issues into multi-agent swarm tasks: converts issues to task checklists, assigns agents by issue type, and posts progress updates as issue comments."

Add an explicit trigger clause: "Use when working with GitHub issues that need multi-agent decomposition, triage, or swarm-based tracking."

Replace the "$agent-swarm-issue" invocation syntax with natural trigger terms users would actually say (GitHub issue, issue triage, task decomposition, multi-agent coordination).

Dimension	Reasoning	Score
Specificity	The description only says "Agent skill for swarm-issue - invoke with $agent-swarm-issue" — it names a domain (swarm-issue) but lists zero concrete capabilities (no decomposition, no issue tracking, no agent coordination). It sits between anchor 1 (no concrete actions at all) and anchor 2 (domain named, actions minimal/generic); the bare invocation hint keeps it just above entirely vague.	2 / 5
Completeness	The "what" is extremely vague ("Agent skill for swarm-issue") and the "when" is entirely missing — no "Use when..." clause or equivalent trigger guidance, which also caps this dimension at 3 per the guidelines. This matches anchor 2 (vague 'what' and no 'when') exactly; it is above anchor 1 only because a recognizable domain name is stated.	2 / 5
Trigger Term Quality	There are no natural keywords a user would say — no "GitHub issue", "issue triage", "task decomposition", or "multi-agent". The only terms are the technical jargon token "$agent-swarm-issue" and the generic words "agent" and "skill", matching anchor 1 (only technical jargon or entirely generic language). It is not a 2 because even the generic-keyword bar of "Works with files" style phrasing is absent.	1 / 5
Distinctiveness Conflict Risk	"Agent skill for swarm-issue" is a meta-description that could match any agent-style skill; nothing in it distinguishes this skill from other swarm/agent/automation skills. It fits anchor 2 (very broad, high overlap risk) rather than anchor 3 because no differentiating capability or trigger is stated at all.	2 / 5
	Total	7 / 20 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: b14c79e

Reviewed: 3 days 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.