# Skill and generated docs

> Edit and publish the SKILL.md that ships with your CLI, and browse its generated command docs.

Every CLI you build comes with two kinds of docs:

- **SKILL.md**, an Agent Skill that tells coding agents when and how to use your CLI.
- **Generated command docs**, one page per command, for your team.

> **Note** This page covers the skill for the CLI you built. The skill that teaches agents to run okibi itself is [the okibi skill](https://okibi.ai/docs/agents/skill.md).

## Where the skill comes from

Each generation writes `SKILL.md` at the root of the CLI's repository. Releases carry it in the same archive as the binary. When a customer runs your install command, the installer saves the skill in `~/.agents/skills`. It then links it into the coding agents it finds: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, and OpenCode.

Running the install command again updates the CLI and its skill together. To save the skill somewhere else, set `MY_CLI_SKILLS_DIR` before installing. The prefix is your CLI name in capitals, with `_` for `-`.

## Read and edit the skill

Owners, admins, and builders can edit it.

**In the app**

1. Open the project and click **Skill** under **CLI**.
2. Click **Edit**. Switch between **Source** and **Preview** to check your change.
3. Click **Save to repo**.

**In the CLI**

```sh
okibi clis skill show my-cli > SKILL.md
okibi clis skill set my-cli --file SKILL.md
```
Without `--file`, `skill set` opens `$VISUAL` or `$EDITOR`. With `--agent`, pass `--file <path>`, or `--file -` to read stdin.

Saving commits `SKILL.md` to the CLI's repository. Your customers don't get it yet: the **Skill** page shows "saved. Not in the official release yet" until you publish.

If someone saved a newer copy first, your save is refused, so nothing is overwritten. The app keeps your draft open. In the CLI, run `skill show` again and redo your edit.

## Publish the skill

Publishing builds a new version from the repository's latest commit and makes it the official release. Owners and admins can publish.

**In the app**

After you save, a **Publish** button appears next to **Edit** on the **Skill** page. It names the next version, such as **Publish v1.0.4**. Click it.

**In the CLI**

```sh
okibi clis skill publish my-cli
```

Before you publish:

- The CLI needs an official release. See [Releases and install](https://okibi.ai/docs/guides/releases.md).
- The official release must be the latest version. If it isn't, make the latest one official on the project's **CLI** page first.
- Any other commits on the repository ship too, because the build uses the latest commit.

Skill publishing always targets the official release. To show testers a skill change, run `okibi clis publish my-cli` to make a version, then pin it for [testing](https://okibi.ai/docs/guides/testers.md).

## How agents use your CLI

An agent doesn't need your whole command list up front. It finds what it needs as it goes:

```sh
my-cli --help
my-cli <command> --help
my-cli <command> --agent
```

1. `--help` lists the commands.
2. `<command> --help` shows the flags for one command.
3. `--agent` runs the command with JSON output and no prompts.

The generated skill already tells agents to work this way. Edit it to add what only you know, such as which commands to run in which order.

## Browse the generated command docs

Click **Docs ↗** on the CLI page. The docs open full screen, with commands grouped by resource. Each command page shows its usage, **Flags**, and an **Example**. Press ⌘K, or Ctrl+K, to search.

- The docs appear after the first successful build.
- They update after every successful build, so they can be newer than the official release.
- Owners, admins, and builders can see them. Workspace testers see **Pinned command docs** for the testing version instead.

- [Releases and install](https://okibi.ai/docs/guides/releases.md): Choose the official release your customers install.
- [The okibi skill](https://okibi.ai/docs/agents/skill.md): The skill for building CLIs with okibi.