okibi.ai

Command Palette

Search for a command to run...

Update a CLI's Agent Skill and Release a New Version with the Okibi CLI

Last updated: 11/18/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}. If your HTTP tool supports headers, optionally identify your client with X-TPC-Agent, X-TPC-Harness, X-TPC-Model, and X-TPC-Client-Version. Send only names and versions you know; omit unknown values. These fields are self-reported analytics, never authentication. Do not send account IDs, API keys, or session tokens in them.

Update a CLI's Agent Skill and Release a New Version with the Okibi CLI

Okibi tracks what changed in a CLI's repository since the last release, lets you edit the agent skill (SKILL.md) from the terminal, and records each edit as a new release. This guide adds two verified gotchas to the skill for acme-orders and publishes the result as a new official release. It is about the skill, which agents read. It does not cover an API that changed: that needs the CLI itself to be rebuilt from an updated spec, which this guide does not do. Publishing a release also changes what every workspace member installs, so use a disposable project.

What you will build

A "Known gotchas" section added to the CLI's SKILL.md, published as a new official release, with the release history and drift status checked before and after.

clis changes (up-to-date)  ->  skill show  ->  skill set --file  ->  skill publish  ->  releases (new patch version)

AI Prompt

Using the Okibi CLI, update the agent skill for acme-orders and publish it.

Requirements:
- `okibi clis changes acme-orders --json` reports `status` and `commitsAhead` since the last published version.
- `okibi clis skill show acme-orders --json` returns the canonical SKILL.md in the `content` field.
- `okibi clis skill set acme-orders --file <path>` saves a new SKILL.md as a commit to the hosted repository. It does not release it.
- `okibi clis skill publish acme-orders` builds a new version from the published code with the saved SKILL.md and makes it the official release as the next patch version. It needs an official release first, and the official release must also be the newest release. Otherwise it fails with `api 400: official-release-not-current`.
- Only add facts you have verified against the CLI.
- Run the verification step below before finishing.

Prerequisites

  • A generated CLI named acme-orders with an official release (okibi clis release set acme-orders --release <release-id>).
  • Okibi CLI 0.2.11, logged in.
  • The facts being added were checked first against the built CLI and the Acme Orders example API. acme-orders orders list --status shipped,pending --agent is rejected with exit code 1, and acme-orders orders cancel order ord_2 --agent returns HTTP 409 with exit code 5.

Note: Output is trimmed. The SKILL.md is about 200 lines (192 to 201 on the CLIs tested), so only the diff is shown, and the line numbers in the diff header will differ on your CLI. In this run the CLI already had a skill release from an earlier test, so the version numbers below are one patch higher than a first run.

1. Check for drift

okibi clis changes acme-orders --json
{
  "latestVersion": 1,
  "releaseVersion": "1.0.0",
  "commitsAhead": 0,
  "status": "up-to-date"
}

This is the output right after generation. Before editing, expect "status": "up-to-date" and "commitsAhead": 0, with the version numbers of your latest release.

2. Save the current skill and add the notes

okibi clis skill show acme-orders --json | python3 -c "import json,sys;print(json.load(sys.stdin)['content'],end='')" > SKILL.before.md
grep -c 'Known gotchas' SKILL.before.md
cp SKILL.before.md SKILL.after.md
cat >> SKILL.after.md <<'EOT'

## Known gotchas

- `orders list --status` takes exactly one value (`pending`, `paid`, `shipped` or `cancelled`). A comma-separated list such as `shipped,pending` is rejected before any request is sent and exits with code 1. Run the command once per status.
- `orders cancel order <id>` on a shipped order returns HTTP 409 and exit code 5. Check the order's status with `orders get` first.
EOT
diff SKILL.before.md SKILL.after.md

skill show --json returns the file inside a JSON object, so the one-liner above extracts it. The grep prints 0 for a skill that does not have the section yet. If it prints a higher number, skip the cat >> append below so the section is not duplicated. The diff:

196a197,201
>
> ## Known gotchas
>
> - `orders list --status` takes exactly one value ...
> - `orders cancel order <id>` on a shipped order returns HTTP 409 ...

3. Save the edit

okibi clis skill set acme-orders --file SKILL.after.md --json

The response includes "status": "saved", the new sha, a commitUrl pointing at the commit in the hosted repository and the saved content. The edit is saved but not yet released.

4. Make sure the official release is the newest

okibi clis releases acme-orders --json

Compare officialReleaseId with the id of the first (newest) entry in releases. skill publish works only when they are equal. In this run they matched. A CLI with only one release (as on a fresh CLI) always matches.

