Skills System Deep-Dive

The Skills System (skills.go) provides a declarative skill definition system that injects specialized capabilities into AntFarm workers and team members.

🎯 Overview

Skills are JSON manifests that define:

• What capabilities a worker receives
• Which tools are enabled
• How the worker should be configured

📁 Structure

Skill Manifest (JSON)

{
  "skill_id": "webdev",
  "name": "Web Development",
  "description": "Full-stack web development with Go and React",
  "version": "1.0.0",
  "category": "development",
  "required_tools": [
    "pm_write_file",
    "pm_shell",
    "pm_grep"
  ],
  "swarm_config": {
    "default_ants": 3,
    "max_parallel_ants": 5,
    "model_tier_preference": "mid-range"
  },
  "injections": {
    "system_prompt_suffix": "You are a web developer specializing in Go and React...",
    "context_variables": {
      "framework": "standard",
      "testing": "required"
    },
    "tool_examples": [
      {
        "tool": "pm_write_file",
        "description": "Create or modify source files",
        "example": "pm_write_file(filename=\"main.go\", content=\"package main\\n...\")"
      }
    ]
  }
}

🔧 Key Components

skills.go

• SkillManifest: JSON struct for skill definition
• SwarmConfiguration: AntFarm worker config
• SkillInjections : Prompt and tool injections
• SkillCatalog: Global registry of all skills
• LoadSkillCatalog(): Load skills from disk
• InjectSkillIntoSession(): Apply skill to worker

📂 Skill Directory

Skills are stored in:

assistant/skills/
├── webdev.json
├── data-analyst.json
├── security-red-teamer.json
├── network-engineer.json
└── ... (92+ total)

🚀 Skill Injection Flow

1. Worker spawns with skill_id
   ↓
2. LoadSkillCatalog() loads all skills
   ↓
3. GetSkill(skill_id) retrieves manifest
   ↓
4. InjectSkillIntoSession():
   - Set ShortTerm("active_skill", skillID)
   - Set ShortTerm("skill_prompt_suffix", injections.SystemPromptSuffix)
   - Load required_tools (cross-hive tools enabled)
   - Override model_tier_preference
   ↓
5. Worker executes with skill context

🎛️ Swarm Configuration

🛠️ Cross-Hive Tool Access

Skills enable cross-hive tool access:

• Default: Workers only access pm_* (AntFarm) tools
• Skill-enabled: Workers get pm_* + bm_* (Business) + existing tools
• This allows specialized workers to use appropriate tools from different hives

📋 Key Functions

🎯 Usage with AntFarm

// Spawn worker WITH skill
session, err := NewProjectWorkerSession(
    "worker",           // worker type
    "project-abc",      // workspace
    "queen-123",       // parent session
    "webdev",          // skill_id ← enables webdev capabilities
)

// The worker now has:
// - System prompt: webdev-specific suffix
// - Tools: pm_write_file, pm_shell, pm_grep (from required_tools)
// - Model: mid-range (from swarm_config.model_tier_preference)

📋 Skill Categories

🔍 Finding Skills

Use MatchSkillsForMission() for AI-driven skill matching:

matches, _ := MatchSkillsForMission(
    "Build a secure API endpoint",  // mission
    "Backend security",             // role description
)
// Returns: ["security-red-teamer", "backend"]

📂 Related Documentation

• AntFarm Swarm — Worker execution system
• Dynamic Skill Injection — Runtime skill loading
• Skill Prerequisites — Dependency system

🆕 Custom Skill Scoping (June 2026)

A multi-commit pass (commits 14590034 → 115734d7, plus design doc skills_scoping_design.md) introduced owned / scoped custom skills: skills that belong to a creator or an agent rather than the global catalog, with fine-grained visibility and activation rules. This complements the original AntFarm skills above and does not change InjectSkillIntoSession semantics for global skills.

Scopes

Lifecycle Hooks

New Tool: create_skill

Commit 014a5526 introduced the create_skill tool:

• Writes a scoped custom skill JSON manifest to the appropriate directory based on caller scope/ownership.
• Auto-activates the skill for the current session so the LLM doesn't need a follow-up activate_skill call.
• Registers the skill for subsequent skill_lookup discovery.
• RBAC still applies afterwards — the skill only augments tools, it cannot bypass role gates (see 8fa2070b).

skill_lookup Enhancements

Two follow-up commits extended skill_lookup:

Docs updated in bb1715d5 (skill_lookup.md documents the activate action and custom-skill columns).

🛡️ RBAC Hardening

Commit 8fa2070b removed the blanket RBAC bypass that previously fired whenever a skillID was present in NewChatSession. Skills now only augment tools (add required_tools, inject prompts); role checks always apply to the resulting toolset. This closes the path where a custom skill could trivially hand an agent infrastructure-only tools.

📝 Design Doc & Tracker

• assistant/prompts/tools/skills_scoping_design.md — full design + progress tracker + delegation notes (commits 14590034, 87827be8, 4c3c092f, 2dbccdf7, b04158f9).
• Nikki persona (nikki.md) gained custom-skill mastery guidance in 18ca5341.
• create_skill.md clarified in b04158f9.

📚 Related Commits (chronological)

🔗 Additional Documentation

• assistant/prompts/tools/skills_scoping_design.md (in-repo) — Full design doc