# Porting Skills from Claude Code

If you have Claude Code command files (`.claude/commands/*.md`) and want to use them in Anteroom, this guide explains the format differences, what translates directly, and what needs adaptation.

## Key Differences

Both Claude Code and Anteroom use **Markdown files with YAML frontmatter**. The formats have converged — porting is mostly mechanical.

| Aspect | Claude Code | Anteroom |
|--------|------------|----------|
| File format | Markdown (`.md`) with YAML frontmatter | Markdown (`SKILL.md`) with YAML frontmatter |
| Location | `.claude/commands/` | `.anteroom/skills/<name>/SKILL.md` or `.claude/skills/<name>/SKILL.md` |
| Prompt body | Markdown body after frontmatter | Markdown body after frontmatter (same) |
| Tool restrictions | `allowed-tools` frontmatter | `allowed-tools` / `denied-tools` frontmatter — enforced at runtime |
| Model directives | "Launch Haiku/Sonnet agents" in prose | Configure `ai.model_family_aliases` to map family names to model IDs, or use full model IDs directly |
| Sub-agents | `Agent` tool (Claude Code built-in) | `run_agent` tool (Anteroom built-in) |

## Field Mapping

| Claude Code frontmatter | Anteroom frontmatter | Notes |
|------------------------|---------------------|-------|
| Filename stem (`commit.md` → `commit`) | `name: commit` (or directory name) | Must match `[a-z0-9][a-z0-9_-]*` |
| `description:` | `description:` | Same — short text for `/skills` list |
| `allowed-tools:` | `allowed-tools:` / `denied-tools:` | Enforced at runtime — tool names are mapped to Anteroom equivalents |
| Markdown body | Markdown body | Same — everything after the closing `---` |

## Tool Name Mapping

Claude Code and Anteroom have different tool names. When the AI reads your skill prompt, it maps the *intent* to whatever tools are available — so Claude Code tool names in prose often work. But using Anteroom's native names is more reliable.

| Claude Code tool | Anteroom tool | Notes |
|-----------------|--------------|-------|
| `Read` | `read_file` | Same behavior — reads file contents |
| `Edit` | `edit_file` | Same — exact string replacement |
| `Write` | `write_file` | Same — create or overwrite files |
| `Bash` | `bash` | Same — shell command execution |
| `Grep` | `grep` | Same — regex search across files |
| `Glob` | `glob_files` | Same — file pattern matching |
| `Agent` | `run_agent` | Similar concept, different mechanics (see below) |
| `WebFetch` | *(not built-in)* | Use MCP tools if available |
| `WebSearch` | *(not built-in)* | Use MCP tools if available |

## Sub-Agents: `Agent` vs `run_agent`

This is the biggest difference. Claude Code's `Agent` tool is a built-in that spawns sub-processes with model selection. Anteroom's `run_agent` tool is similar but works differently:

**What carries over:**

- Parallel execution — the AI can issue multiple `run_agent` calls in one response, and Anteroom runs them concurrently
- Model overrides — `run_agent` accepts an optional `model` parameter
- Tool access — sub-agents get all built-in and MCP tools

**What doesn't carry over:**

- **Model names** — Claude Code uses family names like "Haiku" and "Sonnet". Anteroom can resolve these via `ai.model_family_aliases` in your config (e.g., `{haiku: "claude-3-haiku-20240307", sonnet: "claude-sonnet-4-20250514"}`). Known Claude family names (`haiku`, `sonnet`, `opus`) that are not configured in the alias table are rejected with an actionable error. All other model values pass through unchanged. If omitted, the sub-agent inherits the parent's model.
- **Isolated context** — Anteroom sub-agents cannot see the parent conversation. Each `run_agent` prompt must be fully self-contained with all necessary context (file paths, issue numbers, search terms).
- **The word "agent" is not a directive** — writing "Launch parallel agents" in a skill prompt is just text. The AI decides whether to call `run_agent` based on the available tools and the prompt's intent. Explicit `run_agent` language is more reliable.

**Limits** (configurable via `safety.subagent` in `config.yaml`):

