Publish an Agent Skill

Publish an Agent Skill

Author, validate, review, merge, release, and verify an Agent Skill without assuming a repository owner, account, forge, package layout, or private delivery system. This skill owns one explicitly selected publication target. It does not silently copy the skill into private repositories, plugins, mirrors, websites, sidecars, control planes, or another owner's account.

When to Use

• “Publish this skill,” “release this Agent Skill,” or “add this skill to the public pack.”
• A skill draft must become a discoverable, installable, verified release.
• An existing published skill needs a versioned content update.

Do not use for a user-local skill that should remain unpublished, or for private organization policy when a target-specific publishing skill explicitly overrides this one.

Publication Authority

Discover the repository, owner, publication target, skill layout, version source, tests, review requirements, merge policy, release mechanism, and discovery channels from the active repository and the user's request. If the target is not uniquely known, ask before writing or publishing. Never infer a destination from memory, a sibling clone, an installed skill, a similarly named organization, or credentials that happen to work.

This workflow has one primary target by default.

External and sidecar targets are opt-in only

An external target includes any second repository, private plugin, marketplace, website, mirror, sidecar runtime, canonical-source repository, generated copy, or local-global installation outside the primary target.

Touch one only when the user explicitly asks for or mentions that named target in the active request. Do not infer external propagation from repository history, links, provenance files, prior releases, available credentials, or the presence of another checkout. When explicitly requested, treat every external target as a separate publication with its own scope, validation, approval, readback, and completion status. A primary release is not proof that a sidecar published.

Prerequisites

1. Inspect repository instructions, current branch/status, recent release tags, skill peers, manifest/frontmatter conventions, tests, CI, and release docs.
2. Resolve the exact primary target and whether this is a new skill or update.
3. Define acceptance: skill identity, trigger, boundaries, carried files, discovery name, version, install command, and proof required after release.
4. Inventory external targets mentioned by the user. Record all others as out of scope; do not modify them.
5. Confirm authorization before remote writes, merge, publication, destructive replacement, or cross-account changes. Every external target must be named explicitly by the user in the active request; repository policy may add safeguards but cannot select or authorize an unmentioned target.

Procedure

1. Discover the target contract. Trace validators, generators, catalog code, neighboring imports/links, release automation, and install commands. Do not invent files, fields, commands, versions, or namespaces. Complete when: repository owner, target branch, skill path, metadata contract, checks, release mechanism, and discovery surfaces are evidenced.
2. Write acceptance tests first. Add focused contract tests against the shipped SKILL.md and carried files. Run them and confirm failure for the missing or stale behavior. Complete when: RED proves the intended contract.
3. Author the minimum skill. Match peer structure and progressive disclosure. Keep triggers and counter-triggers precise; make boundaries, prerequisites, ordered steps, pitfalls, and verification executable. Add carried reference files or scripts only when the main file would otherwise carry bulky or repeated detail. Update the repository README/catalogue entry in the same change so humans and agents can discover the exact skill description, install coordinates, and how to update it. Add human-readable release notes or changelog prose that explains what changed, who should care, compatibility/migration impact, and the action required to receive it. A version number or generated diff is not release notes.
4. Validate locally. Run focused tests, frontmatter/link/catalog validators, generated-artifact drift checks, repository-required tests, and diff hygiene. Re-run from a clean dependency state when release reproducibility matters. Complete when: every required local check passes and the diff contains only intended target files.
5. Review before publication. Use the repository's required review gate. If request-blocks-review is installed and Blocks review is requested by the user or repository policy, load it and run review/fix/verify/re-review until the current head is clean. Never silently install a reviewer dependency.
6. Open the publication change. Create the repository-standard branch, commit, and pull request only after scope is reviewed and authorization is present. State tests, release impact, discovery impact, and explicitly excluded external targets. Complete when: the PR URL and exact head exist.
7. Follow CI and review to convergence. Distinguish queued acknowledgements from real reviews. Fix findings, rerun checks, push, and request current-head re-review as required. Complete when: required CI and review gates are green for the exact merge head.
8. Merge and release. Follow branch protection and repository release policy; do not treat merge as publication. Create or verify the version/tag/release and wait for deployment/indexing channels that the target contract names. Publish the human release notes with exact install/update guidance. Encourage affected users and agents to update without claiming or performing unrequested local synchronization.
9. Verify external state from source. Read back the main-branch skill, release, and catalog. Run installer/CLI discovery against the published repository and confirm exact name, description, source URL/type, and version where exposed. Test an isolated install; do not rely on a preexisting local copy or redirect.
10. Synchronize requested local libraries. Only when the user explicitly names a local-global or project-local target, follow All-plane local synchronization. Treat every scope, machine, agent, and native/manual channel as an independent target.
11. Report staged completion. Separate verified, published, deferred, and out of scope. A cache/index delay is pending, not failure or success. Name every explicitly requested external target and its independently verified state.

All-plane Local Synchronization

Publishing and isolated install verification do not authorize changing the user's real skill libraries. Enter this procedure only when the active request explicitly names a local-global scope, project scope, machine, agent set, native plugin, or manual/upload target.

Inventory every plane

1. Read the installed inventory in machine-readable form for both scopes:

   npx skills list --global --json
   npx skills list --json
   

2. Record each skill's scope, source provenance, install path, managed/unmanaged status, copy/symlink form, and every agent path that consumes it. A shared canonical copy linked into several agents is one managed installation with several projections; copied directories can drift independently. Present a deduplicated target manifest before writes: machine × scope/profile × agent/channel × physical path × mechanism. “All supported agents” covers only this discovered set, not unknown profiles or guessed locations.

