# Skills > A skill is a reusable, named prompt or workflow that the model can load on demand. You write it once as a markdown file; kin advertises it to the model and loads its full instructions only when they're needed. A skill is a reusable, named prompt or workflow that the model can load on demand. You write it once as a markdown file; kin advertises it to the model and loads its full instructions only when they're needed. ## What a skill is A skill is a `SKILL.md` file with a small frontmatter block and a markdown body: ```markdown --- name: release-notes description: Draft release notes from the git log since the last tag. --- Gather the commits since the most recent tag, group them by type (features, fixes, docs), and write concise release notes in markdown. ``` | Field | Required | Notes | |-------|----------|-------| | `name` | no | Advisory; the directory or file stem is canonical. A mismatch warns | | `description` | no | What the skill does; shown in the catalog. Falls back to the first paragraph of the body. Capped at 1024 chars | | `license` / `compatibility` | no | Optional metadata carried through from the frontmatter | | `allowed-tools` | no | Documentary only — kin does not enforce it. A skill adds know-how, not permissions; scope a subagent (see [Subagents](/docs/kin/guide/subagents/)) if you need a real tool restriction | The body is the instruction set. Frontmatter is hand-parsed (no YAML dependency), and a malformed or absent frontmatter block degrades gracefully — the file still loads, with the first paragraph as the description. Set `KIN_STRICT_SKILLS=1` (or `strict_skills = true` in settings) to make malformed frontmatter an error instead. See [Environment variables](/docs/kin/reference/environment-variables/) and the [settings.toml reference](/docs/kin/reference/settings-toml/). ## Where skills come from Discovery walks three roots, highest priority first, and the first occurrence of a name wins: 1. `/.kin/skills/` 2. `~/.kin/skills/` 3. the **bundled** library shipped with kin (lowest priority, last resort) Two layouts are supported in each root: a directory holding `SKILL.md` (`/SKILL.md`, the Agent Skills standard) and a flat `.md` file. A project skill always overrides a same-named user skill, and any user or project skill overrides a same-named bundled one — so you can shadow a bundled skill just by writing your own with the same name. Kin deliberately does not auto-discover `.claude/skills/`. A foreign skill can use the same markdown layout while depending on different tools, agents, permissions, lifecycle hooks, or sibling resources. Loading it as-is would make file compatibility look like behavioral compatibility. To bring one across, load `skill-creator` and give it the source path; the MCA will inspect the source and its referenced files, translate the workflow to Kin's harness, and write a separate Kin-native copy under `.kin/skills/`. The source remains unchanged. ## Bundled skills kin ships a small, curated library of exemplar skills so the model has useful workflows out of the box with no setup. They are the lowest-priority discovery root, so they only fill names you have not claimed yourself: | Skill | What it does | |-------|--------------| | `deep-research` | Outline → fan out web searches → verify claims + citation liveness → write a cited report (the inline variant of the [`/deep-research`](/docs/kin/guide/deep-research/) workflow command) | | `brainstorm` | Diverge to several options with tradeoffs, then converge on a pick | | `code-review` | Vet the current diff for correctness, security, architecture, coverage | | `simplify` | Post-implementation reuse / dedup / dead-code cleanup (behavior-preserving) | | `debug` | Error-first hypothesize → reproduce → fix → verify loop | | `commit-message` | Draft a Conventional Commits message from the staged diff; an already authorized workflow may pass it to `git.commit`, but drafting grants no commit/push authority | | `plan` | Structure the read-only planning freeze and present a plan for approval | | `skill-creator` | Capture a completed workflow or explicitly adapt a foreign skill into a Kin-native `SKILL.md` | | `pr-description` | Draft a PR title + body from the branch diff vs base (honors `.github/` PR templates); an already authorized workflow may pass it to `github.open_pr`, but drafting never pushes or publishes | | `shelf` | Curate durable, rock-sized workspace job cards; groom, pick up, submit to Outpost, and recover overdue work | **Trust boundary.** Bundled skills are trusted content that rides the installed wheel — they are reviewed alongside the code. Skills you discover from `.kin/skills/` or `~/.kin/skills/` are *your* authored content; kin loads them as-is. Foreign skill directories are not part of this trust boundary. `/skills` tags every row with its provenance (`project` / `user` / `bundled`) so you can always see where an instruction set came from. Like every skill, a bundled one is prose-on-demand: it adds know-how but grants no permissions — the permission gate and OS sandbox still apply when its steps run. ## Progressive disclosure Skills load in three levels, so a large library costs almost nothing until used: 1. **Catalog** — every skill's name and description is appended to the system prompt, so the model always knows what exists. 2. **Body** — the full instructions load only when the model calls the `skill` tool with a name. 3. **Persist** — the loaded body lands as the tool's result and stays in the conversation for the rest of the session. ## Listing & loading Run `/skills` to see what's discoverable from your workspace — each row is a provenance tag (`project` / `user` / `bundled`), a name, and a short description. The model loads a skill itself through the `skill` tool. Called with no name it lists the available skills; called with a name it loads that skill's body into the conversation before doing the work it describes. The `skill` tool is non-destructive and auto-allowed, so loading a skill never prompts for approval. Discovery runs per call against the session workspace, so a skill you add mid-session is seen without a restart. A skill body can take arguments: `$ARGUMENTS` expands to everything passed, and `$1`, `$2`, … to the individual arguments — the same substitution that [custom slash commands](/docs/kin/guide/slash-commands/) use. For delegating a skill's work to a child agent, see [Subagents](/docs/kin/guide/subagents/).