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.

What a skill is

A skill is a SKILL.md file with a small frontmatter block and a markdown body:

---
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) 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 and the settings.toml reference.

Where skills come from

Discovery walks five roots, highest priority first, and the first occurrence of a name wins:

1. <workdir>/.kin/skills/
2. <workdir>/.claude/skills/
3. ~/.kin/skills/
4. ~/.claude/skills/
5. the bundled library shipped with kin (lowest priority, last resort)

Two layouts are supported in each root: a directory holding SKILL.md (<name>/SKILL.md, the Agent Skills standard) and a flat <name>.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.

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 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
plan	Structure the read-only planning freeze and present a plan for approval
skill-creator	Capture a just-completed workflow as a reusable SKILL.md
pr-description	Draft a PR title + body from the branch diff vs base (honors .github/ PR templates)

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 ~/.claude/skills/ are your authored content; kin loads them as-is. /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 use. For delegating a skill's work to a child agent, see Subagents.