How-To · 10 min
Skills
A skill is a Markdown document a model can pull into context exactly when it's relevant — a review checklist, a deploy runbook, your house style. Models see the list and load what matches; you write them once.
The format
Plain Markdown, either layout:
skills/review-checklist.md # flat file — the name is the filename
skills/deploy-runbook/SKILL.md # folder — the name is the folderOptional frontmatter sets the name and the one-liner models see in the list:
---
name: deploy-runbook
description: Exact steps and checks for deploying the storefront.
---
# Deploy runbook
…the actual instructions…Where skills live
Scanned from five places; on a name clash the earlier source wins:
| Priority | Location | Use for |
|---|---|---|
| 1 — project | <project>/.kaptain/skills (and the project's .claude/skills, .agents/skills) | skills that belong to a repo — they follow the live project root, no restart |
| 2 — global | skills/ in the data folder | your personal library, machine-wide |
| 3 — kapsule | a kapsule's own skills paths | skills shipped with an agent |
| 4 — imported | directories listed in KAPTAIN_SKILL_IMPORT_ROOTS | reuse an existing pack without copying it |
| 5 — your CLIs | ~/.claude/skills, ~/.codex/skills, ~/.agents/skills | the skills your Claude and Codex CLIs already have — listed with their source, one pool |
Add one
- UI: Krew view ▸ Skills category ▸ + Add skill — name, description, content — or Import… from a folder, a
.zip, a git URL orowner/repo, or Upload .zip. Cards show each skill's source and which agents carry it; only global skills are editable in place (project/kapsule/imported ones are owned by their source). - Disk: drop a
.md(or<name>/SKILL.md) into any location above. That's the whole mechanism — no registration step.
How runs use them
Models get two tools: skill_list (names + descriptions — the content stays out of context until needed) and skill_load(name), which injects the document. Kaptain's system scaffold actively tells models to scan the list before starting and load anything relevant — so a well-named skill with a sharp description gets used without you asking. You can also just say it: "load the deploy-runbook skill and follow it."
Skills on a kapsule
A kapsule agent can name skills in its skills list — those documents are injected into its persona on every run, no loading step. Right for the instructions an agent must always follow; use skill_load for the ones it needs sometimes.
Agent-readable version: index.md · Every claim on this page was exercised on a real install before being written. Something missing that cost you time? That is a documentation bug — tell us.