# Skills and project commands

> Package reusable instructions as a skill, add a project slash command, understand discovery precedence, and keep prompt expansion separate from execution.

Source: https://kaitoi.io/docs/cli/skills-and-commands/
Section: Kaitoi CLI / Extending Kaitoi Code
Written for: Teams making repeatable Code workflows.
Prerequisites: A trusted workspace for project extensions
Last reviewed: 2026-10-24

---

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:

```markdown
---
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`:

```markdown
---
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:

```text
/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.

*Figure: A skill is a procedure folder; a project command expands a named prompt.*

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.