Agent skill

The onepin package ships an Agent Skill — a SKILL.md folder that teaches an AI coding tool how to drive the Onepin CLI. 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 is the other, and they coexist. Which one to pick is at the bottom of this page.

Install

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.

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

--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

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:

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

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.

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