# Skill Swarm

> This skill should be used when the agent needs to "find a skill", "install a skill", "search for tools", "what skills do I have", "cherry-pick context from a skill", "extract a section from a skill", "manage agent skills", or when a task requires capabilities not currently available and the agent considers searching for a pre-built skill instead of building from scratch. Acts as the decision protocol for the skill-swarm MCP server tools.

- Skill: `ancrz/skill-swarm` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ancrz/skill-swarm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ancrz/skill-swarm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ancrz (https://skillmd.com/u/ancrz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ancrz/skill-swarm

---


# Skill Swarm — Agent Skill Discovery and Management

This skill acts as the decision controller for the skill-swarm MCP server. It guides the reasoning process for deciding when and how to search, install, and extract context from skills.

## Decision Protocol

When facing a task, follow this decision tree before proceeding:

### Query Format

Always pass **keywords**, not sentences. The system normalizes input but works best with concise terms.

| Good | Bad |
|---|---|
| `"docker deploy"` | `"I need to deploy containers with Docker"` |
| `"pdf parsing"` | `"How do I parse PDF files?"` |
| `"nextjs, react"` | `"I want to build a Next.js app with React"` |

### Step 1: Check Local Skills

Call `match_skills(task_description)` with **keywords** describing the task (e.g. `"docker deploy"`, `"pdf parsing"`).

- If a result returns with `relevance_pct >= 60%` → use that skill directly
- If a result returns with `30% <= relevance_pct < 60%` → consider `cherry_pick_context` to extract only the relevant sections
- If no results or all below 30% → proceed to Step 2

### Step 2: Search Remote Registries

Call `search_skills(query, scope="remote")` with keywords describing the needed capability.

- Evaluate results by description relevance and source trustworthiness
- Smithery results (curated MCP servers) are generally higher trust
- GitHub results require more evaluation of the repository quality

### Step 3: Install or Skip

If a suitable remote skill is found:
- Call `install_skill(name, source, agents="claude,agy,codex")` to install globally
- The installation pipeline handles security scanning automatically
- If the scan fails, the skill is NOT installed (blocked)
- After installation, the skill is available to all configured agents via symlinks

If no suitable skill is found:
- Proceed with the model's built-in knowledge (this is the natural fallback)
- Do not burn tokens on excessive searching — two search attempts maximum

### Step 4: Cherry-Pick When Needed

When only a specific procedure or reference from a skill is needed:

Call `cherry_pick_context(skill_name, sections="Section Name 1,Section Name 2")`

This extracts only the requested sections without loading the entire skill into context. Analogous to `git cherry-pick` — take only what is relevant.

## Architecture

### Global Installation with Symlinks

Skills are installed once to `~/.agents/skills/` (source of truth and Codex user scope) and served to other clients via symlinks:

```
~/.agents/skills/              ← Source of truth; native Codex user scope
├── {skill-name}/
│   └── SKILL.md

~/.claude/skills/              ← Symlink for Claude
├── {skill-name} → ~/.agents/skills/{skill-name}

~/.gemini/config/skills/       ← Current global symlink for agy
├── {skill-name} → ~/.agents/skills/{skill-name}

~/.gemini/antigravity-cli/skills/ ← agy migration-compatible symlink
├── {skill-name} → ~/.agents/skills/{skill-name}
```

### MCP Tools Available

| Tool | Purpose |
|---|---|
| `match_skills` | Score local skills against task (first step) |
| `search_skills` | Search local + remote registries |
| `install_skill` | Download, scan, install, symlink |
| `uninstall_skill` | Remove skill + symlinks |
| `list_skills` | Inventory with health status |
| `get_skill_info` | Full content + metadata |
| `cherry_pick_context` | Extract specific sections |

### Security

All installations pass through a pattern-based security scanner. Skills containing command injection, code execution, credential harvesting, or data exfiltration patterns are automatically blocked.

## Anti-Patterns

- Do NOT search more than twice for the same capability
- Do NOT install skills that duplicate existing local skills
- Do NOT load entire skills when only one section is needed (use cherry-pick)
- Do NOT bypass security scan failures

## Additional Resources

### Reference Files

For detailed protocols and patterns, consult:
- **`references/discovery-protocol.md`** — Complete search and evaluation workflow
- **`references/cherry-pick-patterns.md`** — Partial context extraction strategies
- **`references/trusted-registries.md`** — Registry sources, APIs, and trust levels