# Skills

A skill = a Markdown doc a model pulls into context when relevant (a checklist, a runbook, your house style). Write once; models load on demand.

## Format
Flat `skills/<name>.md` or folder `skills/<name>/SKILL.md`. Optional frontmatter:
    ---
    name: deploy-runbook
    description: Exact steps and checks for deploying the storefront.
    ---
Missing name falls back to the file/folder name.

## Where skills live (priority order; earlier wins on a name clash)
1. project: <project>/.kaptain/skills (and .claude/skills) — follow the live project root, no restart
2. global: skills/ in the data folder — your machine-wide library
3. kapsule: a kapsule's own skills paths — shipped with an agent
4. imported: dirs in KAPTAIN_SKILL_IMPORT_ROOTS — reuse existing packs (e.g. Claude skills) without copying

## Add one
- UI: Krew view > Skills > "+ Add skill" (name, description, content). Cards show source + which agents carry it; only global skills are editable in place.
- Disk: drop the .md into any location above. No registration step.

## How runs use them
Tools: `skill_list` (names + descriptions only) and `skill_load(name)` (injects the document). The system scaffold tells models to scan the list first and load anything relevant — sharp names/descriptions get used unprompted. Or say: "load the deploy-runbook skill and follow it."

## Skills on a kapsule
`skills: [...]` on a kapsule agent injects those documents into its persona every run (always-on instructions). Use skill_load for sometimes-needed ones.