Content
20%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 aspirational document that describes a comprehensive GitHub project management system built around a seemingly fictional 'ruv-swarm' CLI tool. The vast majority of commands are not executable, making the skill more of a product specification than actionable guidance. While it demonstrates good structural ideas (collapsible sections, a complete workflow example), the sheer volume of speculative content and lack of real, executable instructions severely undermines its utility as a skill file.
Suggestions
Remove or drastically reduce all 'npx ruv-swarm' commands unless the tool actually exists and is installable — replace with real gh CLI commands, GitHub Actions workflows, or MCP tool calls that Claude can actually execute.
Reduce the skill to under 150 lines focusing on the core actionable workflows: issue creation with gh CLI, project board management with gh project commands, and a single end-to-end workflow example with validation steps.
Move templates (bug report, feature request, integration issue) into separate bundle files and reference them from the main SKILL.md.
Add explicit validation checkpoints to batch operations (e.g., 'verify issue count before bulk close', 'dry-run sync before bidirectional update') to prevent destructive mistakes.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 700+ lines. Massive amounts of speculative CLI commands for a tool (ruv-swarm) that appears to be hypothetical. Includes extensive templates, dashboard JSON configs, and repetitive patterns that bloat the content enormously. Many sections explain obvious concepts (what a bug report template looks like, what KPIs are). The skill could be reduced to 20% of its size without losing actionable information. | 1 / 3 |
Actionability | Nearly all commands reference 'npx ruv-swarm github ...' which appears to be a fictional/unreleased tool with invented CLI flags. The commands are not executable or verifiable. The JavaScript blocks use pseudo-syntax for MCP calls (e.g., 'mcp__claude-flow__swarm_init { topology: "star" }') that isn't valid code. The gh CLI commands are real but represent a small fraction of the content. Most of this is aspirational rather than actionable. | 1 / 3 |
Workflow Clarity | The 'Complete Workflow Example' section at the end provides a numbered sequence (create issue → init swarm → add to board → sync → monitor), which shows some workflow structure. However, there are no validation checkpoints, no error handling steps, and no feedback loops for the many destructive/batch operations described (bulk close stale issues, cross-org sync, data recovery). The individual sections are disconnected feature showcases rather than coherent workflows. | 2 / 3 |
Progressive Disclosure | Uses HTML <details> tags to collapse sections, which is a reasonable progressive disclosure technique. However, there are no bundle files to reference, and the skill itself is monolithic — all content is inline in one massive file. The references to external resources at the bottom are external URLs, not structured bundle files. The issue templates and workflow configs could easily be separate files. | 2 / 3 |
Total | 6 / 12 Passed |