> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://onepin.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://onepin.ai/docs/_mcp/server.

# Agent skill

> The onepin package ships an Agent Skill that teaches your AI coding tool to drive the Onepin CLI — installed with a single command, offline, no extra config.

The `onepin` package ships an [Agent Skill](https://agentskills.io) — a `SKILL.md` folder that teaches an AI coding tool how to drive the [Onepin CLI](/docs/reference/cli-reference). Install it once and your tool can list and run workflows, watch a run, browse voices and templates, and read usage, using the CLI and the API key you already have.

It's one of two ways to hand Onepin to an agent; the [MCP server](/docs/get-started/mcp-server) is the other, and they coexist. [Which one to pick](#skill-or-mcp) is at the bottom of this page.

## Install

```bash
pip install onepin        # if you haven't already
onepin login              # the skill drives the CLI, so the CLI needs your key
onepin skill install
```

That's the whole thing. With no flags, `onepin skill install` installs into every tool it detects under your home directory — `~/.claude`, `~/.cursor`, `~/.codex`, `~/.copilot`, `~/.gemini` — and falls back to Claude Code if it detects none.

Then restart your tool, or run `/reload-plugins` in Claude Code, so it picks up the new skills directory.

> **Note**
>
> Installing touches nothing but your filesystem — no client, no network, no authentication, so it works offline. `onepin login` matters later, when the skill actually runs a command on your behalf.

### Use it

In **Claude Code** the skill is a slash command named after the package:

```
/onepin list my workflows and run the Korean one
```

Cursor, Codex, Gemini CLI, and Copilot load it on their own when your request is about Onepin — there's nothing to type.

### Pick your tools

| Command                                            | Installs into                                        |
| -------------------------------------------------- | ---------------------------------------------------- |
| `onepin skill install`                             | Every tool detected under your home directory        |
| `onepin skill install --tool claude --tool cursor` | Only the tools you name (repeat `--tool`)            |
| `onepin skill install --all`                       | All five, detected or not                            |
| `onepin skill install --project`                   | The current directory instead of your home directory |

`--project` is for a repo your team shares: commit the skill folder and every clone gets it. Cursor, Codex, and Copilot all read `.agents/skills` in a project, so one copy covers the three.

### Where it lands

| Tool        | Home install               | `--project` install       |
| ----------- | -------------------------- | ------------------------- |
| Claude Code | `~/.claude/skills/onepin`  | `./.claude/skills/onepin` |
| Cursor      | `~/.cursor/skills/onepin`  | `./.agents/skills/onepin` |
| Codex       | `~/.codex/skills/onepin`   | `./.agents/skills/onepin` |
| Copilot     | `~/.copilot/skills/onepin` | `./.agents/skills/onepin` |
| Gemini CLI  | `~/.gemini/skills/onepin`  | `./.agents/skills/onepin` |

`onepin skill path` prints those paths and whether each already exists, writing nothing. It takes the same `--tool`, `--all`, and `--project` flags, so it's the way to check a plan before running it.

## What the skill teaches

The skill is a contract, not a frozen command list — which is why it keeps working as the CLI grows:

* **Discover, don't guess.** It looks commands up with `onepin schema` — the machine-readable manifest of every command, its flags, and whether it's destructive — instead of inventing flags from memory.
* **`--json` goes first.** `onepin --json workflows list`, not a trailing `--json`. Success is JSON on stdout; a failure is an error envelope on stderr and a non-zero exit.
* **The exit code is the success signal**, not the presence of output.
* **Destructive commands need your explicit yes.** The skill is told never to add `--yes` to silence a prompt, and every destructive command is flagged as such in the manifest.
* **Preflight once.** It checks `onepin --version` and `onepin whoami` before doing real work, so "not installed" and "not logged in" surface as themselves rather than as a confusing failure three commands later.

## Update it

The skill ships inside the wheel, so a new version arrives with the package:

```bash
pip install --upgrade onepin
onepin skill install --force
```

`install` refuses to overwrite files that are already there — that's the `FILE_EXISTS` error, and nothing is touched when it fires — so `--force` is how you take the new copy.

## Remove it

```bash
onepin skill uninstall              # prompts first
onepin skill uninstall --all --yes  # every tool, no prompt
```

It only ever deletes the `onepin/` folder, never the `skills/` directory around it, and it's idempotent — with nothing installed it prints `Nothing to remove.` and exits `0`.

## Skill or MCP?

Both give an agent the same workspace. They differ in what has to be on your machine and who runs the work.

|                             | Agent skill                                     | [MCP server](/docs/get-started/mcp-server)      |
| --------------------------- | ----------------------------------------------- | ----------------------------------------------- |
| Setup                       | `pip install onepin`, then one command          | Paste a URL — nothing installed                 |
| Auth                        | Your API key, via `onepin login`                | OAuth sign-in, no key                           |
| Who acts                    | Your agent runs the local CLI                   | The server runs the tools                       |
| Works in                    | Claude Code, Cursor, Codex, Gemini CLI, Copilot | Any MCP client                                  |
| Confirmation before a spend | The skill is instructed to ask                  | The server refuses until a second call confirms |

Reach for the skill when the CLI is already in your workflow — same key, same scripts, and it works offline. Reach for MCP when you want a connection with nothing installed and a server-enforced gate in front of anything that spends credits.

## Troubleshooting

| Symptom                              | Cause                                                                                                                           |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `onepin: command not found`          | The package isn't installed, or isn't on your `PATH` — `pip install onepin`                                                     |
| `FILE_EXISTS` on install             | The skill is already there. Pass `--force` to overwrite it; nothing was changed                                                 |
| Your tool doesn't see the skill      | It was running when you installed. Restart it, or run `/reload-plugins` in Claude Code                                          |
| The agent says you're not logged in  | The skill drives the CLI, which needs its own key — run `onepin login`                                                          |
| `CONFIRMATION_REQUIRED` on uninstall | Under `--json` there is no prompt to answer. Pass `--yes`                                                                       |
| It installed somewhere unexpected    | `onepin skill path` shows where it is. Uninstall, then reinstall with `--tool` or `--project`                                   |
| `SKILL_PAYLOAD_MISSING`              | The installed wheel is damaged or was repackaged without its data files — reinstall with `pip install --force-reinstall onepin` |