spb/skills-spboucher-ai

1---2title: Publishing from Claude Code3description: Give Claude Code a scoped publishing token, keep it in the OS credential store, and publish with a dry run and your approval.4order: 215section: Publish6---78# Publishing from Claude Code910Claude 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.1112## 1. Create a publisher token1314Ask for exactly the publishing scopes, your namespace, and an expiry:1516| Scope | Why |17|---|---|18| `artifacts:read` | Read your own private and draft artifacts |19| `artifacts:create` | Create an artifact in your namespace |20| `artifacts:update` | Edit summary, links, keywords, visibility |21| `uploads:create` | Begin an upload and send the archive |22| `releases:publish` | Finalize the upload into a release |23| `releases:update` | Edit release notes (content stays immutable) |2425This token **cannot** revoke releases, deprecate artifacts, create or list tokens, read the audit trail or moderate. Keep those for yourself in the dashboard.2627Ways to create it:2829- **Dashboard → Tokens → New token.** The token is displayed once.30- **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.31- **Registry operator, from the server**, piped directly into the credential store so it never appears on screen:3233```bash34ssh <node> 'cd ~/apps/skills-spboucher-ai && pnpm -s admin token create --user <email> --name claude-code-publisher --namespace <yourns> --expires-in 90d' \35  | skills login --token-stdin36```3738Optionally restrict the token to an address range with `--ip <CIDR>`.3940## 2. Store it where Claude Code can use it but not show it4142```bash43skills login            # prompts with hidden input, checks the token, stores it44skills whoami           # shows the identity, scopes, namespaces and expiry — never the token45```4647Lookup order used by the CLI:48491. `SKILLS_TOKEN` in the environment of the process (for one-off, process-scoped use).502. The OS credential store: macOS Keychain (service `skills-registry`, account = registry host), or `secret-tool` on Linux.513. A `0600` file at `~/.config/skills/credentials.json`, only if you opted in with `--insecure-file`.5253Claude 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.5455## 3. Ask in plain language5657> Publish the citation-check skill in ./skills/citation-check to Skills as version 1.2.0, with README, changelog and release notes.5859A well-behaved session then does this, and you should expect to see each step:60611. **Uses the directory you named.** It does not go looking through your workspace for other things to publish.622. **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.633. **Updates public documentation and metadata** if you asked (README, CHANGELOG, version, compatibility).644. **Validates**: `skills validate ./skills/citation-check`.655. **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.666. **Waits for your approval** when it matters (see below).677. **Publishes**: `skills publish ./skills/citation-check --visibility public`. The CLI uploads the archive with its hash and the server validates and scans it.688. **Verifies**: fetches the published metadata, compares the checksum, checks the install instructions.699. **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.7071## When your explicit approval is required7273| Situation | Why |74|---|---|75| First public release of an artifact | It becomes visible to everyone, permanently in the history |76| Changing visibility | Exposes or hides the artifact |77| Changing declared permissions, or adding scripts or network use | Changes what installers are agreeing to |78| Deprecating, archiving or revoking | Affects people who depend on it (and needs scopes the publisher token does not have) |7980The 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".8182## Private versus public material8384The files next to a `SKILL.md` are not automatically meant for the public. Before the dry run, make the intended contents explicit:8586- Keep the package directory free of data, drafts, notebooks and credentials.87- Use `.skillsignore` for anything that must stay local.88- The dry-run file list is the release. If a file should not be there, stop and remove it.89- Screenshots listed under `examples` in the manifest are public images. Open each one before publishing and check that it shows nothing but the package at work: no other window, account name, e-mail address, home-directory path, token or private file name. A published screenshot cannot be edited, only revoked with its release.9091Blocking checks catch common credential formats and files such as `.env`. They cannot recognise your confidential manuscript or a client's data.9293## Rotation, revocation and troubleshooting9495```bash96skills auth status                 # is a credential stored, for which registry, when does it expire97skills auth token rotate           # new secret, same grants; stored automatically, never printed; the old one stops working98skills auth token revoke <id|prefix>99```100101Rotate 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.102103| Symptom | Meaning | Fix |104|---|---|---|105| `401 token_expired` | Past its expiry | Create a new token and `skills login` |106| `401 token_revoked` | Revoked or replaced by rotation | `skills login` with the current token |107| `401 invalid_token` | Wrong or truncated token, or calling from an address outside the token's allowlist | Check `skills auth status`; re-login |108| `403 insufficient_scope` | The action needs a scope this token lacks (the response names it) | Do it from the dashboard, or issue a token with that scope |109| `403 namespace_forbidden` | The manifest's namespace is not on this token | Fix the manifest name or use the right token |110| `409 version_exists` | That version is already published | Bump the version; releases are immutable |111| `422 release_rejected` | Blocking findings | Read the findings, fix, bump nothing, publish again |112| `428 confirmation_required` | Needs a human yes | Approve, then rerun |113| `429 rate_limited` | Too many requests, or repeated failed authentications from your address | Wait for the time in `Retry-After` |114115Exit codes of the CLI: `0` success, `1` error, `2` validation failed, `3` authentication or authorization problem.116117## Using MCP instead of the CLI118119The [registry MCP server](/docs/mcp) 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.120