[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CBJGTKZPV0Y6A7RWQR9MYY":3,"skill-same:01M6CBJGTKZPV0Y6A7RWQR9MYY":85},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":54,"linkOnly":55,"markdownContent":56,"markdownBody":57,"frontMatter":58,"refName":61,"commitSha":62,"skillDirectory":63,"forksCount":64,"repositoryHtmlUrl":65,"repositoryHomepageUrl":66,"ownerHtmlUrl":67,"ownerBlogUrl":68,"ownerDescription":69,"updatedAt":70,"install":71,"resources":84},"01M6CBJGTKZPV0Y6A7RWQR9MYY","ai-agent-readonly-context",null,"Use when the user is WIRING CUB-SCOUT INTO AN AI AGENT (Claude \u002F Codex \u002F a custom LLM workflow) and needs the patterns for read-only context, MCP gateway tools, deterministic context snapshots, and the prompt-shape that makes cub-scout's output reliable for LLMs. Natural phrasing: \"set up cub-scout as a Claude tool\", \"expose cub-scout to my agent over MCP\", \"give the LLM a deterministic snapshot of this cluster\", \"what cub-scout patterns work well for AI agents?\", \"MCP config for cub-scout in Claude Code\", \"best practices for wiring cub-scout into Codex \u002F Cursor \u002F Continue\", \"AI-ready cluster context\", \"prompt template for cub-scout output\". Composes `mcp serve` + `context-pack` + `--presentation ai` + the structured JSON contracts. Do NOT load for: a specific verb invocation (load the corresponding scout-* skill), authoring an MCP server in general (this is about wiring CUB-SCOUT specifically), or any mutating workflow (cub-scout never mutates; the read-only triad is the whole point of this skill).","confighub\u002Fcub-scout","confighub","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F206140369?v=4","01M6CBJBWD33AFNG4VXMJHSRXD","ConfigHub Inc","01M6CBJC0K0F8CJVFWGRSR0KYC",14,"MIT","https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Fai-agent-readonly-context\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000003","演示文稿","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53],"ai agent readonly context","ai agent","readonly","context","tool","when","wiring","snapshots","up","ready","only","never","version","use","prompt","MCP","continue","Bash","SET","server","gateway","doctor","code","workflow","mcp server","llms","ai agents","2026-11-10 10:12:30",false,"---\nname: ai-agent-readonly-context\ndescription: 'Use when the user is WIRING CUB-SCOUT INTO AN AI AGENT (Claude \u002F Codex \u002F a custom LLM workflow) and needs the patterns for read-only context, MCP gateway tools, deterministic context snapshots, and the prompt-shape that makes cub-scout''s output reliable for LLMs. Natural phrasing: \"set up cub-scout as a Claude tool\", \"expose cub-scout to my agent over MCP\", \"give the LLM a deterministic snapshot of this cluster\", \"what cub-scout patterns work well for AI agents?\", \"MCP config for cub-scout in Claude Code\", \"best practices for wiring cub-scout into Codex \u002F Cursor \u002F Continue\", \"AI-ready cluster context\", \"prompt template for cub-scout output\". Composes `mcp serve` + `context-pack` + `--presentation ai` + the structured JSON contracts. Do NOT load for: a specific verb invocation (load the corresponding scout-* skill), authoring an MCP server in general (this is about wiring CUB-SCOUT specifically), or any mutating workflow (cub-scout never mutates; the read-only triad is the whole point of this skill).'\nphase: cross-cutting\nallowed-tools: Bash(.\u002Fcub-scout mcp *) Bash(cub-scout mcp *) Bash(cub scout mcp *) Bash(.\u002Fcub-scout context-pack *) Bash(cub-scout context-pack *) Bash(cub scout context-pack *) Bash(.\u002Fcub-scout doctor *) Bash(cub-scout doctor *) Bash(cub scout doctor *) Bash(.\u002Fcub-scout explain *) Bash(cub-scout explain *) Bash(cub scout explain *) Bash(.\u002Fcub-scout trace *) Bash(cub-scout trace *) Bash(cub scout trace *) Bash(.\u002Fcub-scout status) Bash(cub-scout status) Bash(cub scout status) Bash(.\u002Fcub-scout version) Bash(cub-scout version) Bash(cub scout version)\n---\n\n# ai-agent-readonly-context\n\nThe agent-integration loop. The user is wiring cub-scout into an AI agent — Claude Code, Codex, Cursor, Continue, a custom MCP-aware LLM — and needs the patterns that make cub-scout's output reliable for LLMs.\n\nThree patterns matter here, plus the prompt shape that ties them together:\n\n1. **MCP gateway** (`mcp serve`) — long-running tool surface the agent calls live\n2. **context-pack** (`context-pack --format json`) — deterministic one-shot snapshot the agent reasons over\n3. **`--presentation ai`** — output format with bracket notation + uppercase markers that LLMs parse reliably\n\nPlus the read-only invariant: every cub-scout tool an agent can call is **categorically non-mutating**. cub-scout is the safest possible AI surface because the worst-case prompt-injection still can't apply \u002F edit \u002F delete anything.\n\n## When to use\n\nExplicit phrasings:\n\n- \"Set up cub-scout as a Claude tool\"\n- \"Expose cub-scout to my agent over MCP\"\n- \"Give the LLM a deterministic snapshot of this cluster\"\n- \"What cub-scout patterns work well for AI agents?\"\n- \"MCP config for cub-scout in Claude Code \u002F Codex \u002F Cursor \u002F Continue\"\n- \"Best practices for wiring cub-scout into [agent framework]\"\n- \"AI-ready cluster context for my LLM workflow\"\n- \"Prompt template for cub-scout output\"\n- \"How do I make cub-scout JSON parseable by an LLM?\"\n\nImplicit intents:\n\n- The user is **integrating**, not running cub-scout interactively\n- The user values **determinism** (same input → same bytes)\n- The user values **read-only safety** (prompt injection can't escalate to cluster mutation)\n- The user may be combining cub-scout with `cub` \u002F `kubectl` \u002F other tools in the agent's tool set\n\n## Do not load for\n\n- A specific verb invocation — load the matching `scout-*` skill\n- Authoring an MCP server in general (this is about wiring cub-scout *specifically*) — use the MCP-server-authoring docs from the agent host\n- Mutating workflows. cub-scout never mutates; the read-only triad is the whole point of this skill.\n- ConfigHub-side MCP integration — that's `cub`, a separate tool surface\n\n## The patterns\n\n### Pattern 1 — MCP gateway (live tool calls)\n\n`cub-scout mcp serve` is a long-running MCP server exposing cub-scout's verbs as tools. Register it in your agent host's MCP config:\n\n```jsonc\n\u002F\u002F .claude\u002Fmcp_servers.json (Claude Code) — STDIO transport (preferred)\n{\n  \"mcpServers\": {\n    \"cub-scout\": {\n      \"command\": \"cub-scout\",\n      \"args\": [\"mcp\", \"serve\"],\n      \"env\": {\n        \"KUBECONFIG\": \"${env:HOME}\u002F.kube\u002Fconfig\"\n      }\n    }\n  }\n}\n```\n\nThe agent host calls `tools\u002Flist` to discover tools and `tools\u002Fcall` to invoke them. cub-scout's `mcp_test.go` covers the exact catalog:\n\n**Standalone-mode tools** (8, always available):\n- `doctor` — cluster-level diagnostic with structured nextSteps\n- `map` — resource inventory with ownership classification\n- `scan` — risk + misconfiguration findings\n- `trace` — ownership + source chain (one resource)\n- `explain` — plain-English per-resource report\n- `gitops_status` — GitOps\u002Fcontroller delivery status and coverage evidence\n- `gitops_settings` — the delivery settings each Argo CD and Flux deployer declares (auto-sync, self-heal, prune, suspension); declared settings only, no verdict (preview)\n- `release_check` — whether one exact, digest-pinned configuration release reached a target, stage by stage; no application-success claim\n\n**Connected-mode tools** (13, added when the ConfigHub session check passes; since v2.14.0 that check and most of these reads go through the ConfigHub SDK, with no `cub` binary):\n- `compare_three_way` — DRY\u002FWET\u002FLIVE with rolled-up agreement\n- `compare_source_truth` — strategy-typed verdict (target + namespace + strategy required)\n- `confighub_attestations` — attestations ConfigHub records directly against one exact revision (space, unit and revision required); recorded claims, not an approval verdict\n- `confighub_changeorder_get` — exact-space reported ChangeOrder Stage\u002FState and declarations; evaluated outcomes unknown, including Completed\n- `confighub_changesets` — governed ChangeSet history from ConfigHub\n- `confighub_k8s_resources` — ConfigHub Resource-backed intended Kubernetes resources\n- `confighub_k8s_types` — ConfigHub Resource-backed intended Kubernetes type survey\n- `confighub_live_status` — ConfigHub Space live-status writeback with freshness\n- `confighub_releases` — bounded ConfigHub Release history\n- `confighub_resources` — generic ConfigHub Resource entity queries\n- `confighub_unit_events` — bounded ConfigHub UnitEvent history\n- `confighub_units` — ConfigHub unit + fleet inventory\n- `confighub_unit_get` — exact ConfigHub unit details + applied\u002Flive revision\n\nUse the standard MCP `tools\u002Flist` request to dump the registered catalog from\nthe running server. See [`references\u002Fmcp-tool-catalog.md`](..\u002Freferences\u002Fmcp-tool-catalog.md) for per-tool parameters, return shape, and the list of verbs intentionally NOT in the catalog.\n\n### Pattern 2 — context-pack (deterministic snapshot)\n\n`cub-scout context-pack --format json` produces a **one-shot deterministic** JSON snapshot of the cluster. Same input → same bytes. Safe to feed an LLM with prompt caching; safe to diff in CI.\n\n```bash\n$ cub-scout context-pack --format json > cluster-ctx.json\n$ wc -l cluster-ctx.json\n2347 cluster-ctx.json\n\n$ jq '.ownership | group_by(.type) | map({type: .[0].type, count: length})' cluster-ctx.json\n[\n  {\"type\": \"argo\",    \"count\": 47},\n  {\"type\": \"flux\",    \"count\": 12},\n  {\"type\": \"helm\",    \"count\": 8},\n  {\"type\": \"native\",  \"count\": 23},\n  {\"type\": \"unknown\", \"count\": 3}\n]\n```\n\nThe pack carries:\n- `version` — cub-scout build tag + context-pack schema version\n- `capturedAt` — RFC 3339 timestamp (the ONLY non-deterministic field; everything else is reproducible)\n- `cluster` — kubeconfig context + server URL\n- `mode` — `standalone` or `connected`\n- `resources[]` — per-workload kind \u002F name \u002F namespace \u002F ownership classification\n- `attribution[]` — per-resource attribution evidence (`cause`, `managerHint`, `gitSource`, `bindingSource`)\n- `omissions[]` — explicit non-claims (e.g., resources skipped due to CrashLoop, unsupported kinds)\n\nFor lower-level JSON artifacts outside `context-pack`, prefer the shared\n`observation` metadata when present. `map list --format json`, `snapshot`,\n`summary list --format json`, and `watch`\u002F`bot` events expose\n`observation.source`, `observation.mode`, `observation.observedAt`, and\n`observation.freshness` so an agent can tell whether it is reasoning over a\nfresh live read, stored summary evidence, a point-in-time snapshot, or an event\nfrom a polling observer.\n\nFeed it to the LLM as a system message context block:\n\n```\nYou have read-only access to a Kubernetes cluster snapshot via the JSON below.\nCluster: \u003Ccluster name>\nMode: \u003Cstandalone|connected>\nCaptured at: \u003CRFC3339>\n\n\u003Ccluster-ctx.json>\n\nYou can also call the following MCP tools for deeper reads: ...\n```\n\n### Pattern 3 — `--presentation ai`\n\nFor agent prompts that consume ASCII output (not JSON), `--presentation ai` produces a structured form LLMs parse reliably. Uppercase markers; bracket notation; consistent label-value separators.\n\n```bash\n$ cub-scout explain deploy\u002Fapi -n prod --presentation ai\n[explain]\nResource: Deployment\u002Fapi in prod\nOwner: Argo CD application \"payments-api\" [label:argocd.argoproj.io\u002Finstance]\nDrift: Detected\nMutation cause: manual-edit [manager: kubectl-edit; controller co-signal: argocd-controller]\nGit source: https:\u002F\u002Fgithub.com\u002Forg\u002Fplatform-config @abc123 path=apps\u002Fprod\u002Fapi\nEvents: ImagePullBackOff (5 mins ago, repeating)\nRecommended actions:\n  - [read-only] Image ghcr.io\u002Forg\u002Fapi:v2.3.0 cannot be pulled; check ghcr.io status\n  - [read-only] If image is correct, verify imagePullSecrets\n[end explain]\n```\n\nvs. the default human form:\n\n```bash\n$ cub-scout explain deploy\u002Fapi -n prod\nResource: Deployment\u002Fapi in prod\n  Owner: Argo CD application \"payments-api\"\n    (label:argocd.argoproj.io\u002Finstance)\n  ...\n```\n\nThe AI form is denser, less ambiguous, and parseable with regex if needed.\n\nAvailable on `doctor` \u002F `explain` \u002F `trace` (per `#352` \u002F `#359`). The `--presentation paired` flag emits both forms for human + AI dual-purpose output.\n\n## The read-only invariant\n\nThis is **the** value proposition for AI integration. cub-scout's MCP tool catalog is **closed and read-only by construction**:\n\n- Every tool wraps a read-only cub-scout verb with `--format json` or a read-only `cub` list\u002Fget query\n- Every verb is non-mutating\n- The tool catalog is verified by `cmd\u002Fcub-scout\u002Fmcp_test.go` — adding a tool requires a code change + a passing test\n- The receipt capability's `FilterNextSteps` (`pkg\u002Fagent\u002Freceipt_predicates.go`) strips mutating `actionType` \u002F `nextCommand` from any structured next-step hint before emit\n- `TestReceiptPackageReadOnlyClient` statically greps the receipt source for any mutating K8s client method\n\nConsequence: **even with a fully-compromised prompt**, an LLM calling cub-scout's MCP tools cannot apply \u002F edit \u002F patch \u002F delete anything. The blast radius is reads.\n\nThis is unusual — most operational tools mix read and write surfaces. cub-scout's #410 \u002F #428 architectural-triad work made the read-only carve-out a code-enforced invariant, not a convention. That's what makes cub-scout the safest Kubernetes MCP surface for AI agents today.\n\n## Worked example: Claude Code integration\n\n```jsonc\n\u002F\u002F .claude\u002Fmcp_servers.json\n{\n  \"mcpServers\": {\n    \"cub-scout\": {\n      \"command\": \"cub-scout\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n```jsonc\n\u002F\u002F .claude\u002Fskills.json — load the relevant scout-* skills\n{\n  \"skills\": [\n    \"scout-observe\", \"scout-diagnose\", \"scout-compare\", \"scout-attribute\",\n    \"scout-verify\", \"scout-mcp\",\n    \"triage-unhealthy-workload\", \"investigate-drift\"\n  ]\n}\n```\n\nUser prompt: *\"deploy\u002Fapi in prod is broken, what's going on?\"*\n\nAgent's likely loop:\n1. Trigger `triage-unhealthy-workload` skill\n2. Call MCP tool `doctor` (scope: namespace=prod)\n3. Call MCP tool `explain` (`deploy\u002Fapi -n prod`)\n4. Call MCP tool `trace` (`deploy\u002Fapi -n prod`)\n5. Read structured `nextSteps[]` + `events[]` from the responses\n6. Synthesize human-language explanation; route the mutation suggestion to the user\n\nThe agent NEVER calls a mutating MCP tool because **there are none registered**. The user drives `kubectl rollout undo` \u002F `argocd app rollback` from a separate context if needed.\n\n## Configuration tips\n\n- **Prefer STDIO over HTTP** for agent integration — lower latency, easier to sandbox, no port management.\n- **Set `KUBECONFIG` explicitly** in the MCP env block so the server picks up the right cluster context. Don't rely on the agent host inheriting it.\n- **For multi-cluster contexts**, run one `mcp serve` instance per cluster on different ports \u002F paths, OR use the `--context \u003Cname>` flag to switch contexts in-process. cub-scout doesn't support multi-context-in-one-server today (a single `mcp serve` is one context).\n- **Cache `context-pack` aggressively.** It's deterministic; an LLM with prompt caching benefits enormously from caching the snapshot across multiple queries.\n- **Use connected mode** if the agent is doing source-truth \u002F governance work. Check `confighub_reads` in `cub-scout status --json` first (`cub auth status` checks the same session when `cub` is installed); the agent should refuse to claim source-truth verdicts in standalone mode.\n\n## Tool boundary\n\n- **Allowed:** `mcp serve` (long-running but no mutation), `context-pack`, `status`, `version`, plus the read-only verbs the agent will indirectly call through MCP.\n- **Not allowed:** any mutating verb. The MCP gateway never registers one; the static guards in cub-scout enforce it.\n- **MCP and the triad:** cub-scout (evidence) ↔ MCP (transport) ↔ Pilot or agent (judge \u002F actor). The MCP layer is plumbing; it never decides.\n\n## References\n\n- [`scout-mcp`](..\u002Fscout-mcp\u002FSKILL.md) — the verb-group skill for `mcp serve` and `context-pack`\n- MCP tool descriptions audit: `#377`\n- `--presentation` flag: `#352` (doctor \u002F explain), `#359` (trace)\n- Connected MCP trust surface: [`docs\u002Freference\u002Fjson-contracts.md`](..\u002F..\u002Fdocs\u002Freference\u002Fjson-contracts.md) § \"MCP connected trust guidance\"\n- Context-pack format: [`docs\u002Fhowto\u002Fcontext-pack-v2.md`](..\u002F..\u002Fdocs\u002Fhowto\u002Fcontext-pack-v2.md)\n- Examples: [`examples\u002Fai-integration\u002F`](..\u002F..\u002Fexamples\u002Fai-integration\u002F), [`examples\u002Fmcp-gateway\u002F`](..\u002F..\u002Fexamples\u002Fmcp-gateway\u002F), [`examples\u002Fai-agent-quest\u002F`](..\u002F..\u002Fexamples\u002Fai-agent-quest\u002F)\n- Read-only triad: `#410`, `#428`\n\n## Constraints\n\n- The MCP tool catalog is **closed**. Adding tools requires a code change + a passing `mcp_test.go` test. Don't claim cub-scout has a mutating MCP tool — it doesn't, by design.\n- `context-pack` is **deterministic** (same input, same bytes) EXCEPT for the `capturedAt` timestamp. If you need byte-identical output across runs, set a fixed `capturedAt` in your wrapper.\n- For agent hosts that don't speak MCP yet, fall back to invoking cub-scout verbs directly via shell tools with `--format json --presentation ai`. The structured output is the same.\n- This skill's read-only invariant doesn't extend to `cub`. If the agent has BOTH cub-scout AND cub MCP tools registered, the cub side IS mutation-capable. Use a separate allowed-tools policy for that surface.\n","# ai-agent-readonly-context\n\nThe agent-integration loop. The user is wiring cub-scout into an AI agent — Claude Code, Codex, Cursor, Continue, a custom MCP-aware LLM — and needs the patterns that make cub-scout's output reliable for LLMs.\n\nThree patterns matter here, plus the prompt shape that ties them together:\n\n1. **MCP gateway** (`mcp serve`) — long-running tool surface the agent calls live\n2. **context-pack** (`context-pack --format json`) — deterministic one-shot snapshot the agent reasons over\n3. **`--presentation ai`** — output format with bracket notation + uppercase markers that LLMs parse reliably\n\nPlus the read-only invariant: every cub-scout tool an agent can call is **categorically non-mutating**. cub-scout is the safest possible AI surface because the worst-case prompt-injection still can't apply \u002F edit \u002F delete anything.\n\n## When to use\n\nExplicit phrasings:\n\n- \"Set up cub-scout as a Claude tool\"\n- \"Expose cub-scout to my agent over MCP\"\n- \"Give the LLM a deterministic snapshot of this cluster\"\n- \"What cub-scout patterns work well for AI agents?\"\n- \"MCP config for cub-scout in Claude Code \u002F Codex \u002F Cursor \u002F Continue\"\n- \"Best practices for wiring cub-scout into [agent framework]\"\n- \"AI-ready cluster context for my LLM workflow\"\n- \"Prompt template for cub-scout output\"\n- \"How do I make cub-scout JSON parseable by an LLM?\"\n\nImplicit intents:\n\n- The user is **integrating**, not running cub-scout interactively\n- The user values **determinism** (same input → same bytes)\n- The user values **read-only safety** (prompt injection can't escalate to cluster mutation)\n- The user may be combining cub-scout with `cub` \u002F `kubectl` \u002F other tools in the agent's tool set\n\n## Do not load for\n\n- A specific verb invocation — load the matching `scout-*` skill\n- Authoring an MCP server in general (this is about wiring cub-scout *specifically*) — use the MCP-server-authoring docs from the agent host\n- Mutating workflows. cub-scout never mutates; the read-only triad is the whole point of this skill.\n- ConfigHub-side MCP integration — that's `cub`, a separate tool surface\n\n## The patterns\n\n### Pattern 1 — MCP gateway (live tool calls)\n\n`cub-scout mcp serve` is a long-running MCP server exposing cub-scout's verbs as tools. Register it in your agent host's MCP config:\n\n```jsonc\n\u002F\u002F .claude\u002Fmcp_servers.json (Claude Code) — STDIO transport (preferred)\n{\n  \"mcpServers\": {\n    \"cub-scout\": {\n      \"command\": \"cub-scout\",\n      \"args\": [\"mcp\", \"serve\"],\n      \"env\": {\n        \"KUBECONFIG\": \"${env:HOME}\u002F.kube\u002Fconfig\"\n      }\n    }\n  }\n}\n```\n\nThe agent host calls `tools\u002Flist` to discover tools and `tools\u002Fcall` to invoke them. cub-scout's `mcp_test.go` covers the exact catalog:\n\n**Standalone-mode tools** (8, always available):\n- `doctor` — cluster-level diagnostic with structured nextSteps\n- `map` — resource inventory with ownership classification\n- `scan` — risk + misconfiguration findings\n- `trace` — ownership + source chain (one resource)\n- `explain` — plain-English per-resource report\n- `gitops_status` — GitOps\u002Fcontroller delivery status and coverage evidence\n- `gitops_settings` — the delivery settings each Argo CD and Flux deployer declares (auto-sync, self-heal, prune, suspension); declared settings only, no verdict (preview)\n- `release_check` — whether one exact, digest-pinned configuration release reached a target, stage by stage; no application-success claim\n\n**Connected-mode tools** (13, added when the ConfigHub session check passes; since v2.14.0 that check and most of these reads go through the ConfigHub SDK, with no `cub` binary):\n- `compare_three_way` — DRY\u002FWET\u002FLIVE with rolled-up agreement\n- `compare_source_truth` — strategy-typed verdict (target + namespace + strategy required)\n- `confighub_attestations` — attestations ConfigHub records directly against one exact revision (space, unit and revision required); recorded claims, not an approval verdict\n- `confighub_changeorder_get` — exact-space reported ChangeOrder Stage\u002FState and declarations; evaluated outcomes unknown, including Completed\n- `confighub_changesets` — governed ChangeSet history from ConfigHub\n- `confighub_k8s_resources` — ConfigHub Resource-backed intended Kubernetes resources\n- `confighub_k8s_types` — ConfigHub Resource-backed intended Kubernetes type survey\n- `confighub_live_status` — ConfigHub Space live-status writeback with freshness\n- `confighub_releases` — bounded ConfigHub Release history\n- `confighub_resources` — generic ConfigHub Resource entity queries\n- `confighub_unit_events` — bounded ConfigHub UnitEvent history\n- `confighub_units` — ConfigHub unit + fleet inventory\n- `confighub_unit_get` — exact ConfigHub unit details + applied\u002Flive revision\n\nUse the standard MCP `tools\u002Flist` request to dump the registered catalog from\nthe running server. See [`references\u002Fmcp-tool-catalog.md`](..\u002Freferences\u002Fmcp-tool-catalog.md) for per-tool parameters, return shape, and the list of verbs intentionally NOT in the catalog.\n\n### Pattern 2 — context-pack (deterministic snapshot)\n\n`cub-scout context-pack --format json` produces a **one-shot deterministic** JSON snapshot of the cluster. Same input → same bytes. Safe to feed an LLM with prompt caching; safe to diff in CI.\n\n```bash\n$ cub-scout context-pack --format json > cluster-ctx.json\n$ wc -l cluster-ctx.json\n2347 cluster-ctx.json\n\n$ jq '.ownership | group_by(.type) | map({type: .[0].type, count: length})' cluster-ctx.json\n[\n  {\"type\": \"argo\",    \"count\": 47},\n  {\"type\": \"flux\",    \"count\": 12},\n  {\"type\": \"helm\",    \"count\": 8},\n  {\"type\": \"native\",  \"count\": 23},\n  {\"type\": \"unknown\", \"count\": 3}\n]\n```\n\nThe pack carries:\n- `version` — cub-scout build tag + context-pack schema version\n- `capturedAt` — RFC 3339 timestamp (the ONLY non-deterministic field; everything else is reproducible)\n- `cluster` — kubeconfig context + server URL\n- `mode` — `standalone` or `connected`\n- `resources[]` — per-workload kind \u002F name \u002F namespace \u002F ownership classification\n- `attribution[]` — per-resource attribution evidence (`cause`, `managerHint`, `gitSource`, `bindingSource`)\n- `omissions[]` — explicit non-claims (e.g., resources skipped due to CrashLoop, unsupported kinds)\n\nFor lower-level JSON artifacts outside `context-pack`, prefer the shared\n`observation` metadata when present. `map list --format json`, `snapshot`,\n`summary list --format json`, and `watch`\u002F`bot` events expose\n`observation.source`, `observation.mode`, `observation.observedAt`, and\n`observation.freshness` so an agent can tell whether it is reasoning over a\nfresh live read, stored summary evidence, a point-in-time snapshot, or an event\nfrom a polling observer.\n\nFeed it to the LLM as a system message context block:\n\n```\nYou have read-only access to a Kubernetes cluster snapshot via the JSON below.\nCluster: \u003Ccluster name>\nMode: \u003Cstandalone|connected>\nCaptured at: \u003CRFC3339>\n\n\u003Ccluster-ctx.json>\n\nYou can also call the following MCP tools for deeper reads: ...\n```\n\n### Pattern 3 — `--presentation ai`\n\nFor agent prompts that consume ASCII output (not JSON), `--presentation ai` produces a structured form LLMs parse reliably. Uppercase markers; bracket notation; consistent label-value separators.\n\n```bash\n$ cub-scout explain deploy\u002Fapi -n prod --presentation ai\n[explain]\nResource: Deployment\u002Fapi in prod\nOwner: Argo CD application \"payments-api\" [label:argocd.argoproj.io\u002Finstance]\nDrift: Detected\nMutation cause: manual-edit [manager: kubectl-edit; controller co-signal: argocd-controller]\nGit source: https:\u002F\u002Fgithub.com\u002Forg\u002Fplatform-config @abc123 path=apps\u002Fprod\u002Fapi\nEvents: ImagePullBackOff (5 mins ago, repeating)\nRecommended actions:\n  - [read-only] Image ghcr.io\u002Forg\u002Fapi:v2.3.0 cannot be pulled; check ghcr.io status\n  - [read-only] If image is correct, verify imagePullSecrets\n[end explain]\n```\n\nvs. the default human form:\n\n```bash\n$ cub-scout explain deploy\u002Fapi -n prod\nResource: Deployment\u002Fapi in prod\n  Owner: Argo CD application \"payments-api\"\n    (label:argocd.argoproj.io\u002Finstance)\n  ...\n```\n\nThe AI form is denser, less ambiguous, and parseable with regex if needed.\n\nAvailable on `doctor` \u002F `explain` \u002F `trace` (per `#352` \u002F `#359`). The `--presentation paired` flag emits both forms for human + AI dual-purpose output.\n\n## The read-only invariant\n\nThis is **the** value proposition for AI integration. cub-scout's MCP tool catalog is **closed and read-only by construction**:\n\n- Every tool wraps a read-only cub-scout verb with `--format json` or a read-only `cub` list\u002Fget query\n- Every verb is non-mutating\n- The tool catalog is verified by `cmd\u002Fcub-scout\u002Fmcp_test.go` — adding a tool requires a code change + a passing test\n- The receipt capability's `FilterNextSteps` (`pkg\u002Fagent\u002Freceipt_predicates.go`) strips mutating `actionType` \u002F `nextCommand` from any structured next-step hint before emit\n- `TestReceiptPackageReadOnlyClient` statically greps the receipt source for any mutating K8s client method\n\nConsequence: **even with a fully-compromised prompt**, an LLM calling cub-scout's MCP tools cannot apply \u002F edit \u002F patch \u002F delete anything. The blast radius is reads.\n\nThis is unusual — most operational tools mix read and write surfaces. cub-scout's #410 \u002F #428 architectural-triad work made the read-only carve-out a code-enforced invariant, not a convention. That's what makes cub-scout the safest Kubernetes MCP surface for AI agents today.\n\n## Worked example: Claude Code integration\n\n```jsonc\n\u002F\u002F .claude\u002Fmcp_servers.json\n{\n  \"mcpServers\": {\n    \"cub-scout\": {\n      \"command\": \"cub-scout\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n```jsonc\n\u002F\u002F .claude\u002Fskills.json — load the relevant scout-* skills\n{\n  \"skills\": [\n    \"scout-observe\", \"scout-diagnose\", \"scout-compare\", \"scout-attribute\",\n    \"scout-verify\", \"scout-mcp\",\n    \"triage-unhealthy-workload\", \"investigate-drift\"\n  ]\n}\n```\n\nUser prompt: *\"deploy\u002Fapi in prod is broken, what's going on?\"*\n\nAgent's likely loop:\n1. Trigger `triage-unhealthy-workload` skill\n2. Call MCP tool `doctor` (scope: namespace=prod)\n3. Call MCP tool `explain` (`deploy\u002Fapi -n prod`)\n4. Call MCP tool `trace` (`deploy\u002Fapi -n prod`)\n5. Read structured `nextSteps[]` + `events[]` from the responses\n6. Synthesize human-language explanation; route the mutation suggestion to the user\n\nThe agent NEVER calls a mutating MCP tool because **there are none registered**. The user drives `kubectl rollout undo` \u002F `argocd app rollback` from a separate context if needed.\n\n## Configuration tips\n\n- **Prefer STDIO over HTTP** for agent integration — lower latency, easier to sandbox, no port management.\n- **Set `KUBECONFIG` explicitly** in the MCP env block so the server picks up the right cluster context. Don't rely on the agent host inheriting it.\n- **For multi-cluster contexts**, run one `mcp serve` instance per cluster on different ports \u002F paths, OR use the `--context \u003Cname>` flag to switch contexts in-process. cub-scout doesn't support multi-context-in-one-server today (a single `mcp serve` is one context).\n- **Cache `context-pack` aggressively.** It's deterministic; an LLM with prompt caching benefits enormously from caching the snapshot across multiple queries.\n- **Use connected mode** if the agent is doing source-truth \u002F governance work. Check `confighub_reads` in `cub-scout status --json` first (`cub auth status` checks the same session when `cub` is installed); the agent should refuse to claim source-truth verdicts in standalone mode.\n\n## Tool boundary\n\n- **Allowed:** `mcp serve` (long-running but no mutation), `context-pack`, `status`, `version`, plus the read-only verbs the agent will indirectly call through MCP.\n- **Not allowed:** any mutating verb. The MCP gateway never registers one; the static guards in cub-scout enforce it.\n- **MCP and the triad:** cub-scout (evidence) ↔ MCP (transport) ↔ Pilot or agent (judge \u002F actor). The MCP layer is plumbing; it never decides.\n\n## References\n\n- [`scout-mcp`](..\u002Fscout-mcp\u002FSKILL.md) — the verb-group skill for `mcp serve` and `context-pack`\n- MCP tool descriptions audit: `#377`\n- `--presentation` flag: `#352` (doctor \u002F explain), `#359` (trace)\n- Connected MCP trust surface: [`docs\u002Freference\u002Fjson-contracts.md`](..\u002F..\u002Fdocs\u002Freference\u002Fjson-contracts.md) § \"MCP connected trust guidance\"\n- Context-pack format: [`docs\u002Fhowto\u002Fcontext-pack-v2.md`](..\u002F..\u002Fdocs\u002Fhowto\u002Fcontext-pack-v2.md)\n- Examples: [`examples\u002Fai-integration\u002F`](..\u002F..\u002Fexamples\u002Fai-integration\u002F), [`examples\u002Fmcp-gateway\u002F`](..\u002F..\u002Fexamples\u002Fmcp-gateway\u002F), [`examples\u002Fai-agent-quest\u002F`](..\u002F..\u002Fexamples\u002Fai-agent-quest\u002F)\n- Read-only triad: `#410`, `#428`\n\n## Constraints\n\n- The MCP tool catalog is **closed**. Adding tools requires a code change + a passing `mcp_test.go` test. Don't claim cub-scout has a mutating MCP tool — it doesn't, by design.\n- `context-pack` is **deterministic** (same input, same bytes) EXCEPT for the `capturedAt` timestamp. If you need byte-identical output across runs, set a fixed `capturedAt` in your wrapper.\n- For agent hosts that don't speak MCP yet, fall back to invoking cub-scout verbs directly via shell tools with `--format json --presentation ai`. The structured output is the same.\n- This skill's read-only invariant doesn't extend to `cub`. If the agent has BOTH cub-scout AND cub MCP tools registered, the cub side IS mutation-capable. Use a separate allowed-tools policy for that surface.\n",{"name":5,"phase":59,"description":7,"allowed-tools":60},"cross-cutting","Bash(.\u002Fcub-scout mcp *) Bash(cub-scout mcp *) Bash(cub scout mcp *) Bash(.\u002Fcub-scout context-pack *) Bash(cub-scout context-pack *) Bash(cub scout context-pack *) Bash(.\u002Fcub-scout doctor *) Bash(cub-scout doctor *) Bash(cub scout doctor *) Bash(.\u002Fcub-scout explain *) Bash(cub-scout explain *) Bash(cub scout explain *) Bash(.\u002Fcub-scout trace *) Bash(cub-scout trace *) Bash(cub scout trace *) Bash(.\u002Fcub-scout status) Bash(cub-scout status) Bash(cub scout status) Bash(.\u002Fcub-scout version) Bash(cub-scout version) Bash(cub scout version)","main","261862e7ec5e5c93ce377ccfd6b583f5ac03c95c","skills\u002Fai-agent-readonly-context",1,"https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout","https:\u002F\u002Fconfighub.com","https:\u002F\u002Fgithub.com\u002Fconfighub","http:\u002F\u002Fwww.confighub.com","Public repo for ConfigHub","2026-11-14 03:24:15",{"source":8,"skillName":5,"commands":72,"prompt":82,"zipAvailable":83},[73,76,79],{"tool":74,"command":75},"npx","npx skills add confighub\u002Fcub-scout --skill ai-agent-readonly-context",{"tool":77,"command":78},"bunx","bunx skills add confighub\u002Fcub-scout --skill ai-agent-readonly-context",{"tool":80,"command":81},"pnpm","pnpm dlx skills add confighub\u002Fcub-scout --skill ai-agent-readonly-context","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Fai-agent-readonly-context\u002FSKILL.md",true,[],[86,118,145,163,180,202],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":95,"publishedAt":54},"01M6CBPQHTK7YGVZD3MMH1328H","triage-unhealthy-workload","Use when the user is responding to a broken Kubernetes workload UNDER TIME PRESSURE — pager-going-off, CI-red, \"prod is down\" framing. Natural phrasing: \"deploy\u002Fapi is CrashLoopBackOff, what now?\", \"the rollout is stuck, help\", \"this pod won't start\", \"pager fired on payments\", \"everything is red in argocd\", \"what should I check first?\", \"give me a triage plan for this workload\". Composes doctor → explain → trace into a tight ~30-second loop the operator can run in a pager-acknowledged context. Do NOT load for: a planned investigation without urgency (use scout-diagnose directly), a drift question (use investigate-drift), or anything mutating (cub-scout never mutates — route to kubectl with the user driving).","https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Ftriage-unhealthy-workload\u002FSKILL.md",[92],{"categoryNo":93,"categoryName":94,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",[96,97,98,99,100,48,101,102,103,104,44,105,106,107,108,109,40,110,38,111,112,113,114,115,116,117,32],"triage","workload","triage unhealthy workload","kubernetes","diagnose","logs","ci","payments","api","loop","explain","check","broken","question","rollout","cub scout","route","drift","map","time","get","now",{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":122,"categories":123,"keywords":125,"publishedAt":54},"01M6CBPKYVREY83CQYNFW6BVD0","scout-verify","Use when the user wants a TYPED, FINGERPRINTED, IMMUTABLE evidence artifact about a Kubernetes resource — the Verify verb group of cub-scout (the receipt capability shipped in #446). Natural phrasing: \"produce a receipt that this is in compliance\", \"give me an attestation that the cluster matches Git\", \"I need a verifiable record for the audit trail\", \"build a receipt verifying no manual edits since deploy\", \"verify deploy\u002Fapi against source-truth and save the artifact\", \"validate this receipt has not been tampered with\", \"show me what receipts we have\", \"is this receipt tampered with?\", \"attach evidence to my CI gate\". Load whenever intent is receipt \u002F attestation \u002F evidence-artifact \u002F tamper-evident-record \u002F verified-record \u002F audit-trail \u002F postmortem-evidence \u002F acceptance-judge-input. Do NOT load for: a live comparison without a persisted artifact (use scout-compare), interpreting a single field's provenance (use scout-attribute), or actually applying a fix (cub-scout never mutates — route to cub \u002F argocd \u002F kubectl with the user driving).","https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Fscout-verify\u002FSKILL.md",[124],{"categoryNo":93,"categoryName":94,"taxonomyType":21,"taxonomyTypeDesc":22},[126,127,128,99,129,130,102,131,132,104,133,44,134,135,136,137,138,40,38,139,111,140,112,141,116,142,143,144,32],"verify","scout verify","scout","acceptance","produce","attestation","provenance","show me","postmortem","changeset","argocd","view","fix","evidence","show","me","app","unit","managed",{"skillNo":146,"name":147,"nameZh":6,"description":148,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":149,"categories":150,"keywords":151,"publishedAt":54},"01M6CBPF8WZBM7F9X096WT8PJD","scout-observe","Use when the user wants to SEE what is running in a Kubernetes cluster, who owns it, and how it is structured — the read-only Observe verb group of cub-scout. Natural phrasing: \"what is running in my cluster?\", \"give me a map of resources\", \"who owns this Deployment?\", \"trace this back to its source\", \"show me the ownership tree\", \"scan this cluster for risk\", \"dump the cluster as JSON\", \"stream cluster events\", \"run cub-scout as a bot\", \"what is the connection status?\", \"is this cluster healthy?\". Load when intent is observe \u002F inventory \u002F map \u002F show \u002F list \u002F trace \u002F scan \u002F dump \u002F stream \u002F bot \u002F health-check over a Kubernetes cluster. Do NOT load for: explaining WHY something is broken (use scout-diagnose), comparing cluster state to intended state (use scout-compare), provenance of individual field values (use scout-attribute), or any action that mutates the cluster (cub-scout never mutates — route to cub or kubectl with the user driving).","https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Fscout-observe\u002FSKILL.md",[],[152,153,128,154,99,100,155,48,101,156,132,157,133,44,108,40,39,38,37,158,111,140,159,160,114,116,161,162,32],"observe","scout observe","bot","deployment","risk","inventory","hooks","back","health-check","resources","meaning",{"skillNo":164,"name":165,"nameZh":6,"description":166,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":167,"categories":168,"keywords":170,"publishedAt":54},"01M6CBPBM5J9PX4H8CE628AY5X","scout-mcp","Use when the user wants to expose cub-scout to an AI agent over MCP, wants a deterministic AI-ready snapshot of cluster context, or wants cub-scout running as a read-only event bot — the Integrate verb group. Natural phrasing: \"start the MCP server\", \"expose cub-scout to Claude \u002F Codex \u002F my agent\", \"give me an AI-ready context pack of this cluster\", \"set up the MCP gateway\", \"what MCP tools does cub-scout expose?\", \"run cub-scout as a bot\", \"produce JSON context for an LLM to reason about this cluster\". Load whenever intent is mcp \u002F mcp-gateway \u002F mcp-serve \u002F context-pack \u002F bot \u002F agent-context \u002F ai-snapshot \u002F llm-context \u002F model-context-protocol. Do NOT load for: actually running a non-integrate verb (those are scout-observe \u002F scout-diagnose \u002F scout-compare \u002F scout-attribute \u002F scout-ingest \u002F scout-govern \u002F scout-verify), or `cub` MCP integration (that's a separate tool surface).","https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Fscout-mcp\u002FSKILL.md",[169],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[42,171,128,154,51,28,172,173,174,175,46,45,44,176,135,177,178,37,36,35,152,116,143,179,32],"scout mcp","auth","config","run","release","model","read","snapshot","agent-context",{"skillNo":181,"name":182,"nameZh":6,"description":183,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":184,"categories":185,"keywords":186,"publishedAt":54},"01M6CBP7D72G704FWGRXNB6F9T","scout-ingest","Use when the user wants to ADOPT existing Kubernetes \u002F GitOps workload structure into ConfigHub after observing the live cluster — the adoption\u002Fimport verb group of cub-scout. Natural phrasing: \"discover workloads in this cluster and propose ConfigHub units\", \"show me the import proposal before I apply\", \"import this Argo Application set\", \"bring my Flux Kustomizations into ConfigHub\", \"preview what would land in ConfigHub if I imported this repo\", \"parse my git repo as a ConfigHub import bundle\", \"import a cluster aggregator\", \"what would --git-path produce for this repo?\". Load whenever intent is adopt \u002F import \u002F ingest \u002F preview \u002F propose \u002F parse-repo \u002F discovery \u002F aggregator \u002F bring-into-confighub \u002F what-would-confighub-see. Do NOT load for: questions about who changed a resource, whether it was edited by hand or drifted (use scout-attribute or investigate-drift); reading an exported `kubectl get -o yaml` dump to answer a question about the cluster (that is not an import); basic live-cluster inventory (use scout-observe), troubleshooting (use scout-diagnose), comparing live state to ConfigHub (use scout-compare), or the actual write to ConfigHub via `cub variant upload` (that is `cub`, not cub-scout — route to cub skills). Important: `cub-scout import apply` IS the mutating write into ConfigHub — this skill teaches the read-only preview path and explicitly refuses to invoke `import apply` itself.","https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Fscout-ingest\u002FSKILL.md",[],[187,188,128,99,100,175,189,130,190,45,157,191,133,44,135,192,109,177,193,137,40,37,152,111,140,194,195,196,197,142,143,198,199,200,201],"ingest","scout ingest","state","adoption","discovery","repo","write","structure","aggregator","adopt","argo","reading","exported","invoke","parse",{"skillNo":203,"name":204,"nameZh":6,"description":205,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":206,"categories":207,"keywords":208,"publishedAt":54},"01M6CBP32CYJT8DJSGNCRWXQTM","scout-govern","Use when the user wants to consume CONNECTED ConfigHub governance signals from cub-scout — the Govern verb group. Natural phrasing: \"show me the ChangeSet history for this unit\", \"what is the blast radius if I change this unit?\", \"which clusters in my fleet are outliers?\", \"show me yesterday's connected summary\", \"render this view across the fleet\", \"audit who changed this\", \"where did the last apply come from?\", \"list ConfigHub bundles I have\", \"show me the catalog of past snapshots\". Load whenever intent is history \u002F impact \u002F blast-radius \u002F fleet-outliers \u002F summary \u002F view \u002F audit \u002F bundle \u002F catalog \u002F connected-context. Do NOT load for: live cluster comparison (use scout-compare), receipts (use scout-verify), inventory of running pods (use scout-observe), or any mutation via cub. Most of this skill requires `cub auth login` — say so upfront.","https:\u002F\u002Fgithub.com\u002Fconfighub\u002Fcub-scout\u002Fblob\u002Fmain\u002Fskills\u002Fscout-govern\u002FSKILL.md",[],[209,128,210,172,211,212,213,157,126,133,44,214,135,137,215,40,216,217,34,152,111,140,218,116,219,220,143,221,222,223,224,32],"scout govern","change","governance","blast radius","audit","history","catalog","diff","say","project","mutation","impact","render","blast-radius","which","inspect"]