Getting started

The fastest way to bring AI skills and agents into your project — install the CLI, pull in what you need, publish your own, and connect a coding agent to the registry in minutes.

Set up with an AI agent

Paste this into Claude Code, Cursor, or any coding agent to have it install and configure the CLI for you.

You are helping me set up the ahood CLI so I can install and use skills from https://ahood.vercel.app in this project.

1. Install the ahood CLI: `npm i -g @ahood/cli` gives you a persistent `ahood` command, used in every step below. For a single one-off command instead, run `npx @ahood/cli@latest <command>` without installing anything. To build from source instead: https://github.com/AlexKay28/ahood-cli, `npm run build`.
2. Run `ahood login`. It prints a URL for a device-code login -- open it in a browser and approve it there; the CLI stores the resulting token at ~/.config/ahood/credentials.json.
3. Use `ahood skill search <query>` to find skills relevant to what we're building, and `ahood skill add <owner>/<skill>[@version]` to install one into .claude/skills/<owner>/<skill>/, pinned in .claude/skills.lock.json. Check the lockfile afterward to confirm the pin landed.
4. `ahood skill update [<owner>/<skill>]` moves an existing pin forward to the latest version; `ahood skill remove <owner>/<skill>` uninstalls and unpins.
5. If I ask you to publish something: run `ahood skill publish <owner>/<skill>@<version>` from a folder containing SKILL.md. If the skill doesn't exist yet, add `--name "<Display Name>"` (and optionally `--tagline`/`--tags`/`--license`) to create it as part of that same publish -- there's no separate create step. New skills are created private; if I want it publicly discoverable, run `ahood skill edit <owner>/<skill> --visibility public` afterward. The publish command uploads then polls until the version finishes processing server-side, printing "Published ..." on success or the real failure reason if it doesn't.
6. Agents are a second artifact kind, parallel to skills: a folder with AGENT.md (persona/behavior definitions) instead of SKILL.md. Publish one the same way but add `--kind agent` (auto-detected and optional if the folder only has AGENT.md). `ahood skill add` then installs it to .claude/agents/<owner>@<agent>.md instead of .claude/skills/, automatically based on the artifact's kind -- no extra flag needed on `add`.
7. MCP servers are a third artifact kind: a folder with server.json (the MCP server manifest) at its root instead of SKILL.md/AGENT.md. Publish one the same way but add `--kind mcp` (auto-detected and optional if the folder only has server.json). `ahood skill add` then merges the install into the installing project's .mcp.json instead of writing into .claude/, prompting for any server.json `environment_variables` marked secret that aren't already set in your shell.
8. For CI or any non-interactive environment, use the AHOOD_TOKEN environment variable instead of `login` -- every command checks it first.

Confirm you understand the install step above, then go ahead.

Install

npm i -g @ahood/cli

Or run a single command without installing anything: npx @ahood/cli@latest <command>. To build from source: clone the CLI repo and run npm run build.

Commands

