Swarm Skill

Autonomous multi-agent workflow system for complex coding tasks.

Installation

1. Add the marketplace:

   /plugin marketplace add nbashaw/swarm
   

2. Install the skill:

   /plugin install swarm@nbashaw-swarm
   

That’s it! Claude will automatically load the skill when you request non-trivial coding tasks.

What It Does

When invoked for non-trivial coding tasks, this skill:

1. Interviews the user to gather requirements
2. Creates a structured markdown plan with review gates
3. Spawns autonomous agents to execute the plan
4. Reports completion when agents finish

Development Workflow

This repo uses a symlinked development setup for rapid iteration.

Setup (Already Done)

~/.claude/skills/swarm -> ~/dev/swarm-skill/swarm

The installed skill is symlinked to your dev directory. Changes are live immediately!

Daily Workflow

1. Edit files directly:

# Edit the skill
vim swarm/SKILL.md

# Edit the plan template
vim swarm/assets/PLAN_TEMPLATE.md

2. Test immediately: Your changes are live! Just start a new Claude Code session and test:

claude
# Then: "Refactor the auth module" (or any non-trivial task)

3. Commit when happy:

git add .
git commit -m "Improve interview questions"
git push

File Structure

swarm-skill/
├── README.md                      # This file
├── release.sh                     # Package for distribution
├── .gitignore                     # Git ignore rules
└── swarm/                         # The actual skill (symlinked)
    ├── SKILL.md                   # Skill instructions
    └── assets/
        ├── PLAN_TEMPLATE.md       # Plan template
        ├── swarm.sh               # Swarm runner script
        └── test_swarm.sh          # Test script for swarm.sh

Releasing

When ready to share the skill with others:

./release.sh

This creates swarm.skill in the repo root that others can install.

Running the Swarm

The swarm.sh script executes autonomous agents in a loop until the plan is complete.

Basic usage:

./swarm/assets/swarm.sh .context/YOUR_PLAN.md

Available flags:

• -n, --dry-run - Show what would happen without executing claude
• -v, --verbose - Print logs, timing, and plan summary after each iteration
• -h, --help - Show help message

Examples:

# Run with verbose output
./swarm/assets/swarm.sh --verbose .context/refactor_plan.md

# Test without running (dry run)
./swarm/assets/swarm.sh --dry-run .context/feature_plan.md

# Combine flags
./swarm/assets/swarm.sh -v -n .context/test_plan.md

Environment variables:

• MAX_ITERATIONS - Maximum iterations before stopping (default: 20)

MAX_ITERATIONS=50 ./swarm/assets/swarm.sh .context/big_task.md

Testing Tips

Quick test: Ask Claude to set up a simple refactoring task

"Refactor the test utils to use async/await"

Full test: Use a real multi-file feature

"Add JWT authentication to the API with tests"

Check the plan: After Claude creates the plan, review it before execution

• Are phases clearly defined?
• Are review gates in place?
• Is the Gatekeeper checklist specific?

Verify swarm.sh: Test the runner script with the test suite

./swarm/assets/test_swarm.sh

Troubleshooting

Skill not triggering?

• Check the description in SKILL.md frontmatter (that’s the trigger)
• Ensure your task is “non-trivial” (multi-step, multiple files)

Changes not appearing?

• Verify symlink: ls -la ~/.claude/skills/swarm
• Should show: swarm -> /Users/nbaschez/dev/swarm-skill/swarm

Want to test fresh?

• Start new Claude session: claude
• Old sessions cache the skill content

Git Workflow

# Feature development
git checkout -b improve-interview-flow
# ... make changes ...
git commit -m "Add more clarifying questions"
git push origin improve-interview-flow

# After review/testing
git checkout main
git merge improve-interview-flow
./release.sh  # Create distributable

Ideas for Iteration

• Add more examples to SKILL.md
• Refine the interview questions
• Improve the plan template structure
• Add specialized plan templates for common tasks (refactoring, testing, migration)
• Adjust review gate frequencies
• Enhance Gatekeeper checklist items