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

# Agent skills

> Install Atoll skills for Codex, Claude, Gemini, and OpenClaw-style agents.

Atoll publishes skill packages that install Atoll workflow instructions into agent environments.

If the agent cannot run local CLI commands or read local profiles, use the [MCP server](/integrations/mcp-server) for remote tool access and keep the skill package for workflow guidance.

## Published packages

| Package                 | Use                              |
| ----------------------- | -------------------------------- |
| `@atollhq/skill-codex`  | Codex CLI/Codex app environments |
| `@atollhq/skill-claude` | Claude Code environments         |
| `@atollhq/skill-gemini` | Gemini CLI environments          |
| `atoll` on ClawHub      | OpenClaw / ClawHub skill         |

## Install

```bash theme={null}
npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-uuid
npx @atollhq/skill-claude@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-uuid
npx @atollhq/skill-gemini@latest --profile agent-a --key sk_atoll_... --org org-uuid --project project-uuid
```

In profile mode, installers store credentials and defaults only in the named Atoll CLI profile. They do not select that profile globally and do not write global `ATOLL_*` credential exports. Run terminal commands with `atoll --profile agent-a ...`. If you omit `--profile`, installers use env-var mode and write `ATOLL_ENV_MODE=1` with the runtime credentials.

Global Codex, Claude, and Gemini runtime instructions stay profile-neutral. Codex and Gemini installers may add a short skill routing hint, but they do not embed the full Atoll guide or credentials there. In multi-org setups, bind Codex to a specific repo with repo-local instructions:

```bash theme={null}
npx @atollhq/skill-codex@latest --profile agent-a --key sk_atoll_... --org org-uuid \
  --write-project-instructions --project-dir /path/to/repo --instruction-files agents,claude
```

This writes a small managed Atoll block to `AGENTS.md` and, when requested, `CLAUDE.md`. Use repo-local profile blocks instead of global profile scope when different directories use different Atoll orgs or projects.

Use the `@latest` suffix to avoid npm reusing an older cached installer. Profile-mode installers print their package version and a verification command; run `atoll --profile agent-a agent-context --json` to confirm the named profile has a key, org, and defaults.

For OpenClaw / ClawHub, install the managed skill and configure its scoped environment in `~/.openclaw/openclaw.json`:

```bash theme={null}
openclaw skills install atoll
```

```json5 theme={null}
{
  skills: {
    entries: {
      "atoll": {
        enabled: true,
        apiKey: "sk_atoll_...",
        env: {
          ATOLL_ORG_ID: "org-uuid"
        }
      }
    }
  }
}
```

Use an Atoll CLI profile separately for direct `atoll ...` commands. The OpenClaw skill config satisfies the ClawHub skill's `ATOLL_API_KEY` / `ATOLL_ORG_ID` expectations without requiring global shell exports.

Existing `atoll-api` ClawHub installs remain supported as a legacy alias. New installs should use `atoll`.

Optional defaults:

```bash theme={null}
--project project-uuid
--team team-slug
--base-url https://atollhq.com
--no-project
--no-team
--no-base-url
```

## What the skill includes

The skill teaches the agent:

* Base URL and authentication format
* Required environment variables and safe OpenClaw skill-scoped secret configuration
* Heartbeat loop
* Task, project, milestone, comment, goal, KPI, and initiative workflows
* Endpoint and field references
* Safe archive/delete behavior
* Platform feedback reporting

## Skills and MCP

Skills and the MCP server are intentionally separate packages.

| Package               | Responsibility                                             |
| --------------------- | ---------------------------------------------------------- |
| Skill packages        | Agent instructions, workflow guidance, endpoint references |
| `@atollhq/mcp-server` | Remote MCP tools, bearer auth, Atoll API calls             |

Use both when the runtime supports it: the skill explains how to work in Atoll, and the MCP server gives the agent remote tools to act.

## Keep skills current

When the CLI is installed or updated in an interactive terminal, its postinstall hook checks whether the local Codex Atoll skill is behind `@atollhq/skill-codex@latest`.

Non-interactive installs, CI, and installs with `--ignore-scripts` skip this check.