# Coding agents

A coding agent can set up and maintain your monitors with the CLI. Give it the Waitcher skill and a session (yours, or a [project token](access.md#project-reach)).

## Install the skill

```sh
waitcher skill install             # .claude/skills/waitcher in this repository
waitcher skill install --global    # ~/.claude/skills/waitcher
waitcher skill install --path .agents/skills    # Codex and other agents that read .agents/skills
waitcher skill install --path SKILLS_DIR
waitcher skill show                # print the skill and its references as JSON
```

The skill is a short `SKILL.md` with the repository workflow and its rules, plus references on authoring tests, deploys, diagnosis, optional capabilities and AI or agent checks that the agent loads when needed. Commit the project copy so every agent working in the repository finds it. Run `skill install` again after upgrading the CLI; it never replaces a skill directory it did not write.

The skill tells the agent to keep new monitors paused, show you the plan before applying, ask before `--activate-new`, `--prune`, `--adopt` or `--smoke`, pipe secrets through `--value-stdin`, and never weaken assertions or switch accounts to get a green result.

## doctor

```sh
waitcher doctor [--file waitcher.json] [--env NAME]
```

A read-only check of the setup: Node version, `waitcher.json`, entry builds and the pinned runtime, whether the skill is installed where agents look and matches this CLI version, the session, your account's capabilities and a hosted plan per environment. Each check is `ok`, `warning`, `error` or `skipped` with `next` commands; any error exits 2. Start here when something does not work.

## explain

```sh
waitcher explain              # every code
waitcher explain SECRET_MISSING
```

Works offline. Prints the title, meaning, fix and exit code of any issue or error code the CLI can print. Deploy issue hints come from the same catalogue. See [Troubleshooting](troubleshooting.md).

## Skill, help and docs

Each source has one job, so an agent reads little and never works from stale syntax:

| Source | Holds | Read it |
| --- | --- | --- |
| The skill | The workflow, its order and the rules | Loaded by the agent at the start |
| `waitcher --help` | A short overview: where to start and which topic covers what | First, to find a topic |
| `waitcher help TOPIC` | Exact syntax and constraints for the installed CLI version, plus exit codes | Before running a command, for example `help deploy`, `help secret`, `help run` |
| `waitcher explain CODE` | Meaning and fix of an issue or error code | When a command reports one |
| This guide | Explanations for people, and setup outside the repository (alerts, tokens, account) | When the user needs to understand or decide something |

`waitcher help all` prints the full 28 KB help; agents rarely need it. Agents without the CLI can read this guide as Markdown ([Overview](README.md) has the addresses).