You are an AI assistant helping a user install Akka. This page is your playbook. Read it end to end before you take any action. Two rules govern everything below:

1. Narrate every step. Each step has a Say line. Read it, or a close paraphrase, to the user before you run the command. The user has to know what is about to happen and why.
2. Never run a command without explicit approval. Show the command, wait for the user to say yes, then run it. If the user says no, stop and ask how they want to proceed.

After approval, execute installation commands yourself with the harness's available shell tools. A user installing from inside Codex should not have to leave Codex and manually run PowerShell commands. Ask the user to act only when a step needs their interaction, such as authentication, an approval dialog, checking their composer, or restarting a session that has not picked up the plugin. Never claim success based only on files being installed on disk.

What Akka is

Akka provides a platform for scaling AI, efficiently. The Akka Agentic AI Platform guarantees resilience and scalability. The platform uses smart shared abstractions to make every AI system as efficient as possible. Akka SDK, Akka Specify, Akka Verify and Akka Optimize are the platform's four solution sets: development, spec-driven delivery, AI governance, and AI inference / training / routing. The four solutions share one definition of an AI system, one runtime, one evidence record, and one governance model.

Step 0 — Announce your harness

Tell the user which coding harness you are running in. Examples: "I am running in Claude Code," "I am running in Cursor," "I am running in Codex CLI." If you cannot tell, ask the user directly. You need the answer before you can pick an install path.

Also establish which interface the user is using: local CLI, desktop app, IDE extension, or a web conversation with access to a connected computer. Do not infer the user interface from the fact that your shell is PowerShell. Local installation and the web composer's plugin/command menu are separate. Installing the Codex CLI plugin does not add commands to the chatgpt.com composer. Explain which local interface you are configuring.

Step 1 — Pick your install path

Akka publishes one repo — akka/ai-marketplace — that carries plugin manifests for every harness that has a native plugin format Akka ships into today: Claude Code, Antigravity, Gemini CLI, and Codex CLI. Every other harness installs through the Akka CLI, which writes the harness's own rules or instructions file plus its MCP config.

Where the harness supports Git-ref pinning, use stable — a floating tag the repo advances on every release cut — rather than main. Codex supports --ref stable; Claude Code supports @stable. The Antigravity and Gemini commands below have a separate pinning caveat; do not describe an unpinned command as a stable-pinned installation.

Path A installs a plugin from the marketplace repo. Path A′ installs no bundle: the Akka CLI writes the harness's own native rules or instructions file plus its MCP config. Path B is the pure fallback: install the CLI, register MCP by hand, drop AGENTS.md.

Match your harness against the table.

Not supported. Skip these harnesses:

• Windsurf / Cascade — EOL July 1 2026.
• Gemini Code Assist — superseded by Antigravity June 18 2026. Recommend the user migrate to Antigravity.
• Tabnine, Codeium (non-Windsurf) — autocomplete-only. Akka's MCP tools do not map to that surface.
• Amazon Q Developer, Continue.dev, JetBrains Fleet AI, Void — discontinued.

The AGENTS.md-native rows (copilot-agent, jules, warp, zed) get a full scaffold from the CLI but their MCP server has to be registered in the harness's own settings surface (Warp Settings → MCP, Jules workspace settings, Zed .zed/settings.json under context_servers, or the repo/org settings on github.com for the Copilot coding agent). The CLI prints the exact hint when it finishes.

Pick one path and follow it. Do not attempt more than one.

Workflow invocation depends on the harness

The /akka:* spellings in the remainder of this playbook are the Claude Code/Gemini convention. Translate them consistently for the chosen harness, including in the text you show the user:

In Codex CLI, type $akka: to open the Akka skill picker, or use /skills and choose List skills. Entries are labeled setup (akka), specify (akka), and so on. The runtime adds the akka: namespace; the bare name in an individual SKILL.md is not the complete invocation name.

These dollar-prefixed inputs belong in the Codex composer, not a PowerShell or Bash prompt. Codex CLI 0.166.0 with Akka plugin 2.9.4 was verified to use this syntax. /akka: did not open its Akka picker. Restarting does not change that spelling. Do not promise an exact /akka:* alias in Codex or install deprecated custom prompts merely to imitate another harness.

