Skills

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:

[features]
skills = false

Override for a single run:

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:

   ---
   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.