# Build Custom Skills

Create reusable prompt templates that integrate into the CLI REPL as `/commands`.

## Skill Format

Each skill is a directory containing a `SKILL.md` file with YAML frontmatter for metadata and a Markdown body for the prompt:

```markdown title="my-skill/SKILL.md"
---
name: skill-name
description: Short description shown in /skills list
---

The prompt template sent to the AI when the skill is invoked.
This can be multi-line and reference tools, files, etc.
```

## Where to Put Skills

| Location | Scope | Priority |
|---|---|---|
| `.anteroom/skills/` | Project-specific | Highest |
| `~/.anteroom/skills/` | Global (all projects) | Medium |
| Built-in | Default skills | Lowest |

Project skills override global skills with the same name. Global skills override built-in skills.

Anteroom walks up from the working directory to find the nearest `.anteroom/skills/` directory, similar to [ANTEROOM.md](../cli/project-instructions.md) discovery.

### Reserved Skill Names

Skill names cannot use built-in slash command names. Reserved names include: `quit`, `exit`, `new`, `help`, `list`, `delete`, `rename`, `search`, `tools`, `model`, `plan`, and others. If you try to create a skill with a reserved name, it will be silently rejected with a warning.

## Example: Test Runner

```markdown title=".anteroom/skills/test/SKILL.md"
---
name: test
description: Run tests and fix failures
---

Run the test suite with pytest. If any tests fail:
1. Read the failing test file
2. Read the relevant source code
3. Identify the root cause
4. Fix the issue
5. Re-run the tests to verify
```

Usage:

```
you> /test
you> /test just the auth module
```

## Example: Documentation Writer

```markdown title="~/.anteroom/skills/docs/SKILL.md"
---
name: docs
description: Generate documentation for a module
---

Read the specified source file(s) and generate comprehensive
documentation including:
- Module overview
- Public API reference
- Usage examples
- Important implementation notes
```

## Example: Code Reviewer

```markdown title=".anteroom/skills/pr-review/SKILL.md"
---
name: pr-review
description: Review staged changes like a PR
---

Run `git diff --staged` and review the changes as if this were
a pull request. Check for:
- Bugs and logic errors
- Security vulnerabilities
- Performance issues
- Missing error handling
- Missing tests
- Code style issues

Format findings with severity (critical/warning/info) and
specific file:line references.
```

## Skill Arguments

Anything typed after the skill name is appended to the prompt:

```
you> /test just the auth tests
you> /a-help how does the agent loop work?
you> /pr-review focus on the database changes
```

The extra text is concatenated after the skill's `prompt` field, giving the AI additional context.

## Listing Skills

```
you> /skills
```

Shows all available skills with their descriptions and source (default, global, or project).

## Packaging Skills as Packs

To share skills with your team, bundle them into a pack using `/new-pack`:

```
you> /new-pack security rules for our Python projects
```

The AI walks you through creating a pack with skills and other artifacts. See [Packs & Artifacts](../packs/index.md) for details.