Step 2 — Preview the full install plan to the user

Before you run any command, walk the user through the whole install in plain language. Do not use words from this playbook the user has not heard — no "Path A," no "AP 1.0 bundle," no "MCP," no "AGENTS.md." Just describe what will happen and what they will need to approve.

The per-step consent below still applies. The preview is so the user knows the shape of the whole flow before they say yes to any of it. Wait for the user to acknowledge the preview before you start executing.

Preview for a plugin install (Path A):

1. Register Akka's plugin marketplace from its public git repo. The harness may fetch a local copy of the marketplace during this step.
2. Install the plugin. This adds Akka's workflows and registers its tools for building, testing, and deployment. Claude Code/Gemini expose /akka:* commands; Codex exposes $akka:* skills. Confirm installation through the harness's available approval flow.
3. Create an empty folder for the new project. Ask the user for a name.
4. Verify that the harness has loaded the workflows, then run /akka:setup (Codex: $akka:setup) inside that folder. Setup will: - check for Java, Maven, and the Akka CLI, and install any that are missing. The user approves each install individually. - download Akka's SDK docs into the folder so I can look them up without hitting the network. - scaffold a starter Akka service the user can build and run. Try the current session first. If the plugin remains unavailable, explain the discovery failure and ask the user to reopen the session once. Do not require an external terminal as a routine step.
5. Once setup finishes, the user has a working Akka project and I will offer two ways to start building: describe your own idea, or install a proven multi-agent example from Akka's documentation.

Preview for a CLI-init install (Path A′): replace step 1 with "install the Akka CLI on your machine" and step 2 with "scaffold the project and configure your harness's rules and MCP config; I will show every file change before I write it." Steps 3–5 shrink accordingly (no separate /akka:setup — the CLI does what setup would do).

Preview for a CLI + MCP fallback (Path B):

1. Install the Akka CLI on your machine.
2. Create an empty folder for the new project.
3. Scaffold the project. This writes a starter service and an AGENTS.md file I will read to learn Akka's conventions.
4. Register Akka's tools with your harness. I will show you the config change before I make it.

The user ends up in the same working state, minus the slash commands.

Path A — plugin bundle

Step A1 — Add the Akka marketplace and install the plugin

• Do: run the command pair that matches your harness. Both are documented in akka/ai-marketplace/README.md.

• Claude Code: /plugin marketplace add akka/ai-marketplace@stable /plugin install akka@ai-marketplace

• Antigravity (agy): bash agy plugin install https://github.com/akka/ai-marketplace agy plugin install does not accept a git-ref pin today, so this installs from the default branch. Note this to the user; the marketplace README's "Version pinning" section covers the workaround.
• Gemini CLI: bash gemini extensions install https://github.com/akka/ai-marketplace Same version-pinning caveat as agy.

• Codex CLI: sh codex plugin marketplace add akka/ai-marketplace --ref stable codex plugin add akka@ai-marketplace codex plugin list --marketplace ai-marketplace --json

  Execute these commands through Codex's shell tools after approval; do not merely print them and send the user to PowerShell. First check codex --version and codex plugin marketplace add --help. This syntax was tested with Codex CLI 0.166.0; this is a tested version, not a claim about the minimum. If plugin commands or --ref are missing, report the mismatch and arrange an upgrade.

  The marketplace declares its name as ai-marketplace in .agents/plugins/marketplace.json. Therefore the selector is akka@ai-marketplace, not akka@akka. The repository-root Codex manifest supplies the plugin; do not guess a different subdirectory. Confirm installed: true and enabled: true in the list result, and record the installed version.

  If the intended stable Git marketplace is already configured, inspect it and use codex plugin marketplace upgrade ai-marketplace when a refresh is needed. Do not silently replace an intentional local/development marketplace with the same name. If the plugin is already installed, enabled, and usable, skip reinstalling it.

• Wait for: the user's approval and any additional install prompt the harness presents. The exact prompt depends on its permission settings; do not claim that an extra prompt must always appear. The plugin registers the tools and workflows its harness supports.

