# The use-andon skill

The Andon agent installs a `use-andon` skill so the coding agents on the machine (Claude Code, Codex, Gemini CLI,
Cursor, Hermes and [the rest below](#where-it-goes)) can use the `andon` CLI from any repository: add and steer cards, put a plan on the board,
say what needs you, and check this machine's agent. There is nothing to install by hand. The agent writes the skill at
`andon setup` and syncs it every time it starts, which covers `andon up`, the desktop app, app updates and the agent's
daily self-update.

## Turn it off or on

| To | Run |
|---|---|
| remove it from every coding agent on the machine and keep it off | `andon policy cli-skill off` |
| put it back | `andon policy cli-skill on` |
| repair a missing or edited copy when the agent is already current | `andon update` |

## After you install a new coding agent

The skill goes only to coding agents the machine already has. After you install a new one, sync it.

Run `andon policy cli-skill on`, which syncs at once. Restarting the Andon agent also works: `andon install-service` on a
Mac, `systemctl --user restart andon-agent.service` on Linux, or `pnpm andon:up --stop` then `pnpm andon:up` for a local instance run from a clone.

A self-hosted server in Docker doesn't install the skill: it comes with the agent on each machine.

## Where it goes

The agent keeps one copy in its own folder, `~/.local/share/andon/skills/use-andon` (under `$XDG_DATA_HOME` when that
is set), and links it into the skills folder of each coding agent it finds on the machine. An update rewrites the one
copy. Where a link can't be made, or the folder already holds a page of your own, it keeps a copy there instead.

| Folder | Read by |
|---|---|
| `~/.claude/skills/use-andon` (`$CLAUDE_CONFIG_DIR` when set) | Claude Code, and Andon's own Claude accounts, which share it |
| `~/.agents/skills/use-andon` | Codex, Gemini CLI, Cursor, OpenCode, Qwen Code, Kimi, Devin, Amp, Factory Droid, Roo Code |
| `~/.copilot/skills/use-andon` (`$COPILOT_HOME` when set) | GitHub Copilot (the CLI and VS Code) |
| `~/.gemini/config/skills/use-andon` | Google Antigravity |
| `~/.kiro/skills/use-andon` | Kiro |
| `~/.hermes/skills/use-andon` (`$HERMES_HOME` when set), and `skills/use-andon` in each profile under `~/.hermes/profiles/` | Hermes Agent: each profile reads only its own folder |

Cursor, OpenCode, Kimi and Amp also read `~/.claude/skills`. With Claude Code's copy in place, they don't need the
shared folder, so the agent doesn't link it for them alone; a second copy would list the skill twice. Aider has no
skills and gets nothing.

A `SKILL.md` in one of these folders that the agent didn't write is yours, and the agent leaves it alone, as it does a
reference page you added. The skill is called `use-andon` so a skill of your own named `andon` can sit beside it.
A `skills/andon` folder the agent wrote is removed at the next sync.

## What is in it

`SKILL.md` covers one card: find the team and project, write the card, add it, read and change it, group and run cards,
and what needs your yes first. Four reference pages cover the rest, and a session reads one when the request needs it:

| Page | For |
|---|---|
| `references/plan-to-cards.md` | a plan or spec as several cards, each naming the skills its run should use |
| `references/needs-you.md` | what is running, stuck or waiting on you, and how to answer it |
| `references/machine.md` | this machine's agent: policy, repositories, accounts, providers, device keys, tunnel, updates, memory |
| `references/harness.md` | importing, approving and attaching a [harness](https://andon-docs.pages.dev/machines/harnesses.md) |

The card commands' flags in the skill are the CLI's own usage text, so they match the installed build. `andon --help`
is the full list.
