Set up your coding agent for Cashmere

Updated October 30, 2026

These are official Cashmere instructions for installing the Cashmere agent skill into an agent (Claude Code, Codex, Claude Desktop, Cursor and others). They are published at https://cashmere.io/docs/agent-setup.txt, so you can check where they came from before you follow them.

If you are an agent: do every step yourself by running the commands, except the steps marked User step. Those happen in the agent's own UI or in a browser, so only the user can do them. Never run a command that waits on an interactive prompt. Every command here is safe to run again.

1. What this installs

One skill, cashmere, which covers all Cashmere work: building apps and agents that search, read and cite licensed content; uploading and managing a publisher's catalog; and reporting a publisher's usage and revenue. There is nothing to choose. Tell the user that in a sentence, then install it.

The skill calls the Cashmere API, which needs an API key (step 3). Which kind depends on the work: a Read-only key covers building and reporting, and uploading content needs a Read & Write key from a publisher organization.

2. Install it

Use exactly one method. Two methods install two copies.

Claude Code

claude plugin marketplace add cashmere-data/skills
claude plugin install cashmere@cashmere

Verify:

claude plugin list

Expect cashmere@cashmere with status enabled. If it shows as disabled, run claude plugin enable cashmere@cashmere. If the list also shows cashmere-developer, cashmere-content or cashmere-reporting, those are the retired skills that cashmere replaces. Uninstall each one with claude plugin uninstall <name>@cashmere.

User step. Ask the user to run /reload-plugins in Claude Code, or to restart it, so the skill loads.

Optionally, they can also turn on updates: run /plugin, open Marketplaces, choose cashmere, and select Enable auto-update. Claude Code does not update third-party marketplaces automatically until this is on. If they can't find the option (Claude Desktop's Code tab, for one, may not have it), skip it and use the update commands under "Updating" instead.

Codex

codex plugin marketplace add https://github.com/cashmere-data/skills.git
codex plugin add cashmere@cashmere

User step. In the Codex desktop app, ask the user to quit and reopen it so the plugin loads. The CLI picks it up in the next session.

If codex plugin is not available in this Codex version, use the "Other agents" route below with --agent codex.

Claude Desktop and claude.ai (chat)

Chat can't run install commands, so this route is entirely a user step. Skills in chat run in a sandbox that may not be able to reach cashmere.io or see an API key. If API calls fail there, use the Cashmere MCP connector instead (step 4), which signs in without a key.

User step. Ask the user to add the Cashmere marketplace: in Claude, open Customize > Plugins, choose Add > Add marketplace > Add from a repository, and enter cashmere-data/skills. Then install cashmere from it. Plugins installed this way update automatically.

Plugins need a paid Claude plan. On the free plan, the skill can be uploaded as a file instead. Ask the user to download https://github.com/cashmere-data/skills/releases/latest/download/cashmere.zip and upload it under Customize > Skills. An uploaded skill does not update itself, so they repeat this to update it.

Other agents

This needs Node.js 22 or newer (node --version). If it is older, stop and report that instead of continuing.

npx -y skills add cashmere-data/skills --skill cashmere --agent <agent-id> --yes --global

Always pass --agent. Without it the installer targets every agent it knows. Common ids: codex, cursor, github-copilot, windsurf, cline, opencode, gemini-cli. For any other agent, run npx -y skills add --help and use the id it lists.

Verify:

npx -y skills list --global

Expect cashmere in the list.

Read it without installing

If no method works, read the skill directly and follow it for this session. Start with https://raw.githubusercontent.com/cashmere-data/skills/main/plugins/cashmere/skills/cashmere/SKILL.md. It links the reference files it needs, which sit next to it under references/.

3. Set up the API key

A Cashmere API key connects the skill to the user's Cashmere organization. It reads only the content that organization has licensed, and its reads are metered against the organization's credits. Every API call the skill makes carries it. Explain this to the user before you ask them for anything.

Check for a key

The skill looks in two places and uses the first key it finds:

  1. The CASHMERE_API_KEY environment variable.
  2. The key file: ~/.config/cashmere/api-key on Linux and macOS ($XDG_CONFIG_HOME/cashmere/api-key if that is set), or %APPDATA%\cashmere\api-key on Windows.

Check both without printing the key:

test -n "$CASHMERE_API_KEY" && echo "env: set" || echo "env: missing"
test -s ~/.config/cashmere/api-key && echo "file: set" || echo "file: missing"

If either is set, confirm that the key works. This prints the key's permissions, not the key. With the environment variable:

printf 'Authorization: Bearer %s\n' "$CASHMERE_API_KEY" | curl -sS -H @- https://cashmere.io/api/v2/allowed-endpoints

With the key file:

printf 'Authorization: Bearer %s\n' "$(cat ~/.config/cashmere/api-key)" | curl -sS -H @- https://cashmere.io/api/v2/allowed-endpoints