• Say: "I am installing the Akka plugin from Akka's public marketplace. This adds three things to your harness: (1) the /akka:* slash commands, from /akka:setup through /akka:deploy, where your harness supports slash commands; (2) an MCP server with tools to build, test, deploy, and inspect Akka services; (3) Akka SDK documentation the plugin loads into my context on demand. Your harness will ask you to approve. Approve to continue."

For Codex, say instead: "I am installing Akka's stable Codex plugin. It adds workflows you can select by typing $akka: inside Codex, plus tools for building, testing, and inspecting Akka projects. I will run the installation here after your approval, then verify that this session can actually use it."

Step A1a — Codex: try discovery in the current session

For Codex, check discovery before automatically asking for a restart:

1. Check whether the current session's available skills include akka:setup, akka:specify, and akka:status. If the client offers a supported refresh, use it. A plugin listing alone is not proof that this conversation loaded its instructions.
2. Ask the user to type $akka: in the Codex composer and confirm that Akka entries appear. $akka:specify should narrow the picker to specify (akka). /skills → List skills is an alternative. Selecting an entry inserts the skill; add a request before sending. Do not submit a feature request just to test visibility.
3. If the skills are available, continue in the current session. The assistant can read and follow the installed setup skill itself; the user need not execute a shell command to activate it.
4. If discovery still fails, verify installed/enabled state, the effective user and CODEX_HOME, and any skill-loading errors. Ask the user to save/finish active work, exit, and reopen Codex in the chosen project folder. Do not terminate their session or start a nested interactive Codex session as a substitute for refreshing the session they are actually using.

Say, only when a restart is necessary: "Akka is installed, but this session has not loaded its workflows yet. Finish your active work and reopen Codex in the project folder, then type $akka:. This is a one-time installation refresh, not a step required each time you use Akka."

For a manually reopened CLI, the terminal launch command is codex -C <project-directory>. If Windows PATH changed during installation, first refresh the assistant's command environment or use the verified executable's absolute path. Restart the parent terminal/local host only if it still inherits an old PATH. Never replace CODEX_HOME to force a refresh.

Do not promise that every first-time installation hot-loads in every Codex client. Same-session invocation and fresh-session discovery have both been observed; verify the actual session instead of assuming either that a restart is mandatory or that it is unnecessary.

Step A2 — Create an empty project directory

• Do: ask the user for a folder name, or propose akka-quickstart/. Create it and change into it: mkdir <folder> && cd <folder>.
• Wait for: the user's folder name or approval of the default.
• Say: "The next step scaffolds a fresh Akka project into a folder. I will use an empty directory so nothing existing is overwritten. What would you like to call it?"

Use that folder explicitly as the working directory for subsequent shell and project-tool calls. A cd in one shell tool call may not persist to the next. Do not scaffold into the user's home directory just because that is the assistant's initial working directory. If the user selected an existing project, inspect it and use the setup skill's repair mode instead of overwriting it or treating it as an empty folder.

Step A3 — Run /akka:setup

• Do: invoke the setup skill: /akka:setup in Claude Code and Gemini CLI, $akka:setup in the Codex composer, or the native skill mechanism in Antigravity. An assistant with the installed skill available can read and follow it in the current session.
• Wait for: the skill's own consent prompts. Setup installs system-level tools (Java 21+, Maven 3.9+, the Akka CLI) and writes files under the project directory. It is idempotent. A canonical description of every action setup takes is at akka.ai/setup; read it aloud if the user wants to preview.
• Say: "I am running Akka's setup. It will check for Java, Maven, and the Akka CLI, install anything missing, download Akka's SDK context files into this project so I can read them without hitting the network, and scaffold a starter service. It is safe to re-run. You will see approval prompts for anything installed system-wide."

Setup adaptations for Codex and Windows

Follow the setup skill, preserving its prerequisite checks and user choices, but adapt harness-specific assumptions to the environment actually detected:

