docs: move drift remediation, command and help-text workflows into skills (#1047, #1049, #1051)

[sdairs]

Closes #1047. Closes #1049. Closes #1051. Closes #1053. Stacked on #1046.

Moves four task-specific workflows out of AGENTS.md into repo skills that any coding agent can load, so agents read them only when the task needs them. They are in one PR because the skills and AGENTS.md refer to each other.

Changes

openapi-drift-remediation skill (#1047)

.agents/skills/openapi-drift-remediation/SKILL.md, with name/description frontmatter. It covers:

1. Reproducing the drift and grouping the findings by library domain and CLI command group.
2. Planning PR pairs: an API PR, then a CLI PR. One pair per affected command group when the drift spans several groups or adds a library module. Notes that spec_coverage_test fails until the last API PR lands, and to run the library tests with --no-fail-fast in the meantime.
3. The API PR: the fix for each finding kind, moved from the crate AGENTS.md, including the operation-permissions regeneration step.
4. The CLI PR: points at the add-cli-command skill.

add-cli-command skill (#1049)

.agents/skills/add-cli-command/, replacing the "Adding a command" section of the root AGENTS.md:

• SKILL.md: sends the agent to the local or Cloud procedure, then covers the steps both share: try_parse_from tests, both classifiers, the README and the gates. Includes a checklist the agent can copy.
• references/local.md: the local procedure. It now also covers the --json output struct and LocalErrorOutput::from_error (choosing parity or redaction), which the old section left out.
• references/cloud.md: the Cloud steps, including PERMISSIONS, rewritten in plain language, plus the files to change when adding a new command group.

cli-help-text skill (#1051)

.agents/skills/cli-help-text/SKILL.md, replacing the "Writing help text" section of the root AGENTS.md. Merged in from #1052. It covers:

• Where help lives, the screen shape, about and flag rules, and option order with the help_order ranks.
• The CONTEXT FOR AGENTS: block: at most 8 lines, written densely for agents. Permission lines from permissions.rs don't count toward the 8. What it may hold, with a precondition naming the command or flag that meets it. It never holds implementation details. Includes a before/after example.
• A one-line test rule: never pin help or README wording.
• A checklist: render each changed screen with --help, check each line, run the tests.

The add-cli-command and openapi-drift-remediation skills now point at it for help rules.

release skill (#1053)

.agents/skills/release/SKILL.md, replacing the "Releases" section of the root AGENTS.md. It covers the lockstep version bump, tagging the merge commit, and watching release.yml. It also covers a step that wasn't written down anywhere: run NightlyUpload in ClickHouse/ClickHouse (gh workflow run nightly_upload.yml -R ClickHouse/ClickHouse) as soon as Create Release succeeds. clickhousectl update, install.sh and the npm postinstall take the version from the GitHub release but download the archive from builds.clickhouse.com. That workflow otherwise runs once a day, so until it runs, all three get a 404 for the new version. The skill ends with a curl check of all four archives and a checklist.

Analyzer policy moved into the drift skill

The "Analyzer configuration and exemptions", "Enum value coverage" and "Extending the analyzer" sections of crates/clickhouse-cloud-api/AGENTS.md move to openapi-drift-remediation/references/analyzer.md. The crate file keeps the two rules any model change can hit: the VALUES const and deprecated-field gating. It also gets back the rename_all rule that the analyzer's error message points at. Step 3 of the drift skill now points at these rules instead of restating them.

Wiring

• Claude Code: .claude/skills/<name> symlinks to each of the four skills.
• .gitignore: .agents/ and .claude/ stay ignored (chctl skills installs there, and .claude/ holds worktrees), except for these skills and their symlinks.
• AGENTS.md: a line in Workspace points at the drift skill. "Adding a command" is now a pointer plus two lines on code layout, and "Writing help text" is a two-line pointer. The Tests section points at the help skill for the wording rule "Releases" is a one-line pointer to the release skill. The CloudError and telemetry invariants are cut down to the rules themselves, the Cloud integration label rules point at .github/CLOUD_INTEGRATION.md, and the hand-kept list of local test binaries is gone (15.5 KB → 8.0 KB).
• crates/clickhouse-cloud-api/AGENTS.md: the "Remediating a drift issue" procedure is replaced by a pointer to the drift skill. The model policy stays; the analyzer policy moves to the drift skill's reference (19.3 KB → 12.5 KB).
• Analyzer rename_all error: now points at crates/clickhouse-cloud-api/AGENTS.md, "OpenAPI drift", instead of a bare "AGENTS.md", and says "on models" rather than "in models.rs".
• .github/CLOUD_INTEGRATION.md: the intro now matches cloud-integration-decision.py. The planner runs on every same-repository push, and when it selects no live suites the check passes without the label.
• README.md: removes the note about closed stdout (| head) from the intro.
• scripts/check-openapi-drift.py: the drift issue's "Implementation Guide" points at the skill instead of carrying its own copy of the steps.

Authoring choices

These follow Anthropic's skill authoring best practices and OpenAI's Codex skills docs and model guidance:

• Each description is in the third person, says what the skill does and when to use it, and puts trigger words first, because Codex shortens descriptions when space is tight.
• Reference files sit one level below SKILL.md, so the agent loads only the one it needs.
• Plain imperatives, with no emphasis words. A reason is given only where it isn't obvious.

Gates

• Python tests: 96 pass.
• Neither classifier selects any suites for this diff.
• One Rust change, an error message. Library clippy is clean, and the clickhouse-openapi-analyzer and clickhouse-cloud-api tests pass.

🤖 Generated with Claude Code