dev/docs/skills.md

Skills

Warning: 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. Runtime context includes only name, description, and file path; the full body stays on disk.

Enable skills

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

• Disable in config (preferred): add to $HANZO_HOME/config.toml (usually ~/.hanzo/config.toml):

  [features]
  skills = false
  

• Override for a single run:

  dev -c features.skills=true
  

Where skills live

Discovery roots (highest precedence first):

• Repo: nearest .hanzo/skills/**/SKILL.md from current directory up to repo root.
• User: $HANZO_HOME/skills/**/SKILL.md (default: ~/.hanzo/skills/**/SKILL.md).
• System: bundled skills under $HANZO_HOME/skills/.system/**/SKILL.md.

Behavior:

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

File format

• YAML frontmatter + body.
• Required frontmatter fields:
  • name (non-empty, <= 64 chars, single-line normalized)
  • description (non-empty, <= 1024 chars, single-line normalized)
• 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 ~/.hanzo/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.