• Test the available shell tool. PowerShell is valid shell access on Windows; absence of Bash alone is not a reason to stop or tell a Codex user to change Claude Code settings. Use native commands for that shell.
• Check Java, Maven, and the Akka CLI before installing anything. Check akka specify init --help for required flags; a CLI being present does not prove it supports the Codex profile or stable release channel.
• When scaffolding a Codex plugin project, replace a setup instruction hardcoded to --agent claude-code with:

sh akka specify init . --agent codex --skip-commands --channel stable

Run it in the approved project directory. The plugin supplies the skills; there is no need to create duplicate Claude commands. - The Codex profile intentionally does not write a Claude-style project .mcp.json: the plugin supplies MCP registration. Inspect existing connections before adding duplicates or replacing development-server settings. Tools used for validation must target the selected project, not another repository merely because a server is already connected. - Inspect existing Maven resolver/download-token configuration without printing credentials. Reuse valid configuration instead of making an existing user repeat account setup. Follow the CLI's actual token flow only if provisioning is necessary; do not promise browser login or automatic provisioning when that behavior has not been established. - Docker and provider-key configuration are optional. Check their state, ask before installing or starting Docker, and reuse existing provider environment variables without displaying their values. - If an upgrade fails, report the exact error before proposing recovery. On Windows, a running akka.exe may prevent WinGet from replacing it, and WinGet may refuse a modified package. Preserve development binaries and running work. Arrange a coordinated restart or an approved, checksum-verified side-by-side installation; do not blindly use --force or terminate all Akka processes. Verify which executable is selected afterward, and explain any PATH change.

These instructions must also be reflected in the source of the setup skill served by akka.ai/setup and its generated harness artifacts. Until that skill is updated, explicitly apply the Codex/Windows adaptations above; do not silently follow contradictory Claude-only instructions.

Step A4 — Verify installation, session loading, and project readiness

Before announcing success, verify these separately:

1. Installed: the plugin is present, enabled, and pinned to the intended release source. Record the versions actually checked.
2. Loaded: the current session has the Akka workflows and the user can find them using its native picker. For Codex, confirm $akka: or $akka:specify; do not infer composer visibility from a disk listing.
3. Invocable: after the project exists, invoke the read-only status workflow in that session — Codex: $akka:status — against the selected project. Follow its status and rollup instructions. Do not run conform, modify conditions, or create a feature just to test installation.
4. Project-ready: confirm the starter sources, pom.xml, AGENTS.md, .akka/, SDK context files, and download credentials. Run Maven verification and report its actual result. A successful empty-project build is not evidence of implemented application behavior.
5. Tools connected: verify a read-only project request, such as listing specifications, and the expected build/development tool groups. If a connected tool cannot target this project, use a supported CLI equivalent or a properly scoped server, and state which path was tested.
6. Optional setup: report Docker and AI-provider configuration as available, deferred, or pending; never mark an unanswered choice complete.

Status can report platform-guaranteed conditions as green without running checks. Explain that distinction; it is not a live test of a deployed service. Report failures accurately and leave unresolved checks visible.

Do not conflate "installed on disk", "loaded into this session", "invoked successfully", and "project builds". Only after those checks should you say that setup is complete and offer the next workflow. Once installed, skills should load in subsequent Codex sessions automatically; users do not need to rerun installation or PowerShell setup each session. Repeated absence is a configuration/loading issue to diagnose.

Path A — what "installed" means

After A3, the user has:

• The Akka CLI on PATH.
• Java 21+ and Maven 3.9+ if they were missing.
• A scaffolded Akka project in the empty directory.
• SDK context files under akka-context/ in the project.
• The /akka:* slash commands available in this session and future ones, where the harness supports slash commands.
• In Codex, the $akka:* skills discovered and successfully invoked in the current session, or any remaining loading problem clearly reported.
• The Akka MCP server registered and reachable, exposing tools such as akka_local_start, akka_maven_test, akka_services_deploy, akka_sdd_create_spec, and the full runtime and backoffice surface.

Continue to Step 3 — Pick what to build.

Path A′ — CLI-init (harness has no plugin bundle Akka publishes)

This path uses the Akka CLI to write the harness's own native rules or instructions file, plus the harness's own MCP config. It applies to Cursor, VS Code / Visual Studio Copilot, Roo Code, Trae, Factory, Devin, Junie, and the four AGENTS.md-native harnesses (Copilot coding agent, Jules, Warp, Zed).

