> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the skill

> Install the Alakazam skill so your coding agent knows when and how to use the /v1 API.

The Alakazam skill teaches your coding agent how to use the programmable worlds API without being told each time. The skill file is hosted at [`docs.alakazam.gg/skill.md`](https://docs.alakazam.gg/skill.md).

Once installed, your agent can:

* Generate playable worlds from a premise or an image
* Create talk-to characters (stances, memory, voice)
* Embed worlds correctly (the two-token rule)
* Program a world's state-machine graph — deterministically or in natural language
* Wire the `/v1` endpoints and the `@alakazamworld/embed` SDK into your app

## Prerequisites

* **An Alakazam API key.** Create an app at [play.alakazam.gg/?view=developer](https://play.alakazam.gg/?view=developer), mint a secret key (start with `sk_test_…` — a free, mocked [sandbox](/testing)), and export it in the shell your agent inherits:

  ```bash theme={null}
  # Add to your shell profile or .envrc — never commit it.
  export ALAKAZAM_SECRET_KEY="sk_test_..."
  ```

* **A supported agent** — Claude Code, Codex, Cursor, Windsurf, OpenCode, Gemini CLI, GitHub Copilot, and [50+ others](https://github.com/vercel-labs/skills#supported-agents) read skill files.

* **Node.js** to run the `npx skills` installer (or install manually with `curl`).

## Installation

### Method 1 — Skills CLI (one command, every agent)

The skills CLI detects your agent and drops the skill where that agent reads it:

```bash theme={null}
npx skills add -g https://docs.alakazam.gg/skill.md
```

Drop the `-g` to install into the current project instead of globally.

### Method 2 — Manual install with `curl`

Pick your client and run the matching command. Use the project path for an in-repo skill, or the global path for a cross-project one.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    # Project
    mkdir -p .claude/skills/alakazam
    curl -fsSL https://docs.alakazam.gg/skill.md -o .claude/skills/alakazam/SKILL.md

    # Global (across all projects)
    mkdir -p ~/.claude/skills/alakazam
    curl -fsSL https://docs.alakazam.gg/skill.md -o ~/.claude/skills/alakazam/SKILL.md
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    # Project
    mkdir -p .agents/skills/alakazam
    curl -fsSL https://docs.alakazam.gg/skill.md -o .agents/skills/alakazam/SKILL.md

    # Global
    mkdir -p ~/.codex/skills/alakazam
    curl -fsSL https://docs.alakazam.gg/skill.md -o ~/.codex/skills/alakazam/SKILL.md
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    # Project
    mkdir -p .agents/skills/alakazam
    curl -fsSL https://docs.alakazam.gg/skill.md -o .agents/skills/alakazam/SKILL.md

    # Global
    mkdir -p ~/.cursor/skills/alakazam
    curl -fsSL https://docs.alakazam.gg/skill.md -o ~/.cursor/skills/alakazam/SKILL.md
    ```
  </Tab>

  <Tab title="Any agent (.agents)">
    Codex, Cursor, OpenCode, Gemini CLI, GitHub Copilot, Cline, and others share `.agents/skills/`:

    ```bash theme={null}
    mkdir -p .agents/skills/alakazam
    curl -fsSL https://docs.alakazam.gg/skill.md -o .agents/skills/alakazam/SKILL.md
    ```
  </Tab>
</Tabs>

## Verify it loaded

Open a fresh agent session and ask:

> "Using Alakazam, how do I embed a world in a browser without exposing my secret key?"

A correctly loaded skill answers with the **two-token rule** — your server mints a short-lived session token (`POST /v1/sessions/token` with the secret key), and the browser uses *that* token with `@alakazamworld/embed`, never the key itself. If the agent suggests putting the API key in the browser, the skill didn't load — confirm the file exists at the path your agent reads.

## Next steps

<CardGroup cols={2}>
  <Card title="Agent quickstart" icon="robot" href="/agent-quickstart">
    Pair the skill with a one-paste onboarding prompt.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first world and embed it.
  </Card>
</CardGroup>