v4: Skills Mechanism

# skills/company-standards/SKILL.md
---
name: company-standards
description: Company code standards and best practices
---

## Naming Conventions
- Function names use lowercase_with_underscores
- Class names use PascalCase
...

---
name: pdf
description: Process PDF files. Use for reading, creating, or merging PDFs.
---

# PDF Processing Skills

## Reading PDFs

Use pdftotext for quick extraction:
\`\`\`bash
pdftotext input.pdf -
\`\`\`
...

#!/usr/bin/env python3
"""
v4_skills_agent.py - Mini Claude Code: Skills Mechanism (~550 lines)

Core Philosophy: "Knowledge Externalization"
============================================
v3 gave us subagents for task decomposition. But there's a deeper question:

    How does the model know HOW to handle domain-specific tasks?

The Paradigm Shift: Knowledge Externalization
--------------------------------------------
Traditional AI: Knowledge locked in model parameters
  - To teach new skills: collect data -> train -> deploy
  - Cost: $10K-$1M+, Timeline: Weeks

Skills: Knowledge stored in editable files
  - To teach new skills: write a SKILL.md file
  - Cost: Free, Timeline: Minutes
"""

import os
import re
import subprocess
import sys
from pathlib import Path

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv(override=True)


# =============================================================================
# Configuration
# =============================================================================

WORKDIR = Path.cwd()
SKILLS_DIR = WORKDIR / "skills"
client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
MODEL = os.getenv("MODEL_ID", "claude-sonnet-4-5-20250929")


# =============================================================================
# SkillLoader - The core addition in v4
# =============================================================================

class SkillLoader:
    """
    Manages loading and parsing of skill files.

    Key Design Decisions:
    --------------------
    1. Progressive disclosure: Metadata always loaded, body on demand
    2. Standard format: YAML frontmatter + Markdown body
    3. File-based: Git-friendly, human-readable, editable
    """

    def __init__(self, skills_dir: Path):
        self.skills_dir = skills_dir
        self.skills = {}
        self.load_skills()

    def load_skills(self):
        """Discover and load all skill metadata."""
        if not self.skills_dir.exists():
            return

        for skill_path in self.skills_dir.glob("*/SKILL.md"):
            skill = self.parse_skill_md(skill_path)
            if skill:
                self.skills[skill["name"]] = skill

    def parse_skill_md(self, path: Path) -> dict:
        """
        Parse YAML frontmatter + Markdown body.

        Returns:
            {name, description, body, path, dir}
        """
        content = path.read_text()

        # Match YAML frontmatter
        match = re.match(r'^---\s*\n(.*?)\n---\s*\n(.*)$', content, re.DOTALL)
        if not match:
            return None

        frontmatter_text, body = match.groups()

        # Parse YAML frontmatter
        frontmatter = {}
        for line in frontmatter_text.strip().split('\n'):
            if ':' in line:
                key, value = line.split(':', 1)
                frontmatter[key.strip()] = value.strip()

        return {
            "name": frontmatter.get("name", path.parent.name),
            "description": frontmatter.get("description", ""),
            "body": body.strip(),
            "path": path,
            "dir": path.parent
        }

    def get_descriptions(self) -> str:
        """
        Generate metadata list for system prompt.

        This is always loaded (Layer 1: ~100 tokens/skill).
        """
        if not self.skills:
            return "No skills available."

        return "\n".join(
            f"- {name}: {skill['description']}"
            for name, skill in self.skills.items()
        )

    def get_skill_content(self, name: str) -> str:
        """
        Get full skill content for context injection.

        This is loaded on demand (Layer 2: ~2000 tokens).
        """
        if name not in self.skills:
            return f"Skill '{name}' not found."

        skill = self.skills[name]
        return f"# Skill: {name}\n\n{skill['body']}"


# Global skill loader instance
SKILLS = SkillLoader(SKILLS_DIR)


# =============================================================================
# System Prompt - Updated for v4
# =============================================================================

SYSTEM = f"""You are a coding agent at {WORKDIR}.

Loop: plan -> act with tools -> update todos -> report.

Rules:
- Use TodoWrite to track multi-step tasks
- Use Skill tool to load domain expertise when needed
- Prefer tools over prose. Act, don't just explain.
- After finishing, summarize what changed.

Available Skills:
{SKILLS.get_descriptions()}"""


# =============================================================================
# Skill Tool - Loads domain knowledge on demand
# =============================================================================

TOOLS = [
    # v1-v3 tools (unchanged)
    # ... bash, read_file, write_file, edit_file, TodoWrite, Task

    # NEW in v4: Skill tool
    {
        "name": "Skill",
        "description": "Load a skill to get domain expertise.",
        "input_schema": {
            "type": "object",
            "properties": {
                "skill": {
                    "type": "string",
                    "description": "Name of the skill to load"
                }
            },
            "required": ["skill"],
        },
    },
]


# =============================================================================
# Tool Execution with Skill Support
# =============================================================================

def run_skill(skill_name: str) -> str:
    """
    Load and inject skill content into conversation.

    Key insight: Skill content enters as tool_result (user message),
    not system prompt. This preserves cache!
    """
    content = SKILLS.get_skill_content(skill_name)

    # Return as tool result - becomes part of conversation history
    return f"""<skill-loaded name="{skill_name}">
{content}
</skill-loaded>

Follow the instructions in the skill above."""


def execute_tool(name: str, args: dict) -> str:
    """Dispatch tool call to implementation."""
    if name == "Skill":
        return run_skill(args["skill"])
    # ... (other tools from v1-v3)
    return f"Unknown tool: {name}"

def run_skill(skill_name: str) -> str:
    content = SKILLS.get_skill_content(skill_name)
    # Full content returned as tool_result
    # Becomes part of conversation history (user message)
    return f"""<skill-loaded name="{skill_name}">
{content}
</skill-loaded>

Follow the instructions in the skill above."""

def agent_loop(messages: list) -> list:
    while True:
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,  # Never changes - cache stays valid!
            messages=messages,
            tools=ALL_TOOLS,
        )
        # Skill content enters messages as tool_result...

# Avoid: Edit history
messages[2]["content"] = "edited"  # Cache invalid

# Recommend: Append only
messages.append(new_msg)  # Prefix unchanged, cache hit