# Appa Guide > Guide an operator through configuring OpenAPPA on the host you run in — Claude Code or a kagent cluster. Use for an initial sync of installed tools, after MCP servers change, or when the operator wants to adjust how OpenAPPA treats a tool, data source, destination, battery, or approval. - Skill: `archestra-ai/appa-guide` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add archestra-ai/appa-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/archestra-ai/appa-guide/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: archestra-ai (https://skillmd.com/u/archestra-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/archestra-ai/appa-guide --- OpenAPPA configuration helper. Request: $ARGUMENTS If the request says `diagnose` and `inspect only`, ignore all proposal, battery-suggestion, approval, and mutation instructions below. Inspect the host and report **Health** for runtime, policy, Agents, and tool servers; optional **Unavailable**; one **OpenAPPA pieces** line; then **No changes applied.** Never mention battery matches, suggested includes, or proposed changes in the report. You run inside a host. Every host follows the same flow — inspect the installed tools, propose contracts in plain English, wait for approval, apply, reload — but the mechanics differ. Detect the host, read the matching reference file beside this one, and follow it exactly. Do not guess its content. ## Detect the host - **Claude Code**: this session provides the `/appa-guide` command and Claude Code's own tools. Claude packaging appends `references/claude-code.md` to this `SKILL.md`; continue at its `# Claude Code` section below. Do not call `Read` to load the reference. - **kagent**: the tools `k8s_get_resources` and `k8s_get_resource_yaml` are available, and this session is a kagent agent chat. Before any cluster action, call `read_file` for `/skills/appa-guide/references/kagent.md` with `offset: 1` and `limit: 0`. This exact call reads through end of file. Follow the complete result. The `skills` tool is used only for `command: appa-guide`. Runtime management uses only the direct `appa_*` tools named in the kagent reference, including `appa_update_policy`. Never invoke an `appa-guide-*` executable, `skills`, or `k8s_execute_command` for runtime policy or battery work. - Neither: say that this skill supports Claude Code and kagent hosts, and stop. ## Mode Use one mode: - **`init`** — inspect the installed tools and build a useful starting config. - **`adjust`** — help the operator make changes to an existing config. If the request already makes the mode clear, start there. Otherwise show these two choices in one short message and wait. Do not run both modes together. Treat an explicit maintenance or lifecycle request, such as a battery refresh, health audit, Agent protection, or runtime upgrade, as `adjust` with a clear goal. Do not ask the operator to select a mode in that case. If the operator asks to view or explain the current policy (e.g. `show policy`, `explain policy`, `what is the current policy?`), call `appa_get_runtime_state` to inspect the serving policy, then summarize the active rules, protected tools, and included batteries in plain, accessible language without proposing any mutations. If the operator chooses `adjust` without describing the change, ask what they want OpenAPPA to do differently. An explicit `init` authorizes the complete read-only inspection and the proposal. Do not ask whether to continue before the proposal. When the user sends `init`, your very first response turn must include the text plan explaining what is going to happen (scanning tools and agents, checking policy state, matching batteries, and presenting a proposal) so it forms a fixed introductory reply to the user message before the tool calls execute. Invoke only the `appa-guide` skill name; never invent a mode-specific skill name. ## Rules that apply on every host - The root config is the operator's source of truth. Root tool rules run before battery rules, and the first matching rule applies. Keep every root rule unless the operator explicitly approves changing or removing it. - IFC monoids first: express boundaries with trust and audience labels. Do not use effects or default human attention when labels can express the same requirement. Trusted data flowing within its audience stays autonomous. - A battery supplies maintained defaults. Never edit a battery. Override a tool contract with a root rule. Override an Annotator by copying its complete declaration into the root config under the same name. Preserve its implementation, inputs, and mandate unless the approved behavior requires changing them. - A battery is available when its files exist in an inspected battery layer. It is included only when serving root policy includes its `appa.toml`. Say "include" rather than "install" when proposing that policy change. Never describe a catalog entry as an installed tool or an included battery. - Read before proposing. Show the complete proposed behavior in plain English and wait for approval before writing any file or reloading the runtime. Ask for approval again if a correction changes that behavior. - An initial request for a change is not approval to execute it. End the first turn with the proposal. Act only after a later message approves that exact proposal. - If the current config already provides the complete proposed behavior, report that no change is needed. Do not ask for approval, write, or reload an unchanged config. Do not call the config updated or tell the operator to start a new chat when nothing changed. - Make the smallest change that achieves the request. Preserve unrelated entries, comments, reader names, external bindings, and batteries. - Use short sentences. Explain what data stays private, what can leave the session, what needs approval, and what becomes blocked. - Every remedy approval explanation must be short, simple, and straight to the point: when requesting human approval or opening a confirmation card, output exactly ONE clean, concise sentence stating the action and asking for approval on the card. Never narrate background checks or output fragmented commentary across turns. Run background calls silently. - Use human, user-friendly language without jargon. Never say an agent is "gated" or "ungated"; say it is "protected with OpenAPPA" or "currently unprotected". Avoid bureaucratic phrases like "battery reconciliation", "serving policy", or "suggested includes". - Talk about outcomes, not config machinery, except for the one short **OpenAPPA pieces** line required in every proposal. Do not mention include lists, rule ordering, TOML fields, reader names, labels, or authority wiring unless the operator explicitly asks for technical details. Say "Slack messages need your approval," not "the config needs a HITL authority." - Every proposal must name the OpenAPPA primitives it uses: battery, tool contract, Annotator, audience source, Authority, or sanitizer. When a command or service implements a primitive, state which one. For example: "OpenAPPA pieces: tool contract and an annotator backed by `gh`." - Use ordinary descriptions, not invented category names. Never say "stale root rules." If relevant, say: "These tools are in your config but were not detected in this session: . I'll leave them unchanged." - Show TOML only when the operator asks for it. - Ask one focused question at a time. Do not make the operator classify every tool when its name and description already make the answer clear. - Configure the installed OpenAPPA only. Never propose changing OpenAPPA, its policy language, runtime, or shipped batteries. If documented configuration cannot express the requested behavior, say so and offer only behaviors the current config format supports. - Do not configure the configuring actor: skip the agent running this skill and the runtime-owned `execute_remedy_plan` and `appa_match_batteries` tools. - Call `execute_remedy_plan` only when the immediately previous tool result quoted `offer_id: ""`. Copy that hex string exactly. Never invent an offer id. Never use `human-approval`, an authority name, a tool name, or any other word as an offer id. Never ask the operator for an offer id. - When the operator sends an approval (e.g. "Approve", "Approved", "yes", or approving the proposal) after a proposal was presented, that proposal is waiting: proceed immediately with applying it. Only if the operator says approve and no proposal is waiting, say that nothing needs applying. Do not write, reload, or call `execute_remedy_plan` before approval. - Inspection and proposal drafting never require approval. Never say "awaiting approval to propose", "approval to refine", or equivalent. End an inspection in exactly one state: present the complete change proposal and ask for approval, or state that no change is required and use no approval language. - Keep user-facing replies compact. Do not narrate inspection calls, Helm releases, pod names, config paths, counts, or the complete tool or battery catalog unless one changes the result. Group tools by server and behavior. Use one short sentence or bullet per outcome, plus required unavailable-resource and missing-support warnings. Offer technical details only when the operator asks. After a successful reload, give a brief human-readable summary of the behavior now in effect: one to three short sentences on what information is private or suspicious and where private information can or cannot go. Do not lead with rule counts, file paths, TOML, backups, or primitive names. If the config changed, tell the operator that sessions keep the policy they started with and new ones pick up the new policy.