Skill System

Core Insight: A skill is not a tool — it's a bundle of related tools, documentation, and behavior rules packaged as a single capability. The skill system turns "100 tools crammed into every prompt" into "a menu of capabilities loaded on demand," saving thousands of tokens and dramatically improving tool selection accuracy.

What is a Skill?

A tool is a single function the model can call. A skill is a packaged capability that bundles:

Tools — one or more related function schemas and handlers
Documentation — a SKILL.md file explaining when and how to use the skill
Behavior rules — constraints, patterns, and conventions for the model to follow

skill/
├── SKILL.md          # Documentation: when to use, how to use, constraints
├── tools.py          # Tool implementations
└── schema.json       # Tool schemas (or generated from code)

For example, a git skill doesn't expose a single git tool — it bundles git_status, git_diff, git_commit, git_push, git_log, and includes documentation on commit message conventions, branch naming, and when to ask before pushing.

Skill vs. Tool

	Tool	Skill
Scope	Single function	Bundle of related functions
Documentation	Parameter description	Full SKILL.md with examples, conventions
Loading	Always present or absent	Loaded on demand from a menu
Context cost	~100–200 tokens per schema	~200 token menu entry + ~1,000 tokens when loaded
Behavior rules	None	Can include constraints, workflows, patterns

The distinction matters for token economics. A harness with 80 tools pays ~12,000 tokens per API call just for schemas. A skill system with 15 skills and a 300-token menu loads only what's needed.

SKILL.md Format

The SKILL.md file is the skill's instruction manual. The model reads it when the skill is loaded:

# Git Operations

## When to Use
- User asks to check, commit, or push code changes
- You need to inspect file history or diffs
- Resolving merge conflicts

## Available Tools
- `git_status` — Show working tree status
- `git_diff` — Show changes (staged or unstaged)
- `git_commit` — Commit staged changes with a message
- `git_push` — Push commits to remote
- `git_log` — Show recent commit history

## Conventions
- Always run `git_status` before committing
- Use conventional commit messages (feat:, fix:, docs:)
- Never force-push without explicit user approval
- Commit message should be under 72 characters

## Examples
To commit and push:
1. `git_status` → review what's changed
2. `git_diff` → verify the changes are correct
3. `git_commit("feat: add user auth middleware")`
4. `git_push`

This format gives the model enough context to use the skill correctly without embedding all that knowledge in tool descriptions.

Instead of loading all tools at startup, present the model with a compact menu of available skills. The model reads the menu, decides which skill it needs, and loads it:

SKILL_MENU = """Available skills (use load_skill to activate):

- file_ops: Read, write, search, and edit files in the workspace
- git: Version control — status, diff, commit, push, log
- web: HTTP requests, web search, URL fetching
- shell: Execute shell commands in a sandbox
- database: SQL queries, schema inspection, migrations
- calendar: Create events, check availability, manage schedules
- email: Read inbox, send emails, search messages
- image: Generate and analyze images
"""

The menu costs ~150 tokens. Loading a skill adds its SKILL.md (~500–1,000 tokens) and tool schemas (~200–800 tokens). Compared to loading all tools upfront:

Strategy                    Tokens (8 skills, ~60 tools)
────────────────────────────────────────────────────────
All tools upfront:          ~12,000 tokens (always)
Skill menu + 2 loaded:      ~150 + ~2,400 = ~2,550 tokens
────────────────────────────────────────────────────────
Savings:                    ~9,450 tokens per turn (78%)

Over a 30-turn session, that's ~280K tokens saved — real money at API pricing.

Skill Registry Implementation

import json
from pathlib import Path
from dataclasses import dataclass, field

@dataclass
class Skill:
    name: str
    description: str
    doc: str                           # Contents of SKILL.md
    tools: list[dict] = field(default_factory=list)        # Tool schemas
    handlers: dict = field(default_factory=dict)            # name → callable