If they differ, an older release is official on purpose or by mistake. Do not promote the newest release only to unblock the publish: that changes what every workspace member installs. Find out why the older release is official first. If you do want the newest release official, save the current official id before you change it, so you can put it back:

ORIG=$(okibi clis releases acme-orders --json | python3 -c "import json,sys;print(json.load(sys.stdin)['officialReleaseId'])")
okibi clis release set acme-orders --release <newest-release-id> --json
# to undo: okibi clis release set acme-orders --release "$ORIG" --json

5. Publish it

okibi clis skill publish acme-orders --json
{ "publishedVersion": 3, "releaseVersion": "1.0.2" }

The version numbers depend on how many releases already exist. A first skill publish on a new CLI returns 1.0.1.

6. Check the release history

okibi clis releases acme-orders --json
{
  "officialReleaseId": "<id of 1.0.2>",
  "releases": [
    { "id": "<id of 1.0.2>", "releaseVersion": "1.0.2", "kind": "skill-update" },
    { "id": "<id of 1.0.1>", "releaseVersion": "1.0.1", "kind": "skill-update" },
    { "id": "<id of 1.0.0>", "releaseVersion": "1.0.0", "kind": "generation" }
  ]
}

The newest release is listed first. officialReleaseId matches the newest release after a successful skill publish. All three releases carry runNumber 1, because a skill update builds from the same run's code.

Verify the result

okibi clis skill show acme-orders --json | python3 -c "import json,sys;print(json.load(sys.stdin)['content'])" | grep -c 'Known gotchas'
okibi clis changes acme-orders --json

Expected: a grep count of 1 or higher, and from changes the releaseVersion returned by skill publish in step 5, with "status": "up-to-date" and "commitsAhead": 0.

How it works

skill set commits the new file to the CLI's hosted repository. skill publish builds a new version from the published code with the saved SKILL.md, cuts a release of kind skill-update and makes it the official release. The earlier releases stay in the history.

Common issues

skill set does not release anything

After step 3 the content is saved, but the official release is unchanged until skill publish runs.

skill publish fails with official-release-not-current

okibi clis skill publish returned api 400: official-release-not-current after the official release had been moved back to 1.0.0 with okibi clis release set acme-orders --release <older-release-id> while newer releases existed. Selecting the newest release again with okibi clis release set acme-orders --release <newest-release-id> fixed it, and it changed what every workspace member installed while it was in place.

Source changes use a different command

okibi clis changes reports commits ahead of the last release, and okibi clis publish builds those commits as the next version. With commitsAhead at 0, okibi clis publish acme-orders --json printed all repository commits are already published and created no release (the list still held 3 releases, with the official one the newest). To test it with a real source commit, save a skill edit without publishing it. The numbers below come from a CLI that already had releases 1.0.1 and 1.0.2, so yours will be lower. skill set commits the file to the hosted repository, so changes then reports one commit ahead:

okibi clis skill set acme-orders --file SKILL.new.md --json
okibi clis changes acme-orders --json
{ "latestVersion": 4, "releaseVersion": "1.0.3", "commitsAhead": 1, "status": "ahead",
  "compareUrl": "https://github.com/okibi-hosted/<workspace>-acme-orders-2/compare/<base>...<head>" }

okibi clis publish acme-orders --json then built that commit as the next version and did not promote it:

{ "publishedVersion": 5, "releaseVersion": "1.0.4" }

okibi clis releases acme-orders --json listed 1.0.4 with kind repository-update, and the official release was still 1.0.2. After okibi clis release set acme-orders --release <1.0.4 id>, a fresh install printed acme-orders 1.0.4, and its SKILL.md contained the new line (202 lines). changes went back to up-to-date with commitsAhead 0. (The 1.0.3 in that sequence is a configuration-update release that Okibi built when command analytics were turned on.) To read the OpenAPI spec a CLI builds from, use okibi spec source acme-orders. The older spec edit command no longer exists.

Run commands before documenting them

The skill is read by agents, so a wrong note causes wrong calls. Both notes added here were checked with a live call first. The cancel command in the CLI is orders cancel order <id>, which differs from the shorter form older guides used.


verification:
  status: verified
  tested_at: "2026-11-02"
  product_version: "okibi 0.2.11; acme-orders 1.0.2"
  command: "okibi clis skill show acme-orders --json | python3 -c \"import json,sys;print(json.load(sys.stdin)['content'])\" | grep -c 'Known gotchas'"
  expected_result: "A count of 1 or higher, and clis changes reports the release version returned by skill publish with status up-to-date. The version number depends on prior releases. A source commit was published with okibi clis publish and promoted with release set."

Related Articles