| Limit | Default |
|-------|---------|
| Max concurrent | 5 |
| Max total per request | 10 |
| Max nesting depth | 3 |
| Timeout per sub-agent | 120s |
| Output truncation | 4,000 chars |

## Step-by-Step Migration

### Before: Claude Code command file

```markdown title=".claude/commands/pr-summary.md"
---
name: pr-summary
description: Summarize a pull request
allowed-tools: Bash, Read, Grep
---

# /pr-summary

Summarize the given pull request.

## Usage

/pr-summary 85

## Steps

1. Fetch the PR details:
   ```bash
   gh pr view {args} --json title,body,files
   ```

2. Launch parallel agents to analyze:

   **Agent A (Haiku):** Read the diff and list changed files.
   **Agent B (Haiku):** Check if tests were modified.

3. Write a summary covering what changed and why.
```

### After: Anteroom skill file

```markdown title=".anteroom/skills/pr-summary/SKILL.md"
---
name: pr-summary
description: Summarize a pull request
allowed-tools:
  - bash
  - read_file
  - grep
---

Summarize the given pull request.

## Usage
/pr-summary 85

## Steps

1. Fetch the PR details with `gh pr view {args} --json title,body,files`.

2. Use the `run_agent` tool to analyze these tasks in parallel.
   Each sub-agent prompt must be self-contained.

   Sub-agent 1: Run `gh pr diff {args}` and list the changed files
   with a one-line summary of each change.

   Sub-agent 2: Run `gh pr diff {args} --name-only` and check if
   any test files were modified. Report which tests changed.

3. Write a summary covering what changed and why.
```

### What changed

1. **File layout**: Single `.md` file → `<name>/SKILL.md` directory layout (Anteroom uses the directory name as the skill name)
2. **`allowed-tools`**: Preserved — Anteroom enforces tool restrictions from the frontmatter at runtime. Claude tool names (e.g., `Bash`, `Read`) should be updated to Anteroom names (`bash`, `read_file`) for exact matching
3. **"Agent A (Haiku)"**: Replaced with explicit `run_agent` language and self-contained prompts. If `ai.model_family_aliases` is configured, the family name resolves automatically
4. **Model names**: Configure `ai.model_family_aliases` to map Claude family names to real model IDs, or remove them to inherit the parent model
5. **`{args}`**: Works the same — user arguments replace the placeholder (but see the code-fence gotcha below)

!!! warning "Gotchas"
    **These are the four things that silently fail when porting without changes:**

    1. **`allowed-tools` tool names must use Anteroom names.** Claude Code uses `Bash`, `Read`, `Grep` etc. Anteroom enforces `allowed-tools` at runtime using its own tool names (`bash`, `read_file`, `grep`). Update the tool names in frontmatter when porting. See the tool name mapping table above.
    2. **Model family names need configuration.** `run_agent(model="haiku")` is rejected locally unless `ai.model_family_aliases` maps it to a real model ID. Configure aliases in `config.yaml`: `ai: { model_family_aliases: { haiku: "claude-3-haiku-20240307" } }`, or omit `model` to inherit the parent's model.
    3. **Sub-agent prompts must be self-contained.** Unlike Claude Code where agents share some context, Anteroom sub-agents see *only* their prompt. Include file paths, PR numbers, search terms — everything the sub-agent needs.
    4. **`{args}` inside fenced code blocks is not expanded.** Anteroom's `{args}` expansion skips content inside `` ``` ... ``` `` fences. If your Claude Code command has `{args}` inside bash fences, move the command to inline code (`` `command {args}` ``) or plain prose when porting.

## What Just Works

Not everything needs changing. These patterns translate directly:

- **Bash commands** (`gh`, `git`, `pytest`, `ruff`) — same shell, same tools
- **`{args}` placeholder** — same expansion behavior (but not inside fenced code blocks — use inline code instead)
- **Multi-step workflows** — the AI follows numbered steps naturally
- **File reading/writing** — tool names differ but the AI maps intent correctly
- **Checklists and review criteria** — the AI interprets markdown checklists as instructions

## See Also

- [Skills](skills.md) — full skill authoring reference
- [Skill Examples](skill-examples.md) — complete example skills with commentary
- [Built-in Tools: run_agent](tools.md#run_agent) — sub-agent tool reference