ahood login: Device-code browser login, stores a token at ~/.config/ahood/credentials.json.
ahood logout: Removes the stored token.
ahood whoami: Reports whether your stored token still authenticates and, since it does, the authenticated username.
ahood token create <name>|list|revoke <id>: All three subcommands require an existing browser-backed session (see Personal API tokens below) -- a CLI process authenticated with a bearer token cannot manage tokens end-to-end, only a logged-in browser session can.
ahood completion <bash|zsh|fish>: Print a shell completion script for the command names.
ahood skill search <query>: Search published skills.
ahood skill view <owner>/<skill>: Show a skill’s details -- tags, license, homepage, repository, dates, and more -- without installing it. Alias: ahood skill show.
ahood skill versions <owner>/<skill>: List a skill's published-version history: version, changelog, size, and publish date.
ahood skill list: List your own skills, public and private, with their visibility and download/star counts.
ahood skill add <owner>/<skill>[@version]: Install into .claude/skills/<owner>/<skill>/, pinned in .claude/skills.lock.json. For an agent (published with --kind agent), installs to the single file .claude/agents/<owner>@<skill>.md instead. For an MCP server (published with --kind mcp), merges an entry into the installing project’s .mcp.json instead, prompting for any secret environment variables not already set in your shell -- the install path branches automatically based on the artifact’s kind, no extra flag needed.
ahood skill update [<owner>/<skill>]: Move the lockfile pin forward to the latest version.
ahood skill remove <owner>/<skill>: Uninstall and unpin.
ahood skill edit <owner>/<skill> [--tagline] [--tags] [--license] [--visibility] [--homepage] [--repository]: Update a skill you own. Only the flags you pass are changed; requires the publish scope.
ahood skill unpublish <owner>/<skill>[@version]: Without @version: deletes the skill from the registry for every consumer, not just your local install. With @version: yanks just that one version instead -- marked yanked rather than removed, so existing lockfile pins still resolve but new installs are warned off it. Prompts for a typed “yes” confirmation first either way.
ahood skill star <owner>/<skill>: Star a skill. Requires the publish scope; idempotent, so starring one you've already starred is a no-op.
ahood skill unstar <owner>/<skill>: Remove your star. Also idempotent -- unstarring one you never starred is a no-op.
ahood skill init [name]: Scaffold a new skill folder with a minimal, valid SKILL.md.
ahood skill publish <owner>/<skill>@<version> [--name] [--tagline] [--tags] [--license] [--kind]: Publish a new version of a skill, agent, or MCP server from a folder (must contain SKILL.md, AGENT.md, or server.json). --kind agent publishes it as an agent and --kind mcp publishes it as an MCP server instead of a skill; auto-detected from the folder’s contents (e.g. an AGENT.md-only folder, or a server.json-only folder) when omitted. If the skill/agent/MCP server doesn’t exist yet, this creates it first -- pass --name (required in that case) and optionally --tagline/--tags/--license. Processing happens server-side after upload; the CLI polls and reports the final status.

Personal API tokens

Create, list and revoke personal API tokens at /settings/tokens in the browser. Token management is deliberately session-only, so it cannot be done with a token — the CLI’s ahood token subcommands exist but are not usable end-to-end today, and will report that the action requires a logged-in browser session.

Tokens carry scopes. A token with only the read scope is read-only across the whole API: it can search, read and download, but every write — publishing a skill or a version, and starring or unstarring — requires the publish scope.

CI usage

Set AHOOD_TOKEN in your CI environment instead of running login interactively — every command checks it before falling back to the stored credentials file.

Public API

Every CLI command calls the same /api/v1/** routes documented in this repo’s backend architecture doc, authenticated with Authorization: Bearer <token> instead of a browser session.

MCP server

An agent can call the registry directly, mid-session, instead of a human operating a website or CLI. Connect to POST /api/mcp (Streamable HTTP, JSON responses, no SSE) with the same personal access token minted at /settings/tokens:

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json, text/event-stream

No prior initialize call is required on a stateless server — a client’s normal connection handshake still runs, but each tool call is a self-contained request.

Tools, mirroring the REST API one-for-one over the same service layer:

search_skills: Keyword search, tag filter, sort (public skills, no scope required).
get_skill: Metadata + latest-version details for owner/skill.
fetch_skill: A 60-second signed download URL for a version (default: latest). Pinned snapshot only — no ongoing link back to upstream, same as npm/pip pinning.
list_skill_versions: A skill’s published-version history (edit/provenance history).
list_my_skills: The caller’s own skills, public and private.
create_skill, update_skill, delete_skill: Require the publish scope.
report_skill: Flag a visible skill for review. Reports never auto-hide a skill; hiding is a human admin action.

fetch_skill shares its 60/minute rate-limit bucket with the REST download route, and create_skill shares its 20/hour bucket with POST /api/v1/skills — splitting calls across REST and MCP does not double a caller’s effective limit.