Skills and project commands.

Use a skill for a reusable procedure with supporting files. Use a project command for a short named prompt with arguments. Both supply instructions; neither silently approves commands or grants new tool access. This guide covers CLI 0.9.0.

#Create a skill

Create .kaitoi/skills/release-notes/SKILL.md in the workspace:

---
name: release-notes
description: Write release notes from reviewed changes.
---

Read CHANGELOG.md and the supplied change summary. Draft user-facing notes
and identify missing evidence before claiming an item is shipped.

Use a lowercase name with letters, digits, and hyphens. Place reference text, templates, or other support files in the skill's folder. Inside Code, /skills lists the discovered skills and /release-notes explicitly invokes this one. Code can load instructions and read support files as needed. A script being present in the folder does not cause it to execute on load.

For duplicate names, the first match wins in this order: project .kaitoi/skills, .claude/skills, .agents/skills, then user ~/.kaitoi/skills. Project sources require trust. Inspect /skills for invalid or shadowed entries rather than assuming every folder was accepted.

#Create a project command

Create .kaitoi/commands/review.md:

---
description: Review a named area without edits
argument-hint: <area>
---

Review $ARGUMENTS for concrete defects. Return file and line evidence
before proposing changes.

Then invoke it:

/review "the retry handler"

$ARGUMENTS becomes the supplied argument text. $1 through $9 substitute individual parsed words, with quotes grouping words. A nested path such as .kaitoi/commands/frontend/component.md becomes /frontend:component.

The release-notes skill consists of a folder containing SKILL.md and optional support files; /release-notes loads its procedure. The frontend/component.md command is a prompt file exposed as /frontend:component. Calling it with “a search field” substitutes that text for $ARGUMENTS. Loading either extension does not execute shell code or bypass tool permissions.

The skill’s procedure notebook stays with its supporting files. The command receives an argument chip and emits the filled prompt; tool review and execution remain downstream.

Project commands are discovered from .kaitoi/commands, then .claude/commands, with the first name winning. Built-in slash commands cannot be replaced. Use /help to inspect the available command names.

#Keep compatibility claims narrow

Command front matter recognizes description and argument-hint. Fields such as model and allowed-tools do not grant their meaning from another product. A line beginning with ! remains prompt text; command expansion does not run it as a shell command.

Skills and commands follow trust, file policy, redaction, and bounded reads. They are not loaded into brokered Crew children. This is supported file-format compatibility, not full compatibility with another agent's plugin or settings system.

If the wrong procedure appears, check the active workspace and winning path, then the file's name and front matter. Keep instructions focused on inputs, steps, evidence, and the expected output so the agent can tell when it is done.