agent-swarm-issue

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

2.93x

Quality

Does it follow best practices?

Impact

97%

2.93x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/agent-swarm-issue/SKILL.md

Quality

Content

12%

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

This skill is an extremely verbose, largely non-actionable document that reads more like a product marketing spec than an executable skill. The vast majority of commands reference a hypothetical 'npx ruv-swarm' CLI tool with no evidence it exists, making the skill unusable in practice. The content is a monolithic wall of speculative features with no validation steps, poor organization, and significant redundancy across sections.

Suggestions

Strip the content down to only commands and workflows that actually work with the declared MCP tools (mcp__github__*, mcp__claude-flow__*) and standard CLI tools (gh), removing all references to the unverifiable 'npx ruv-swarm' tool.

Reduce to a focused overview (under 100 lines) covering the core workflow: fetch issue → analyze → decompose → coordinate agents → update issue, with one concrete end-to-end example using real tool syntax.

Add explicit validation checkpoints in workflows, especially for destructive operations like auto-closing issues and batch processing.

Move detailed examples (GitHub Actions YAML, issue templates, label configs) into separate bundle files and reference them from the main skill with clear one-level-deep links.

Dimension	Reasoning	Score
Conciseness	Extremely verbose at 400+ lines with massive amounts of speculative CLI commands for a tool (ruv-swarm/npx ruv-swarm) that appears hypothetical. Enormous repetition of similar patterns (issue-init, issue-decompose, etc.) with slight variations. Explains concepts Claude already knows (what bug reports are, what feature requests are, label strategies). The best practices and security sections are generic filler.	1 / 3
Actionability	Nearly all commands reference 'npx ruv-swarm' which appears to be a non-existent or undocumented tool, making none of the code executable or verifiable. The MCP tool invocations at the bottom use incorrect syntax (not valid JSON calls). The gh CLI portions are more concrete but are wrapped in fictional pipeline commands. Most content is aspirational rather than actionable.	1 / 3
Workflow Clarity	Some workflows like 'Task Decomposition' and 'Progress Tracking' show reasonable step sequences with bash commands. However, there are no validation checkpoints or error recovery steps in any workflow. The sheer number of disconnected workflow fragments makes it hard to follow any single coherent process. Missing feedback loops for destructive operations like auto-closing stale issues.	2 / 3
Progressive Disclosure	Monolithic wall of text with no meaningful separation of content. Everything is dumped into a single massive file covering issue conversion, templates, automation, metrics, security, examples, and more. References to swarm-pr.md, sync-coordinator.md, and workflow-automation.md exist at the bottom but no bundle files are provided. Content that should be in separate reference files (label automation JSON, GitHub Actions YAML, issue templates) is all inline.	1 / 3
	Total	5 / 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.

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 problem domain it addresses. It reads more like an invocation instruction than a skill description.

Suggestions

Describe what the skill actually does with concrete actions (e.g., 'Triages and assigns issues across multiple agents' or whatever swarm-issue functionality entails).

Add an explicit 'Use when...' clause with natural trigger terms that describe the scenarios where this skill should be selected.

Replace the generic 'Agent skill for swarm-issue' with a domain-specific description that distinguishes this skill from other agent-related 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, not something a user would naturally say. 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' could apply to virtually anything, and 'swarm-issue' is undefined in the description.	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
Commit: 16a55f7

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.