Skills

A Kin skill is one named bundle with two optional doors. The model can load it on demand with the skill tool, and you can run it directly as /name arguments. Both doors use the same instructions and resource base.

The bundle

Each skill is a directory whose entry point is exactly SKILL.md:

.kin/skills/release-notes/
├── SKILL.md
├── style.md
└── scripts/
    └── collect.sh

---
name: release-notes
description: Draft release notes from the Git history since the last tag.
argument-hint: "[base tag]"
---
Read [style.md](${KIN_SKILL_DIR}/style.md), gather commits since $1, and
write concise release notes. If no base is supplied, use the latest tag.

name must equal the directory name and match [a-z][a-z0-9-]{0,63}. Flat <name>.md files are not skills. Kin rejects an invalid bundle and reserves its name at that discovery tier, so a broken project skill cannot silently fall through to a different user or bundled skill.

Field	Required	Meaning
name	yes	Exact directory name
description	yes	Complete catalog and /skills description; maximum 1,024 characters
kind	no	prompt (default); executable workflow bodies are retired
argument-hint	no	Usage hint shown beside /name
disable-model-invocation	no	true removes the model door while keeping /name
user-invocable	no	false removes the slash door while keeping model loading
allowed-tools	no	Documentary list only; it never grants or restricts tools
license / compatibility	no	Bundle provenance and compatibility notes
metadata	no	One-level string mapping for bundle metadata

Booleans are typed. Misspellings such as disableModelInvocation, non-boolean values, missing frontmatter, empty bodies, oversized files, and malformed frontmatter are invalid—not warnings with guessed behavior. The same bounded frontmatter parser validates and loads both skills and agent profiles. KIN_STRICT_SKILLS retains its historical name but now affects agent frontmatter only; skill validation is always strict.

Sibling guides, scripts, templates, and assets belong inside the directory. ${KIN_SKILL_DIR} expands to its absolute resource base before argument substitution, and relative links should resolve inside the bundle. Reading a resource never expands filesystem, network, credential, approval, or tool authority. Project skill symlinks must resolve inside the workspace; user skills may deliberately link to a user-owned directory.

Where skills come from

Discovery walks three roots in order:

1. <workdir>/.kin/skills/
2. ~/.kin/skills/
3. Kin’s installed bundled library

The first directory to claim a name wins, even when that claimant is invalid. Later valid copies appear as shadowed in /skills. Built-in client commands such as /clear and /plan reserve their names and cannot be replaced by a skill.

Kin composes project skills only after the workspace is trusted, exactly as it composes AGENTS.md. A local client’s route may seed <workdir>/.kin/skills/ beside the AGENTS.md it seeds, never overwriting an existing bundle; a skill meant for that client must be model-invocable, because a client turn carries no / dispatch.

Kin does not auto-discover .claude/skills/ or other harness directories. File shape alone does not make another harness’s tools, permissions, lifecycle, or resources compatible. Load skill-creator and give it an explicitly chosen foreign source when you want a separate Kin-native adaptation; the foreign directory remains untouched and is never live-loaded.

Creating and editing skills

/skill-creator is the canonical authoring procedure for new bundles, edits, and intentional adaptations from another harness. You can invoke it directly, or open /config → skill. The config route shows every source claimant with its project, user, or bundled source and its valid/invalid and effective/shadowed status. It then starts a visible root conversation with the live skill-creator instructions and a bounded snapshot of the selected skill.

Choose a publication scope explicitly:

• project override is the recommended default and targets <workdir>/.kin/skills/<name>/;
• user-wide targets ~/.kin/skills/<name>/, persists across workspaces, and carries a prominent fresh approval warning.

A project claimant is edited in place. Choosing project scope for a user or bundled winner creates an override and leaves its source untouched. An explicit user edit is allowed even when a project claimant shadows it, and the proposal says so. Kin can repair an invalid canonical directory or migrate a lone legacy <name>.md claimant to <name>/SKILL.md inside the same approved transaction; bundled files are never modified.

The author publishes through propose_skill, not ordinary file-edit tools. One proposal includes the complete resulting SKILL.md, every changed UTF-8 text resource, explicit text-resource deletions, and a per-file diff; resources that are not named are preserved. Before showing the diff Kin validates the live frontmatter parser and every relative Markdown or ${KIN_SKILL_DIR} reference. It refuses traversal, symlinks, reserved names, and project targets outside the workspace. A proposal may touch at most 32 paths, carry 256 KiB of proposed text, and use at most 64 KiB for SKILL.md.

