Content
7%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, marketing-style document that reads more like aspirational product documentation than actionable Claude instructions. The commands appear fabricated with no evidence of being executable, and critical safety concerns (auto-merging, pushing changes) lack validation steps. The content could be reduced by 80%+ while improving clarity by focusing on actual working commands and real workflows.
Suggestions
Reduce content to under 100 lines focusing only on what Claude needs to know that it doesn't already—remove all marketing bullets, obvious security check lists, and redundant sections
Replace speculative 'npx ruv-swarm' commands with actual executable workflows using real tools (gh CLI, existing linters, etc.) or clearly document that ruv-swarm must be installed and link to its actual documentation
Add explicit validation checkpoints to workflows, especially before destructive operations like auto-merge and push-changes (e.g., 'verify CI passes before merging', 'review generated comments before posting')
Split the monolithic file into focused sub-files (e.g., SECURITY-REVIEW.md, GITHUB-ACTIONS.md, CUSTOM-AGENTS.md) and keep SKILL.md as a concise overview with clear references
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 700+ lines with massive redundancy (the 'Multi-Agent Review System' section repeats the Quick Start nearly verbatim). Includes extensive marketing-style bullet points ('✅ Parallel review by specialized agents'), emoji decoration, JSON schemas listing obvious checks Claude already knows (e.g., 'SQL injection vulnerabilities', 'XSS attack vectors'), and sections like License/Last Updated that waste tokens. Much of the content is aspirational feature documentation rather than actionable instruction. | 1 / 3 |
Actionability | Despite containing many code blocks, the commands reference a tool ('npx ruv-swarm') with invented CLI flags that appear fabricated and non-executable. There's no evidence these commands actually work—they read like speculative API design rather than tested, copy-paste-ready instructions. The bash scripts have issues (e.g., using $REVIEW_OUTPUT outside the step where it was defined in the GitHub Actions workflow). The skill describes rather than instructs. | 1 / 3 |
Workflow Clarity | Despite being a complex multi-step process involving destructive operations (auto-merging PRs, pushing changes), there are no validation checkpoints or feedback loops. The 'Complete Workflow Examples' are just single commands with no sequencing. The auto-merge script lacks safety checks beyond a simple review count. No error recovery patterns are defined for when agents fail or produce incorrect results. | 1 / 3 |
Progressive Disclosure | Uses HTML details/summary tags for collapsible sections which provides some structure, and references related skills at the bottom. However, with no bundle files provided, all content is monolithically inlined in a single massive file. The Table of Contents with anchor links provides navigation but the sheer volume of inline content (configuration examples, custom agent code, workflow YAML, webhook handlers) should be split into separate files. | 2 / 3 |
Total | 5 / 12 Passed |