agent-swarm-issue

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

2.93x

Quality

10%

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

20%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill is excessively verbose and largely non-actionable, relying heavily on a hypothetical 'npx ruv-swarm' CLI tool that appears fictional. It covers an enormous surface area (issue triage, stale issue handling, duplicate detection, epic management, cross-repo coordination, metrics, etc.) without providing executable, verifiable guidance for any single workflow. The content reads more like a product specification or wishlist than an actionable skill for Claude.

Suggestions

Remove or replace all 'npx ruv-swarm' commands with actual executable tools (gh CLI, MCP tools listed in frontmatter, or bash scripts) that Claude can realistically use.

Reduce content by 70%+ by focusing on one core workflow (e.g., 'analyze issue → decompose into subtasks → track progress') with concrete, executable steps and validation checkpoints.

Fix MCP tool call syntax to use proper JSON format and show realistic, executable examples of the tools listed in the frontmatter.

Move specialized topics (GitHub Actions integration, stale issue handling, duplicate detection, metrics) into separate referenced files to keep SKILL.md as a concise overview.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at 400+ lines with massive redundancy. Many sections repeat similar CLI patterns (issue-init, issue-decompose, etc.) with slight variations. Includes extensive hypothetical tool commands (npx ruv-swarm) that Claude cannot verify or execute, and explains concepts like issue templates, label strategies, and best practices that are general knowledge. The content could be reduced by 70%+ without losing actionable information.	1 / 3
Actionability	Nearly all commands reference a hypothetical 'npx ruv-swarm' CLI tool with no indication it exists or how to install it. The bash scripts mix real gh CLI commands with fictional tool invocations, making them non-executable. MCP tool calls at the bottom use incorrect syntax (not valid JSON arguments). The skill describes an aspirational system rather than providing concrete, executable guidance.	1 / 3
Workflow Clarity	Some workflows like 'Task Decomposition' and 'Progress Tracking' show reasonable step sequences with gh CLI commands. However, there are no validation checkpoints or error recovery steps in any workflow. The overall structure jumps between many different use cases (bug handling, feature requests, stale issues, duplicates, etc.) without a clear primary workflow, making it hard to follow a coherent process.	2 / 3
Progressive Disclosure	References to related files (swarm-pr.md, sync-coordinator.md, workflow-automation.md) exist at the bottom, but no bundle files are provided to verify them. The content itself is a monolithic wall covering too many topics inline (issue templates, label automation, GitHub Actions, metrics, security, best practices) that should be split into separate reference files. The structure has sections but lacks a concise overview pointing to details elsewhere.	2 / 3
	Total	6 / 12 Passed

Description

0%Scale 1-3

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 domain it operates in. It reads as a placeholder rather than a functional description.

Suggestions

Add a clear explanation of what 'swarm-issue' actually does — list specific concrete actions (e.g., 'Creates, triages, and assigns issues across multiple repositories').

Add an explicit 'Use when...' clause with natural trigger terms that users would actually say (e.g., 'Use when the user asks about creating issues, triaging bugs, or managing tasks across projects').

Replace the invocation instruction ('invoke with $agent-swarm-issue') with domain-specific context that distinguishes this skill from other agent or issue-management skills.

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 unlikely to be naturally used by users. 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

Validation

90%

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 — 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
Path: .agents/skills/agent-swarm-issue/SKILL.md
Commit: 913f9ea

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.