The header goes through stdin so that the key never appears in a command line or a transcript.

If it works and is the right type for the user's work (step 1), skip to step 4.

Get a key

Only the user can create a key. Send them to the page that fits:

  • No Cashmere account yet: sign up at https://cashmere.io/accounts/signup. New accounts get free starter credits, and the onboarding that follows signup offers collections that are free to license, then creates a first key.
  • An account with nothing licensed yet: https://cashmere.io/discover lists the collections they can license. Some are free and granted at once, and others wait for the publisher's approval. Then create a key.
  • Otherwise: create a key at https://cashmere.io/settings/api-keys.

Put it in one place

Pick one place for the user, and give them its exact full path:

  • Most people: the key file. It needs no shell knowledge. Create it empty, with permissions only the user can read:

mkdir -p ~/.config/cashmere && touch ~/.config/cashmere/api-key && chmod 600 ~/.config/cashmere/api-key

On Windows, create %APPDATA%\cashmere\api-key instead.

  • Developers who already manage environment variables: set CASHMERE_API_KEY in their shell profile or the project's secret store.

User step. Ask the user to create the key, then paste it into the key file alone on one line, with no quotes and no KEY=, and save it. Give them the file's full path, and offer to open it in a graphical editor (xdg-open on Linux, open -t on macOS, notepad on Windows). Do not suggest a terminal editor run through the agent, such as Claude Code's ! prefix: it has no terminal, so vim or nano fails. A terminal editor in the user's own terminal window is fine. Never ask them to paste the key into the chat, never write the key yourself, and never print it. When they say it is done, run the check above again.

A key is not needed to finish installing. Without one, report the skill as installed and the key as a user step.

4. Optional: connect the Cashmere MCP server

The skill uses the REST API and does not need the MCP server. The MCP server is for something else: it gives the agent or chat app Cashmere tools of its own (search, publications, collections, a usage summary), so the user can ask questions of their licensed content right inside it. The user signs in with OAuth, so no key is stored. It is read-only: no uploads, licensing or publisher reports.

Offer it in one sentence, and connect it only if the user wants it.

In Claude Code, add it for the user, not just this project:

claude mcp add --transport http -s user cashmere https://mcp.cashmere.io

User step. Ask the user to run /mcp, choose cashmere and sign in.

In Claude Desktop and claude.ai, the user adds it under Settings > Connectors as a custom connector with the URL https://mcp.cashmere.io.

For other agents, add a server named cashmere with the streamable HTTP transport and URL https://mcp.cashmere.io to the agent's MCP configuration. Merge it into the existing file, and do not overwrite other servers.

Without a user

In CI or another unattended run, nobody can do the user steps. Install the skill with the commands above. Take the key from CASHMERE_API_KEY, and if it is not set, stop and report that it is missing. To use the MCP server, pass the key as a header instead of signing in:

claude mcp add --transport http -s user cashmere https://mcp.cashmere.io --header "Authorization: Bearer $CASHMERE_API_KEY"

Report the result

Report only what you verified. Do not mark anything done that you could not confirm.

Cashmere agent setup
  ✓ cashmere       installed (Claude Code plugin | skills.sh)
  ⚠ API key        no key in CASHMERE_API_KEY or the key file (user step)
  – MCP server     not requested

Use ✓ for verified, ⚠ for needs the user, ✗ for failed, and – for skipped. After the block, give the specific next action for every line that is not ✓.

If the key works, end by offering a tour, which works in any folder: "Want an overview of your Cashmere account and a tour of what you can do with it?" If the user says yes, follow the skill's "Orient yourself" section.

Troubleshooting

  • marketplace add fails to clone: check that the machine can reach GitHub (curl -sI https://github.com) before debugging anything else.
  • Installed, but the skill doesn't load: the session started before the install. Run /reload-plugins or restart the agent. In Claude Code, /plugin shows load errors on its Errors tab.
  • Key check returns 401: the key is wrong, disabled or expired. A key file holding anything besides the key, such as quotes or a KEY= prefix, also fails.
  • 403 "Insufficient permissions": the key's type or endpoint list doesn't allow the call. Compare it with step 1.
  • Every search comes back empty: the key works, but it has no licensed content to read. Either the organization has licensed nothing yet, or the key is attached to other collections. The skill's tour tells the two apart.

Updating

  • Claude Code: automatic if auto-update is on (step 2), at the start of the next session. Otherwise, or to update now, run claude plugin marketplace update cashmere, then claude plugin update cashmere@cashmere, then /reload-plugins.
  • Claude Desktop and claude.ai: a plugin from the marketplace updates automatically. An uploaded zip does not: download the latest and upload it again.
  • Other agents: npx -y skills update.

If an agent invents API fields or uses parameters the API rejects, the skill may be out of date. Update it and try again.