Add embedded Claude Code Skills + AGENTS.md for AI agents

AGENTS.md

@@ -0,0 +1,58 @@
+# APImetrics CLI — agent guide
+
+Instructions for AI coding agents (OpenAI Codex, Cursor, Gemini CLI, and any tool that reads `AGENTS.md`) operating the `apimetrics` CLI in this repository. Claude Code users get the same guidance as installable skills — see [Skill parity](#skill-parity).
+
+## Prerequisites
+
+1. `apimetrics project show` — confirm a project is active. Every project-scoped command fails without one. If none is set, run `apimetrics project select`.
+2. `apimetrics login` handles authentication (OAuth). **There is no `--api-key` flag.**
+
+## Core facts about this CLI
+
+- **Commands are flat, generated from the platform's live OpenAPI description**: `list-calls`, `create-call`, `run-call` — not `calls create`. The set can change with the server spec, so treat `apimetrics --help` and `apimetrics <command> --help` as authoritative and inspect a command's help before assuming an option or body field.
+- **Create/update commands read JSON from stdin** via heredoc. There is no `--body`, `--data`, or `-d`:
+  ```bash
+  apimetrics create-call <<'EOF'
+  { "meta": { "name": "Health" }, "request": { "method": "GET", "url": "https://example.com/health" } }
+  EOF
+  ```
+  CLI Shorthand is also accepted (`apimetrics create-call meta.name: "Health", request.method: GET, request.url: https://example.com/health`).
+- **Output**: `-o json` for machine use; `-f` projects with a shorthand query; `-q` adds confirmed query params. The command spec is cached ~24h and refreshes automatically; `--rsh-no-cache` forces a refresh.
+- **List envelopes are not uniform.** `list-calls`, `list-results`, `list-call-results`, and `list-auth-settings` return `{ "meta": ..., "results": [...] }`; `list-schedules` returns `{ "data": [...] }`; `list-slos`, `list-browser-monitors`, and `list-mcp-monitors` return a bare `{ "results": [...] }`. Inspect each command's own output before writing an `-f` path.
+- **`get-result` is a summary** (`result`, `http_code`, `response_time` ms, `location_id`, `test`, `created`; `result` ∈ `PASS`/`FAIL`/`WARN`/`ERROR`/`TIMEOUT`/`QUEUED`). Deeper data comes from `get-result-content`, `get-result-screenshot`, the `query-*-performance`/`query-*-dns-diagnostics` commands, and `conformance-results`.
+- **Percentiles are server-computed** by the `query-*-performance` commands (`measures`: `mean`/`p50`/`p90`/`p95`/`p99`; API `metrics`: `total`/`dns`/`connect`/`tls`/`ttfb`/`response`). Do not hand-average result summaries.
+- **API assertions** are set with `set-call-conditions <call-id>` (read with `get-call-conditions`), not in the `create-call` body.
+- **Bulk config-as-code** lives under the hidden `apimetrics bulk` group (`init <url>` e.g. `apimetrics:/monitors`, `status`, `diff [--remote]`, `pull`, `reset`, `push`).
+- **Never print secrets.** Reference auth settings by ID (`auth_id`/`token_id`); never paste tokens, cookies, keys, or certificate contents.
+
+## Workflows (skills)
+
+Each entry names when to reach for it and the key commands. Full step-by-step workflows — including safety gates, evidence rules, and output templates — are in `skills/claude-skills/<name>/SKILL.md`; read that file before executing the workflow. Run `apimetrics onboard` to print every workflow to stdout for context injection.
+
+| Workflow | Use when | Key commands |
+|---|---|---|
+| **project-bootstrap** | setting up monitoring / onboarding a service | `project select`, `create-call`/`create-browser-monitor`/`create-mcp-monitor`, `set-call-conditions`, `create-schedule`, `add-call-to-schedule`, `run-call`/`run-monitor` |
+| **weekly-health-review** | reliability report for the last 7 complete days | `list-results --since --before`, `query-api-performance`, `list-calls` |
+| **failure-investigation** | root-causing one failing result or a series | `get-result`, `list-call-results --since --before`, `get-result-content`, `query-api-monitor-dns-diagnostics`, `get-call-conditions` |
+| **incident-triage** | blast radius / common cause across many monitors | `list-results --since --before`, `query-api-dns-diagnostics`, `query-api-performance` |
+| **monitoring-estate-audit** | coverage & hygiene governance review | `list-calls`, `list-schedules`, `list-slos`, `list-auth-settings`, `list-calls-by-auth` |
+| **slo-review** | SLO design & attainment (no attainment endpoint — derive it) | `list-slos`, `get-slo`, `list-results`, `query-api-performance` |
+| **config-as-code** | reviewed bulk edits with rollback | `bulk init apimetrics:/monitors`, `bulk status`, `bulk diff`, `bulk push`, `bulk reset` |
+| **performance-analytics** | latency percentiles, component timing, DNS drift | `query-api-performance`, `query-api-monitor-performance`, `query-api-dns-diagnostics`, `query-browser-performance`, `query-mcp-performance` |
+
+## Safety
+
+- Mutating workflows (`project-bootstrap`, `config-as-code`) require explicit user intent, a pre-change snapshot, and a stated rollback path. Never `bulk push` from a dirty or drifted checkout.
+- Read-only analysis workflows make no changes.
+- Every reported percentage carries a numerator and denominator; every root-cause statement carries confidence and evidence.
+- Never weaken an assertion just to turn a real failure green.
+
+## Skill parity
+
+The eight workflows above are shipped to Claude Code as native skills:
+
+```bash
+apimetrics skills install --claude-skills   # writes .claude/skills/<name>/SKILL.md
+```
+
+The same content backs this `AGENTS.md` and `apimetrics onboard`, so Claude Code and other agents operate from one source of truth.

README.md

@@ -193,11 +193,34 @@ apimetrics skills install --claude-code
 apimetrics onboard
 ```
 
-Available skills:
+Available setup skills:
 - `setup-api-monitor` — Create an API (HTTP) monitor, attach a schedule, and verify it
 - `setup-browser-monitor` — Create a browser monitor, attach a schedule, and verify it
 - `setup-mcp-monitor` — Create an MCP protocol monitor with session steps
 
+### Claude Code Skills (operational workflows)
+
+In addition to the setup commands above, the CLI ships eight richer, current-format **Claude Code Skills** covering the operational lifecycle. Install them into `.claude/skills/<name>/SKILL.md`:
+
+```bash
+apimetrics skills install --claude-skills
+```
+
+- `apimetrics-project-bootstrap` — select a project and stand up verified scheduled monitoring
+- `apimetrics-weekly-health-review` — analyze the previous seven complete days
+- `apimetrics-failure-investigation` — root-cause one result or a failure series
+- `apimetrics-incident-triage` — blast radius and common cause across monitors
+- `apimetrics-monitoring-estate-audit` — coverage, hygiene, stale/duplicate monitors
+- `apimetrics-slo-review` — SLO design, attainment, and error-budget risk
+- `apimetrics-config-as-code` — safe bulk checkout/diff/push workflow
+- `apimetrics-performance-analytics` — latency percentiles, component timing, and DNS analytics
+
+Read-only skills load automatically when a request matches; the two mutation skills require explicit invocation and gate every change behind approval.
+
+### Other agents (OpenAI Codex, Cursor, Gemini CLI, …)
+
+The repo root ships an [`AGENTS.md`](AGENTS.md) — the cross-agent standard read by OpenAI Codex, Cursor, Gemini CLI, and others — that carries the same core CLI facts and workflow index. Any agent can also pull the full workflows on demand with `apimetrics onboard`.
+
 ## Configuration
 
 Configuration and cached tokens are stored in platform-specific locations:

skills/claude-skills/apimetrics-config-as-code/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: apimetrics-config-as-code
+description: Check out APImetrics resources with the CLI bulk workflow, review and diff JSON changes, detect remote drift, and safely push authorized updates with a rollback path.
+argument-hint: "[resource collection or change goal]"
+disable-model-invocation: true
+---
+
+# APImetrics configuration as code
+
+Use the CLI's built-in hidden `bulk` workflow for local JSON checkout and synchronization. Treat `bulk push` as a production mutation requiring explicit approval.
+
+
+## Operating rules
+
+1. Use only the `apimetrics` CLI and Claude's normal shell/file tools. Do not require `jq`, Python, custom scripts, direct HTTP clients, or undocumented platform APIs.
+2. Begin with:
+   ```bash
+   apimetrics --version
+   apimetrics project show
+   apimetrics --help
+   ```
+   Run `apimetrics login` or `apimetrics project select` only when needed.
+3. The CLI command tree is generated from the platform's current OpenAPI description. Inspect `apimetrics <command> --help` before constructing a body or assuming an option name.
+4. Commands are generally flat (`list-calls`, `create-call`), not noun/verb groups.
+5. Create and update operations read JSON from stdin. Use a quoted heredoc:
+   ```bash
+   apimetrics <create-or-update-command> ... <<'EOF'
+   {
+     "example": true
+   }
+   EOF
+   ```
+   Do not invent `--body`, `--data`, or `-d`.
+6. Use `-o json` for analysis. Use `-f` only after inspecting the response shape. The top-level response envelope includes status, headers, and `body`. List bodies are NOT uniform: `list-calls`, `list-results`, `list-call-results`, and `list-auth-settings` return `{"meta":..., "results":[...]}`; `list-schedules` returns `{"data":[...]}`; `list-slos`, `list-browser-monitors`, and `list-mcp-monitors` return a bare `{"results":[...]}` with no `meta`/pagination. Inspect each command's own output before writing an `-f` path (e.g. `-f body.results[0]` vs `-f body.data[0]`).
+7. Use `-q key=value` only for query parameters confirmed by command help or observed request documentation.
+8. Preserve evidence. Record the active project, commands run, IDs, time window, and the smallest response excerpts needed to support conclusions.
+9. Never print, store, or paste credentials into the report. Prefer existing auth-setting IDs. Do not include bearer tokens, cookies, API keys, client secrets, or private certificate contents.
+10. Do not mutate project configuration unless the user explicitly authorized the change. Before any mutation, show the planned objects and rollback path.
+11. Do not poll in a tight loop. Use sensible pauses and bounded attempts.
+12. When a command is absent, report the limitation and show the closest CLI-supported path. Do not fabricate a command.
+
+
+## Important capability
+
+The CLI includes:
+
+```bash
+apimetrics bulk init
+apimetrics bulk list
+apimetrics bulk status
+apimetrics bulk diff
+apimetrics bulk pull
+apimetrics bulk reset
+apimetrics bulk push
+```
+
+Confirm with:
+
+```bash
+apimetrics bulk --help
+```
+
+The bulk workflow keeps metadata and resource versions, detects local and remote changes, and can avoid overwriting local edits during pull.
+
+## Workflow
+
+### 1. Establish scope and safety
+
+Confirm:
+
+- active project
+- resource collection
+- isolated working directory
+- intended change
+- approval boundary
+- rollback owner
+
+Do not initialize into a directory containing unrelated JSON files.
+
+### 2. Initialize the checkout
+
+`bulk init` takes exactly one URL argument that returns a list of resources, each with a link and a version. Use the CLI's own API-name scheme (`apimetrics:/<collection>`) rather than a raw host — the repository's own example is:
+
+```bash
+apimetrics bulk init apimetrics:/monitors
+```
+
+`init` auto-detects the resource URL from `url`/`uri`/`self`/`link` and the version from `version`/`etag`/`last_modified`/`lastModified`/`modified`. If the collection response doesn't expose those directly, shape it with `-f` and/or build links from IDs with `--url-template`:
+
+```bash
+apimetrics bulk init apimetrics:/monitors -f 'body.{url, version: last_update}'
+apimetrics bulk init apimetrics:/monitors -f 'body.{id, version: last_update}' --url-template='/monitors/{id}'
+```
+
+Always confirm the exact flags first:
+
+```bash
+apimetrics bulk init --help
+```
+
+Do not guess an undocumented host path; prefer the `apimetrics:` scheme, which resolves against the CLI's configured server. `bulk` is a hidden command group — it will not appear in the top-level `--help` list, but `apimetrics bulk --help` is authoritative.
+
+### 3. Baseline
+
+Run:
+
+```bash
+apimetrics bulk status
+apimetrics bulk list
+```
+
+Read the metadata and checked-out JSON. Record a clean baseline before editing. If remote changes already exist, pull or reconcile first.
+
+### 4. Edit and validate
+
+Make only the authorized JSON changes. Preserve IDs, versions, references, and unrelated fields.
+
+Run:
+
+```bash
+apimetrics bulk status
+apimetrics bulk diff
+```
+
+Review every changed, added, and removed resource. Use `--match` only after testing the expression against `bulk list`.
+
+### 5. Reconcile remote drift
+
+Immediately before push:
+
+```bash
+apimetrics bulk status
+apimetrics bulk diff --remote
+```
+
+If remote changes exist, stop and reconcile. `bulk pull` does not overwrite local changes, but conflicts still require deliberate review.
+
+### 6. Approval gate
+
+Present:
+
+- exact resources and IDs
+- unified diff
+- dependencies/references affected
+- expected operational effect
+- rollback plan
+- post-change verification
+
+Run `apimetrics bulk push` only after explicit approval in the current conversation.
+
+### 7. Verify
+
+After push:
+
+- run `bulk status` and require clean local/remote state
+- read changed resources through normal CLI commands
+- run affected monitors on demand
+- verify schedule targets and successful results
+- retain the before/after diff in the handoff
+
+### 8. Rollback
+
+For unpushed local edits:
+
+```bash
+apimetrics bulk reset [file...]
+```
+
+For pushed changes, restore the reviewed baseline JSON and push only with fresh approval. Do not treat `reset` as a remote rollback.
+
+## Hard rules
+
+- Never push from a dirty or drifted baseline.
+- Never bulk-edit auth secret values.
+- Never delete resources solely because files appear stale; verify references and recent results.
+- Never use bulk push as a discovery tool.