Publishing from Claude Code

Claude Code can prepare, validate and publish an artifact for you through the skills CLI. It acts with a scoped token: enough to publish in your namespace, nothing more.

1. Create a publisher token

Ask for exactly the publishing scopes, your namespace, and an expiry:

This token cannot revoke releases, deprecate artifacts, create or list tokens, read the audit trail or moderate. Keep those for yourself in the dashboard.

Ways to create it:

• Dashboard → Tokens → New token. The token is displayed once.
• From an existing credential: skills auth token create --name claude-code-publisher --scopes artifacts:read,artifacts:create,artifacts:update,uploads:create,releases:publish,releases:update --namespace <yourns> --expires-in 90d --store — --store puts the new token straight into the credential store instead of printing it. The calling credential needs tokens:write and can only grant what it holds itself.
• Registry operator, from the server, piped directly into the credential store so it never appears on screen:

ssh <node> 'cd ~/apps/skills-spboucher-ai && pnpm -s admin token create --user <email> --name claude-code-publisher --namespace <yourns> --expires-in 90d' \
  | skills login --token-stdin

Optionally restrict the token to an address range with --ip <CIDR>.

2. Store it where Claude Code can use it but not show it

skills login            # prompts with hidden input, checks the token, stores it
skills whoami           # shows the identity, scopes, namespaces and expiry — never the token

Lookup order used by the CLI:

1. SKILLS_TOKEN in the environment of the process (for one-off, process-scoped use).
2. The OS credential store: macOS Keychain (service skills-registry, account = registry host), or secret-tool on Linux.
3. A 0600 file at ~/.config/skills/credentials.json, only if you opted in with --insecure-file.

Claude Code runs skills … commands; the CLI reads the credential itself. The token never needs to be in a prompt, a CLAUDE.md, an MCP description, a .env file or your shell profile, and it must not be put there.

3. Ask in plain language

Publish the citation-check skill in ./skills/citation-check to Skills as version 1.2.0, with README, changelog and release notes.

A well-behaved session then does this, and you should expect to see each step:

1. Uses the directory you named. It does not go looking through your workspace for other things to publish.
2. Reads the package: manifest, SKILL.md, scripts. It points out anything that looks like a secret, personal data, private research material or third-party proprietary content.
3. Updates public documentation and metadata if you asked (README, CHANGELOG, version, compatibility).
4. Validates: skills validate ./skills/citation-check.
5. Dry run: skills publish ./skills/citation-check --visibility public --dry-run, and shows you the report: target, version, visibility, file list with sizes, skipped files, declared permissions, findings, checksum.
6. Waits for your approval when it matters (see below).
7. Publishes: skills publish ./skills/citation-check --visibility public. The CLI uploads the archive with its hash and the server validates and scans it.
8. Verifies: fetches the published metadata, compares the checksum, checks the install instructions.
9. Reports the exact URL and version. If the server refused or quarantined the release, it says so; it does not claim success before the API confirms it.

When your explicit approval is required

The API enforces confirmation for visibility and destructive actions: without an explicit confirmation flag it answers 428 confirmation_required. The CLI asks interactively; --yes answers on your behalf, so an agent should pass --yes only after you approved the dry run. Routine patch releases can be delegated under a policy you state in advance, for example: "patch versions of artifacts that are already public, with no change in permissions or file types, may be published after a clean dry run".

Private versus public material

The files next to a SKILL.md are not automatically meant for the public. Before the dry run, make the intended contents explicit:

• Keep the package directory free of data, drafts, notebooks and credentials.
• Use .skillsignore for anything that must stay local.
• The dry-run file list is the release. If a file should not be there, stop and remove it.

Blocking checks catch common credential formats and files such as .env. They cannot recognise your confidential manuscript or a client's data.

Rotation, revocation and troubleshooting

skills auth status                 # is a credential stored, for which registry, when does it expire
skills auth token rotate           # new secret, same grants; stored automatically, never printed; the old one stops working
skills auth token revoke <id|prefix>

Rotate before expiry and whenever the token may have been exposed. If a token leaks, revoke it first, then review your audit trail in the dashboard.

Exit codes of the CLI: 0 success, 1 error, 2 validation failed, 3 authentication or authorization problem.

Using MCP instead of the CLI

The registry MCP server offers the same publishing steps as tools. Archive bytes still travel by HTTP PUT, and the same token rules apply. The CLI is the simpler path for publishing because it packs, hashes, uploads and verifies in one command.