3. Discover native plugin/package channels from the target's own release contract. A plugin-native skill and a standalone skill with the same bare name are separate identities; do not replace or remove one to update the other.

4. Inventory manual planes separately: uploaded archives, downloaded files, browser-only agents, remote agents, containers, other machines, and clients the Skills CLI reports as unsupported. Never claim they were synchronized from a successful update on this machine.

Apply by ownership and scope

• CLI-managed global copy: update the named skills without scope inference:

  npx skills update <skill...> --global --yes
  

• CLI-managed project copy: run from the exact project and specify project scope explicitly:

  npx skills update <skill...> --project --yes
  

• Missing global copy across all supported agents: add from the authoritative published source, preserving the repository's install form:

  npx skills add <published-source> --skill <skill...> --global --agent '*' --yes
  

  Use --copy only when the user or existing installation selected copied delivery. Do not silently convert copy to symlink or symlink to copy.

• Missing project copy: run in the exact project, omit --global, and name the intended agents. Project installation may create or update lock metadata; include and verify it according to repository policy.

• Unmanaged or provenance-less copy: do not overwrite it as if managed. Show the exact path and proposed source, obtain approval for destructive replacement, then remove only that identity/scope and reinstall from the authoritative source. Preserve unrelated and namespaced skills.

• Upstream deletion: report a removal candidate; require separate explicit destructive approval before deleting any local skill.

• Native plugin/package channel: use that channel's marketplace/registry refresh and update commands, then read back its declared version and skill namespace. Do not use the generic Skills CLI as proof that a native plugin updated.

• Manual/upload channel: produce or fetch the released artifact, verify it, and give the user the replacement/upload action. If the agent cannot perform that UI action, report manual action required; never mark it updated.

• Unsupported agent: report the literal unsupported result and leave it unsupported. Use deferred only for an explicitly requested target that is temporarily unreachable. Do not fabricate a path or copy files into an undocumented folder.

Verify every requested plane

1. Re-run scope inventories and confirm source provenance and all expected agent projections. --agent '*' means every agent supported by the installed CLI, not every agent that exists.
2. Compare installed bytes or a cryptographic hash with the authoritative published artifact when the channel exposes no trustworthy version. A command exiting zero is not freshness proof. Where no authoritative version/ref/digest is comparable, report freshness as unknown; do not infer it from a rewritten local timestamp or command success.
3. For native plugins, read back the exact installed version and namespace. For project scope, verify the consuming project sees the project copy rather than a higher-precedence global/plugin copy.
4. Restart or reload each affected agent/runtime when its loader caches skills; current-session discovery may remain stale until then.
5. Report a matrix with scope × agent/channel × identity: updated, already current, manual action required, unsupported, deferred, failed, or out of scope. Never collapse partial multi-agent success into “local libraries updated.”

Usage Examples

Publish this Agent Skill to the current repository. Discover its conventions,
write contract tests first, validate and review the current head, then merge,
release, verify installer discovery and provenance, and report any indexing lag.
Do not touch any other repository, private plugin, marketplace, website, mirror,
sidecar, canonical/generated copy, or local-global installation unless I
explicitly name it.

Publish this skill to the current public pack and also update the private plugin
repository I named. Treat those as separate targets, preview both scopes, verify
each release independently, and do not infer any additional mirror or sidecar.

Pitfalls

• Owner assumed from environment: working credentials do not select a target.
• Merge called release: prove the tag/deploy/catalog and install path.
• Branch copy called publication: installer discovery must read the merged source, not an indexed feature branch or cache.
• Silent external propagation: mirrors, websites, private plugins, sidecars, and local-global installations require explicit user mention.
• Root SKILL.md: some installers stop discovery there; follow the target's actual multi-skill layout.
• Description drift: package README/catalog copy must match frontmatter where the target enforces it.
• README/changelog treated as cleanup: catalogue README, human release notes, and actionable update guidance are release artifacts, not optional follow-up.
• Review of stale head: only current-head evidence satisfies the gate.
• Local copy used as proof: verify published source and isolated install.
• One plane called all planes: global, project, native-plugin, copied, symlinked, manual/upload, remote, and unsupported clients have independent freshness and completion states.
• Index cache ambiguity: report the authoritative source separately from delayed third-party indexes.

Verification

• Primary repository, owner, branch, layout, and release target were discovered.
• Tests failed before authoring and pass after implementation.
• Frontmatter, links, carried files, catalog, generators, and full checks pass.
• Repository/catalogue README lists the skill and exact install/update path.
• Human release notes explain outcomes, compatibility, and who should update.
• Published update guidance encourages adoption without mutating unrequested local targets.
• Required review is clean for the exact current head.
• Merge, release, and deployment/indexing states are reported separately.
• Main-branch source and release were read back.
• CLI discovery and isolated install report exact skill identity and provenance.
• Every explicitly requested local plane was inventoried before mutation.
• A deduplicated target manifest was presented before every local write.
• Managed updates preserved scope, source, agent set, and copy/symlink form.
• Upstream-missing skills are removal candidates requiring separate destructive confirmation, not ordinary update deletions.
• Without a comparable authoritative version/ref/digest, freshness is unknown, never inferred from command success or timestamps.
• Native, manual, remote, and unsupported channels have independent outcomes.
• Installed bytes/version/namespace were read back and affected runtimes were restarted or reloaded where required.
• Every user-mentioned external target has an independent verified state.
• No unmentioned private, external, mirror, website, sidecar, or local-global target was modified.