# Skills

URL: https://docs.hanzo.ai/docs/dev/usage/skills

> Extend Hanzo Dev with reusable skill bundles.

> This is an experimental feature and may change.

Hanzo Dev can discover reusable "skills" on disk. A skill is a small bundle with a name, short description, and optional body instructions.

## Enable Skills

Skills are behind the `skills` feature flag and **enabled by default**.

Disable in config:

```toml
[features]
skills = false
```

Override for a single run:

```bash
dev -c features.skills=true
```

## Where Skills Live

Discovery roots (highest precedence first):

1. **Repo**: `.agents/skills/**/SKILL.md` and `.codex/skills/**/SKILL.md`, from the
   current directory up to the repo root.
2. **Home**: `~/.agents/skills/**/SKILL.md`.
3. **User**: `$CODE_HOME/skills/**/SKILL.md` (default: `~/.code/skills/`, and the
   legacy `~/.codex/skills/` is read too).
4. **System**: the `.system` skills that ship with Hanzo Dev, installed under
   `$CODE_HOME`.
5. **Admin**: `/etc/codex/skills/**/SKILL.md`.

Names are deduped in that order, so a repo skill wins over a user skill of the
same name, and a user skill wins over a system one.

Behavior:

- Recursive scan; only files named exactly `SKILL.md` are loaded.
- Hidden entries and symlinks are skipped.
- Duplicate skill names are deduped by precedence (first match wins).
- Render order is by name, then path.

## File Format

YAML frontmatter + body. Required frontmatter fields:

- `name` — non-empty, max 64 chars, single-line
- `description` — non-empty, max 1024 chars, single-line

Extra keys are ignored.

## Loading and Rendering

- Skills load once at startup.
- When valid skills exist, Hanzo Dev appends a runtime-only `## Skills` section after `AGENTS.md`.
- Invalid skills are ignored and surfaced as startup errors in the TUI.

## Create a Skill

1. Create `~/.code/skills/<skill-name>/`.

2. Add `SKILL.md`:

   ```markdown
   ---
   name: your-skill-name
   description: what it does and when to use it
   ---

   # Optional body
   Add instructions, references, examples, or scripts (kept on disk).
   ```

3. Restart Hanzo Dev.

## Managing Skills

- Use `/skills` in the TUI to browse and toggle skills.
- Use the Settings overlay (Skills section) for configuration.