class SkillRegistry:
    """Registry with on-demand skill loading."""

    def __init__(self, skills_dir: str):
        self.skills_dir = Path(skills_dir)
        self._catalog: dict[str, Skill] = {}
        self._active: dict[str, Skill] = {}
        self._scan()

    def _scan(self):
        """Scan the skills directory and build the catalog."""
        for skill_dir in self.skills_dir.iterdir():
            if not skill_dir.is_dir():
                continue
            skill_md = skill_dir / "SKILL.md"
            schema_file = skill_dir / "schema.json"
            if not skill_md.exists():
                continue

            doc = skill_md.read_text()
            # Extract first line after "# " as description
            first_heading = ""
            for line in doc.splitlines():
                if line.startswith("# "):
                    first_heading = line[2:].strip()
                    break

            schemas = []
            if schema_file.exists():
                schemas = json.loads(schema_file.read_text())

            self._catalog[skill_dir.name] = Skill(
                name=skill_dir.name,
                description=first_heading,
                doc=doc,
                tools=schemas,
            )

    def get_menu(self) -> str:
        """Generate the skill menu for the model."""
        lines = ["Available skills (use load_skill to activate):\n"]
        for name, skill in self._catalog.items():
            status = " [loaded]" if name in self._active else ""
            lines.append(f"- {name}: {skill.description}{status}")
        return "\n".join(lines)

    def load_skill(self, name: str) -> str:
        """Load a skill, making its tools available."""
        if name not in self._catalog:
            return f"Error: Unknown skill '{name}'. Check the skill menu."
        if name in self._active:
            return f"Skill '{name}' is already loaded."

        skill = self._catalog[name]
        self._active[name] = skill
        tool_names = [t["name"] for t in skill.tools]
        return (
            f"Loaded skill '{name}' with {len(skill.tools)} tools: "
            f"{', '.join(tool_names)}\n\n"
            f"Documentation:\n{skill.doc}"
        )

    def unload_skill(self, name: str) -> str:
        """Unload a skill to free up context space."""
        if name not in self._active:
            return f"Skill '{name}' is not loaded."
        del self._active[name]
        return f"Unloaded skill '{name}'."

    def get_active_schemas(self) -> list[dict]:
        """Return tool schemas for all currently loaded skills."""
        schemas = []
        for skill in self._active.values():
            schemas.extend(skill.tools)
        # Always include the meta-tools
        schemas.append({
            "name": "load_skill",
            "description": "Load a skill by name to activate its tools",
            "parameters": {
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "Skill name from the menu"}
                },
                "required": ["name"],
            },
        })
        return schemas

    def dispatch(self, tool_name: str, arguments: dict) -> str:
        """Dispatch a tool call to the appropriate skill handler."""
        if tool_name == "load_skill":
            return self.load_skill(arguments["name"])

        for skill in self._active.values():
            if tool_name in skill.handlers:
                try:
                    return str(skill.handlers[tool_name](**arguments))
                except Exception as e:
                    return f"Error: {type(e).__name__}: {e}"

        return f"Error: Tool '{tool_name}' not found. Is the skill loaded?"

Thin Harness + Thick Skills

The architecture principle: the harness should be thin — just the agentic loop, context assembly, and skill registry. All domain-specific intelligence lives in skills:

┌─────────────────────────────────────────────────┐
│  Harness (thin)                                  │
│  ┌──────────┐  ┌───────────┐  ┌──────────────┐ │
│  │ Agentic  │  │  Context   │  │    Skill     │ │
│  │  Loop    │  │ Assembler  │  │  Registry    │ │
│  └──────────┘  └───────────┘  └──────────────┘ │
└─────────────────────┬───────────────────────────┘
                      │ loads on demand
     ┌────────────────┼────────────────┐
     ▼                ▼                ▼
┌─────────┐    ┌───────────┐    ┌───────────┐
│  git    │    │  file_ops  │    │  web      │
│  skill  │    │  skill     │    │  skill    │
└─────────┘    └───────────┘    └───────────┘

This separation has practical benefits:

Skills are portable — a skill written for one harness works in another
Skills are testable — test tools and schemas in isolation
Skills are composable — the model discovers how to combine loaded skills naturally
The harness stays simple — add capabilities by adding skills, not by modifying the core

Common Pitfalls

Loading all skills at startup — Defeats the purpose of the skill system. Use the menu pattern and load on demand.
Monolithic skills — A "do-everything" skill with 30 tools is just the all-tools-upfront problem in disguise. Keep skills focused: 3–8 tools each.
Missing SKILL.md — Tools without documentation force the model to guess at conventions. The SKILL.md is not optional; it's the skill's brain.
No unload mechanism — If the model loads five skills and can't unload them, context fills up fast. Always provide unload_skill alongside load_skill.
Confusing skill and tool names — If a skill is named git and contains a tool named git, the model may try to call the skill name as a tool. Use distinct naming: skill git, tools git_status, git_diff, etc.