docs: clarify triage preflight checks and repo guidelines (#153)

Reorder the antithesis-triage preflight as an ordered checklist (auth key,
snouty doctor, API reachability) so failures get surfaced one cause at a
time. Expand AGENTS.md with what `make validate` actually checks, the
sibling `<skill>-test/` harness convention, and an explicit note on the
automation that owns version bumps and CHANGELOG entries. Add a
CLAUDE.md that points Claude Code at AGENTS.md.

Author: carlsverre

AGENTS.md

@@ -11,8 +11,16 @@ https://agentskills.io/specification.md
 
 ## Build, Test, and Development Commands
 
-- `make validate`: validates all SKILLS align with the specification.
-- `make validate-changelog`: validates CHANGELOG.md format.
+- `make validate`: checks each `*/SKILL.md` for YAML frontmatter, a `name`
+  that matches its directory, a non-`TODO` `description`, and at least one
+  top-level `# ` heading. This is the canonical structural check.
+- `make validate-changelog`: validates `CHANGELOG.md` format.
+- `make validate-links`: runs the `lychee` link checker (config in
+  `lychee.toml`).
+- `make test`: runs unit tests for skill helper scripts (`process-logs.py`
+  in triage and debug; `build-url.py` in query-logs).
+- `make install-dev`: bootstraps the dev environment via
+  `scripts/install.sh`.
 
 ## Coding Style & Naming Conventions
 
@@ -32,6 +40,13 @@ Testing is validation-driven:
 - Scope: verifies presence and correctness of frontmatter, heading requirements, and skill discovery via `*/SKILL.md`.
 - For validator updates, test both pass and fail paths (for example, a missing `description` should fail).
 
+Some skills also ship a live integration harness as a sibling directory
+(`<skill>-test/`, e.g. `antithesis-debug-test/`, `antithesis-query-logs-test/`).
+These exercise the skill end-to-end against a real Antithesis tenant via
+`agent-browser` and are invoked manually with `<skill>-test/run.sh ...`. They
+are not wired into `make validate` or `make test` — see each harness's
+`README.md` for prerequisites.
+
 ## Commit & Pull Request Guidelines
 
 Use clear, conventional commit messages such as:
@@ -43,10 +58,18 @@ PRs should include:
 
 - What changed and why.
 - Validation evidence (`make validate` output).
-- Any follow-up work or limitations.
+- Any follow-up work for future PRs or limitations. Omit if irrelevant.
+
+## Automation: do not bump versions or edit the changelog by hand
+
+Scripts in `.ci-scripts/` run on merge and handle these chores for you. Do not
+propose or perform them as part of a PR.
+
+- `update_skill_versions.py` manages `metadata.version` in every `SKILL.md`.
+- `changelog.py` appends an entry to `CHANGELOG.md` from the PR title (and the
+  `changelog - breaking` / `changelog - non-breaking` label, if present). For
+  notable changes (new skills, breaking changes, significant fixes), add the
+  appropriate label; breaking entries are prefixed with `BREAKING CHANGE:`.
 
-For notable changes (new skills, breaking changes, significant fixes), add a
-`changelog - breaking` or `changelog - non-breaking` label to the PR. A bot
-updates `CHANGELOG.md` automatically on merge using the PR title — breaking
-entries are prefixed with `BREAKING CHANGE:`. Do not edit `CHANGELOG.md`
-directly.
+Edit `SKILL.md` content freely, but leave the `metadata.version` field alone,
+and do not edit `CHANGELOG.md` directly unless directly requested by the user.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

antithesis-triage/SKILL.md

@@ -23,25 +23,23 @@ Use this skill to analyze Antithesis test runs.
 - DO NOT PROCEED if `jq` is not installed. See `https://jqlang.org/download/` for installation options.
 - **Note:** `snouty runs` may be hidden from `snouty --help` but is still supported. If you need to confirm availability or see subcommand syntax, `snouty runs --help` still works.
 
-### API access (rollout in progress)
+### Preflight: confirm triage can work
 
-This version of the triage skill talks to Antithesis through the snouty API (`snouty runs ...`). The API is currently being rolled out to all tenants; however, you may encounter a tenant that isn't updated yet. You should detect access before continuing unless you already know (from context or memory) that the tenant in question has the API enabled.
+This version of the triage skill talks to Antithesis through the snouty API (`snouty runs ...`). Several things can prevent that from working. Walk down the checklist below in order — it is ordered from the most-likely cause (auth not exported) to the least-likely (tenant missing API access). Stop at the first failing check and surface **only that cause** to the user; do not list the others. Do not attempt real triage work until every check passes.
 
-**Detect missing API access** before doing real work:
+You can skip preflight if you already know (from context or memory) that the user's setup is working.
 
-1. Check that `$ANTITHESIS_API_KEY` is set. `snouty doctor` reports this too.
-2. If unset, ask the user whether their tenant has API access. If they don't
-   know or say no, treat the API as unavailable.
-3. Optionally probe: `snouty runs list -n 1` — if it fails with an error, the tenant is not yet enrolled.
+1. **Is `$ANTITHESIS_API_KEY` set?** This is the most common cause of failure. If unset, tell the user to export it (e.g., `export ANTITHESIS_API_KEY=<their key>`) and stop. Do not speculate about other causes.
 
-**If API access is unavailable**, do NOT attempt to run this skill. Instead, tell the user to either:
+2. **Does `snouty doctor` pass?** Run `snouty doctor`. If it reports any failure, relay that failure to the user and stop. Today this mostly re-confirms environment variables, but it is the canonical place where key validity, network reachability, and API-access checks will be surfaced as they are added — so always run it here.
 
-- **Contact Antithesis support** to request API access for their tenant.
-- **Or downgrade this skill** to the previous browser-based version on the
-  `agent-browser-triage` branch:
-  `https://github.com/antithesishq/antithesis-skills/tree/agent-browser-triage`
+3. **Can the API actually be reached?** Probe with `snouty runs list -n 1`. If this errors, the most likely remaining cause is that the tenant is not yet enrolled in the snouty API rollout. Tell the user to either:
+   - **Contact Antithesis support** to request API access for their tenant, or
+   - **Downgrade this skill** to the previous browser-based version on the
+     `agent-browser-triage` branch:
+     `https://github.com/antithesishq/antithesis-skills/tree/agent-browser-triage`
 
-This fallback is temporary and will be removed once the API rollout completes.
+   This fallback is temporary and will be removed once the rollout completes.
 
 ## Gathering user input