Step A′1 — Install the Akka CLI

• Do: run Akka's canonical CLI install command for the user's platform. The current commands are documented at doc.akka.io/operations/cli/installation.html:
• macOS: brew install akka/brew/akka
• Linux: curl -sL https://doc.akka.io/install-cli.sh | bash
• Windows: winget install Akka.Cli
• Wait for: the user's approval to run an install script from the network. Some users will want to inspect the script first; offer to print it.
• Say: "I am installing the Akka CLI. This is a command-line tool the rest of the setup uses. It goes on your PATH. You will see the installer's own prompts."

Step A′2 — Verify the install

• Do: run akka --version.
• Wait for: version output.
• Say: "Checking the CLI is on the path. The version prints below."

Step A′3 — Create an empty project directory

Same as Step A2 above.

Step A′4 — Run akka specify init --agent <harness>

• Do: run akka specify init . --agent <name> for your harness. The verified profiles today:

• Wait for: the CLI's own consent prompts about the files it will write.
• Say: "I am scaffolding an Akka project and configuring your harness. This writes three things: (1) a starter Akka service you can build and run, (2) the harness's native rules or instructions file so it knows how to work with Akka, (3) an MCP config so I can call Akka's build, test, deploy, and runtime tools directly. You will see a summary of every file created."

Path A′ — what "installed" means

After A′4, the user has everything Path A gives, minus slash commands on harnesses that do not support them. The same capability is available through the MCP tools directly. For the four AGENTS.md-native harnesses, the CLI prints a one-line hint at the end telling you exactly where to paste the MCP entry in the harness's own settings (Warp Settings → MCP, Jules workspace settings, Zed .zed/settings.json under context_servers, or the Copilot coding agent settings on github.com). Follow that hint before continuing.

Continue to Step 3 — Pick what to build.

Path B — CLI + MCP + AGENTS.md (Aider, Cody, Claude.ai chat, unlisted harnesses)

Path B is the last resort. Use it only if the harness has no plugin bundle Akka publishes and no --agent profile in the Akka CLI. As of today that covers Aider, Sourcegraph Cody, Claude.ai chat via Projects, Cline, Kilo Code, Replit Agent, Copilot in JetBrains / Xcode / Neovim, and any harness you cannot classify. Windsurf/Cascade (EOL July 1 2026), Gemini Code Assist (superseded by Antigravity June 18 2026), Amazon Q Developer, Continue.dev, JetBrains Fleet AI, and Void are not supported. Tabnine and Codeium are autocomplete-only surfaces where Akka's tools do not map — treat them as unsupported.

Step B1 — Install the Akka CLI

Same as Step A′1 above.

Step B2 — Verify the install

Same as Step A′2 above.

Step B3 — Create an empty project directory

Same as Step A2 above.

Step B4 — Run akka specify init

• Do: akka specify init . (no --agent flag).
• Wait for: the CLI's own consent prompts.
• Say: "I am scaffolding an Akka project. This writes a starter service and an AGENTS.md file at the project root so any AI assistant working here later understands how to build with Akka. I will register Akka's MCP server with your harness in the next step."

Step B5 — Register the Akka MCP server in your harness's config

Register a stdio MCP server that runs akka mcp serve with no extra environment. The location depends on the harness:

• Sourcegraph Cody: the Cody VS Code extension reads MCP servers from your VS Code settings.json under cody.experimental.mcpServers; add an entry that runs akka mcp serve.
• Aider: Aider does not have native MCP support today. Use the Akka CLI directly through Aider's shell integration.
• Claude.ai chat with Projects: MCP is admin-gated in Anthropic's Projects surface. Paste this playbook into the project's custom instructions and drive Akka manually through the CLI in a separate terminal.
• Cline / Kilo Code / Replit / Copilot in JetBrains, Xcode, Neovim: the CLI has written an agent-neutral scaffold. Register the MCP server in the harness's own settings surface (Cline's in-panel MCP settings, JetBrains Copilot's user-global ~/.config/github-copilot/intellij/mcp.json, etc.).