Approval is fresh and non-reusable. Kin locks and rechecks the complete bundle state after approval, then publishes the staged directory as one recoverable transaction. A stale target aborts without writing. An interrupted transaction keeps the last complete catalog visible until recovery, so a lower-priority claim cannot surface temporarily. The proposal tools are root-only, unavailable during planning, and report needs_human in headless runs.

Two doors

The model door

The system prompt carries a compact catalog of model-invocable skills. The model calls skill with a name and optional arguments; Kin reads the current bundle and adds one <skill_content> block to the conversation. Calling the tool with no name returns the complete model-invocable list and leaves a skill catalog row rather than claiming a bundle invocation.

Each named call leaves an explicit skill invocation /name row in the chat timeline. Its verdict shows whether loading succeeded or failed. Named skill calls made by a child remain visible there even though ordinary child tool traffic is folded into its parent row or an artifact editor.

disable-model-invocation: true makes a procedure human-only. The tool refuses to reveal that body and tells the model to ask you to run /name. user-invocable: false creates the inverse: a model-loadable skill with no slash entry.

The human door

Type /name arguments in the composer. Kin displays the slash gesture in the transcript, then adds a settled skill invocation /name · by you row while storing and sending the same rendered <skill_content> block the tool door would produce. Skills expand $ARGUMENTS and $1, $2, and so on. Instructions and answers remain in the ordinary conversation, including on follow-up and resume. Legacy kind: workflow bundles are refused with a migration diagnostic.

In headless mode, only a positional prompt is slash-dispatched: kin -p "/release candidate". Piped stdin remains literal context. Invalid, unknown, built-in, and non-user-invocable names fail before a model session starts. The converted research and review commands work through this same door.

A live, scoped catalog

For a root session, the catalog is the final segment of the system prompt. A child with skill receives it after the stable base and before its fixed profile suffix. A rubric-bound child with no skill tool receives no catalog; a general, coder, researcher, explorer, or planner child does.

The catalog has a fixed 8,000-character budget. Kin first keeps every full description. If necessary it shortens descriptions from the bundled end, then falls back to name-only rows. It never drops a model-invocable name and tells the model how many descriptions were shortened. /skills is never budgeted.

Kin hashes the discovered claims. The registry refreshes before root turns and child spawns, and on editor reload, slash dispatch, /skills, and skill calls. A root turn recomposes its system only when the observed digest differs from the one already composed; a spawn uses the fresh snapshot without rewriting its in-flight parent. Applied skill and root-guidance changes therefore take effect on the next root turn or resume; a child spawned after application gets the fresh configuration while already-running children keep their launch system and catalog. No restart is needed. An incomplete scan keeps the last complete snapshot and reports the exact scan problem instead of publishing a partial catalog.

Inspecting the registry

/skills shows every valid skill with source, slash hint, kind, and model+user, model-only, user-only, or inert flags. It also shows shadowed and invalid name claims, catalog length and digest, and whether the last scan completed. Descriptions are complete here.

Kin’s installed library includes the general prompt skills brainstorm, code-review, commit-message, debug, deep-research-inline, delegate-plan, docs, pr-description, recall, remember, simplify, skill-creator, and test; and the human-only procedures /init, /critique, /deep-research, /research, /revise, and /security-review. All carry ordinary instructions. Review and research scope follows the request, with optional supervised delegation.

test writes focused tests through the repository’s real framework and fixtures; docs grounds maintained prose in the source and documentation owner.

remember and recall carry Kin’s continuity discipline. remember offers, inside its ordinary answer, to record one durable fact — a correction you made, a preference, constraint, or decision you stated, or a hard-won finding — and writes it only after you say yes, as an ordinary approved file write: into the document that owns it in a repository, or into context/<area>/<slug>.md plus a context/INDEX.md line where no owning document exists. recall reads that index only when a request concerns the workspace’s continuity or you ask, follows only the relevant notes, verifies any note that names a file, flag, command, or path against current source before acting on it, and proposes deleting wrong notes, rewriting superseded ones, and promoting facts that belong in an owning document. Nothing loads the index automatically, nothing writes at session end, and there is no memory tool, store, timer, or reminder behind either skill; a wrong offer costs a sentence, never a store. Review skills report substantiated findings rather than filling a defect quota, and Git prose follows repository guidance and history before using a fallback convention. Bundled skills are the lowest-priority examples, not a privileged execution lane: their instructions still pass through workspace trust, the ordinary permission gate, and any operator-owned external boundary.