Skip to main content
Kairos ships a skill file that teaches a host agent everything it needs: how to install Kairos, how to interview you about what it may do, how to give it a task, and how to read what it did. The file is generated from the same contracts the backant CLI executes, so what your agent reads and what the CLI does cannot drift.
Needs backant-kairos 1.6.0 or newer. Run npx backant-kairos@latest if you installed earlier.

​
Install the skill

Install once per machine, where your agent discovers skills:
Writes the skill for every host that is present and reports the others as skipped.
Re-run after upgrading backant-kairos. The install is idempotent; an unchanged file is left alone.

​
What to say to your agent

Open your agent inside the repository and talk to it. The skill tells it which commands to run.

​
How the interview works

Setup writes .backant.toml with safe defaults: no merging, no CI or infrastructure edits, gates on push and PR creation. The interview turns those defaults into your decisions.
1

Status first

The agent runs backant ctl config status --json. Every key comes back with its value, its default, and a source: default (unanswered), answered (you decided), or skipped (does not apply right now, for example merge_migrations while merge is false).
2

One question per turn

For each unanswered key, in order, the agent asks the key’s question in your chat, tells you why it matters and what the current value is, and offers keeping it as an answer.
3

Every answer is written and recorded

backant ctl config set <key> <value> --issuer <agent name> --json rewrites the file and logs who answered and when. Keeping the current value or saying “you decide” still writes it, so it counts as answered.
4

Stop when complete

The agent re-runs status until complete is true and problems is empty, then summarizes what Kairos may now do.
Changes apply on the next turn. No restart. The answers are yours to audit: backant ctl events --type config_answered --json lists every answer with issuer and time, and backant ctl config get <key> --json shows who set a key.
ctl config set rewrites the whole file from the contract. Hand-written comments and unknown keys are dropped, and the envelope lists them under dropped. Change the file through the CLI, not by hand, once your agent manages it.

​
Give Kairos a task

This creates a GitHub issue in the repo, labeled kairos-task, and pins it as a directive. The envelope returns the issue number, its URL, and the directive id. Needs gh installed and authenticated. To see it picked up: backant ctl status --json shows pending directives, and once Kairos has taken it, backant ctl explain --json shows the decision that did.

​
The config contract

Every key your agent can ask about, in the order it asks. Live copy: backant ctl config schema --json. Values are typed. Booleans are true or false, arrays are JSON ('["src/**"]'), enums must be one of the listed values. Strings cannot contain commas, quotes, hashes, or control characters, and numbers must be plain non-negative decimals, because the file is read line by line. A value the reader could not read back is rejected before it is written.

​
Read the skill yourself

Prints the exact document your agent installed. A copy of the current release is served at backant.io/kairos/SKILL.md. Do not edit the file by hand; the next skill install overwrites it.

​
For agent authors

Every backant ctl verb takes --json and answers with exactly one line:
Exit code 0 on success, 2 for bad_input and not_a_workspace, 3 for not_found, 4 for a state conflict, 1 for anything unexpected. The hint is always something the agent can run next. The full table of verbs, flags, and examples is in the skill file; each example there is executed by the CLI’s own test suite.