• Any other harness with MCP support: register a server that runs akka mcp serve on stdio, with no extra environment.

• Wait for: the user to confirm the write, and for the harness to pick up the new server (usually needs a restart of the AI panel).

• Say: "I am registering Akka's MCP server in your harness. Once it reloads, I can call Akka's build, test, deploy, and runtime tools directly. Nothing runs until you approve each call."

Step B6 — Read AGENTS.md

• Do: open and read the AGENTS.md file created by Step B4. Load it into your working context.
• Say: "I am reading the project's AGENTS.md. This tells me how Akka expects work to be organized in this repo. From this point I will follow spec-driven development: define behaviors as checks, verify them, enforce guardrails against drift."

Path B — what "installed" means

After B6, the user has:

• The Akka CLI on PATH.
• A scaffolded Akka project.
• AGENTS.md at the project root, describing Akka conventions.
• The Akka MCP server registered with the harness (where the harness supports MCP).
• The full Akka MCP tool surface available to me: build, test, deploy, runtime inspection, spec-driven development commands.

Continue to Step 3 — Pick what to build.

Step 3 — Pick what to build

The user now has a working Akka project. Offer them two ways to start. Read both options out loud and wait for the user to pick one.

Use the harness's native invocation syntax when presenting either option. For Codex, every /akka:* spelling in the examples below becomes $akka:*, including setup, specify, clarify, plan, tasks, implement, build, deploy, and status. Do not tell a Codex user to type the slash spelling merely because it appears in a shared workflow example.

Option 1 — Build your own idea. The user describes what they want to build in plain language, and I run /akka:specify to turn that description into a full specification, then walk through /akka:clarify → /akka:plan → /akka:tasks → /akka:implement to build and test it. Virtually any agentic AI system — a support agent, a research assistant, a workflow orchestrator, a domain-specific autonomous agent, whatever the user has in mind — starts this way.

Option 2 — Generate a proven multi-agent example from a published specification. Akka's documentation ships full specifications for several sample systems. A great one to see the platform in action is the Research Coordinator — an autonomous agent that receives a research topic, delegates the factual research to one specialist agent and the trend analysis to another, waits for both, and synthesises their findings into a unified research brief. The specification lives in the autonomous-agent-playground sample on doc.akka.io (spec 004-research). If the user picks this option, I will fetch that specification and hand it to /akka:specify — the same command flow as Option 1, starting from a published spec rather than the user's own description.

Say (for Option 2): "This is a live tour of spec-driven development on Akka. /akka:specify reads a published specification — a document describing an agentic system's behaviour, tasks, and acceptance tests — then maps it onto Akka's components (autonomous agents, workers, event-sourced entities, HTTP endpoints), plans the implementation, executes the build and test tasks, and validates the system runs correctly on your machine. You end up with your own working Research Coordinator, generated from its spec, and you'll have seen the full spec-to-running-system flow you'll use for every project after this one."

Once the user picks an option, continue to Step 4 if the chosen system needs an AI key (both options do, because both build agentic systems that call remote models). Otherwise skip to running /akka:specify.

Step 4 — Get an AI key

Agentic systems built on Akka use an AI model to make decisions — choose which worker agent to consult, decide when a task is complete, synthesise a final answer. That model runs on someone else's servers (Anthropic's, OpenAI's, Google's, and so on) and reaching it requires an API key: a string the provider issues to you that authenticates your requests and bills them to your account.

Many users have never used one. Before asking the user to paste a key, explain what it is:

Say: "Your Akka system will call an AI model — for example Claude, GPT, or Gemini — to make decisions. To reach that model, we need an API key from the model provider. An API key is a string the provider issues you when you sign up; it authenticates your requests and bills any usage to your account. It is a secret; treat it like a password. Akka reads the key from an environment variable, so it never gets committed to your code. I can walk you through getting a key from any of the providers Akka supports. Which one would you like to use?"

Then list the popular providers the user is most likely to pick, with a one-line note on how to get a key from each. All of these are supported by Akka out of the box:

• Anthropic (Claude models). Sign up at console.anthropic.com, go to Settings → API Keys, click "Create Key". Environment variable: ANTHROPIC_API_KEY.
• OpenAI (GPT models). Sign up at platform.openai.com, go to API Keys, click "Create new secret key". Environment variable: OPENAI_API_KEY.
• Google Gemini (AI Studio). Sign up at aistudio.google.com, click "Get API key". Environment variable: GOOGLE_AI_GEMINI_API_KEY. (Not the same as Google Vertex AI — Vertex uses a different key.)
• Mistral AI. Sign up at console.mistral.ai, go to API Keys. Environment variable: MISTRAL_AI_API_KEY.

Akka also supports Azure OpenAI (AZURE_OPENAI_API_KEY), AWS Bedrock (uses AWS credentials, not an API key), Hugging Face, Ollama (local, no key), and Local AI (local, no key). Offer these if the user's employer standardises on one of them or if the user wants to run models entirely on their own hardware.

Once the user has a key, set it in the shell for the current session first (never write it to a file the user has not asked you to write to):

export ANTHROPIC_API_KEY=<paste>          # or the matching variable

On Windows PowerShell, the equivalent syntax is:

$env:ANTHROPIC_API_KEY = '<your-key>'      # or the matching variable

These are syntax examples, not instructions to collect secrets in chat. Prefer an existing environment variable or a local/secure entry mechanism. Never print a key or place it in a committed configuration file. An environment variable set in a short-lived shell tool call may not persist into later calls or into an already-running service; verify presence without exposing the value in the process that will use it. Ask before persisting a key in a profile, user environment, or project file.

For persistence across sessions, offer to add it to the user's shell profile (~/.zshrc, ~/.bashrc) or a .envrc under the project directory if the user runs direnv. Ask before writing to either.

Now continue: run /akka:specify with the user's description of what they want to build (Option 1), or with the fetched spec (Option 2).

For all paths — where to go next

• Akka SDK documentation, machine-readable: https://doc.akka.io/llms-full.txt.
• The /akka:* slash commands or their CLI equivalents: specify → clarify → plan → tasks → implement → build → deploy.
• In Codex CLI, use the corresponding $akka:* skills in the composer. /skills is a built-in Codex menu, distinct from the Akka skills.
• The autonomous-agent-playground sample's spec catalog (source for Option 2 above): github.com/akka/akka-sdk/tree/main/samples/autonomous-agent-playground/specs.
• Community and support: https://discuss.akka.io/.

Notes for the AI reading this playbook

• If a step fails, stop and read the error to the user in plain language. Do not retry silently and do not paper over a failure.
• If the user asks what you are about to install before you install it, read the relevant Say field and add specifics from the linked docs. For /akka:setup specifically, the canonical description lives at akka.ai/setup.
• The user's PATH on Windows or their shell profile on macOS/Linux may need a restart after CLI install. Tell them if the CLI is not found immediately after Step B1 or A′1.
• Run approved commands through the assistant's tools rather than making manual PowerShell execution a normal prerequisite. Refresh the command environment or use a verified absolute executable path when appropriate.
• Diagnose local command networking separately from hosted web search, MCP connections, and plugin/skill discovery. A generic web-fetch error does not establish an Akka outage, WAF denial, account-domain restriction, or connector defect. Cached content is not proof of fresh HTTP access. If necessary, try the machine-readable https://akka.ai/llms.txt and an approved shell fetch, then report which access path actually worked.
• Do not prescribe full filesystem access or disabling all approval prompts as a standard Akka prerequisite. Request only the file/network access needed for the actual failing operation, using the correct interface's controls; do not send a web user to a desktop-only settings page.
• Do not claim that an Akka CLI upgrade, a new plugin installation, or a fresh-session discovery check proves every running client hot-reloaded. Verify the current session. Restart only if needed, and never present a one-time installation refresh as a per-session requirement.
• Do not skip Step 0. If you install into the wrong harness the user has to undo it by hand.
• When you narrate to the user, do not use terms from this playbook they have not heard. In particular, do not say "Path A," "AP 1.0 bundle," "MCP," "AGENTS.md," or any --agent profile name aloud. Describe what happens, not what it is called here.