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.

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

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