Skip to main content
A skill is a reusable package of instructions and supporting files for one job. Agent Registry keeps one record for each skill: its package, the workspace that owns it, every version, and the usage evidence from runs that used it.

​
What skills contain

A package starts with SKILL.md, the skill’s core instructions. It can also hold references, templates, examples, and scripts. An agent that uses the skill receives the whole package, so a template or script can change what the skill sends, reads, or writes. The skill page shows the package size and identifies each file’s content, so you can tell what belongs to each version. A skill name is unique within its workspace. The same name can exist in another workspace.

​
How skills enter Agent Registry

Skills reach the registry in several ways:
  • Desktop import: the desktop app imports the skills installed for Claude Code and Codex on your computer into your personal workspace.
  • GitHub SkillSync: a repository path maps to a skill. Approved changes on the protected branch publish new versions, and GitHub stays the source of truth.
  • Desktop bulk upload, CLI, and HTTP API: publish a package directly into one workspace.
The skill’s source label records where it came from. A Git-backed version also records its repository, commit, path, and contributors.

​
Versions and releases

Every save creates a version. A version captures the skill’s exact files, so you can see or restore what the skill contained at any point. A version reaches people only once it is released, so a skill can change without changing what your team already uses. Each workspace sets a release policy:
  • Auto release: each saved version is released once its checks pass.
  • Manual release: the skill’s owner or a workspace admin releases a version when it is ready.
A new version is checked before it can be released. It shows Checking while in review, or Blocked if the check refused it. The version people get now is marked Live. Only the skill’s owner or a workspace admin can release, roll back to the previous release, or withdraw a release. Restoring an earlier version copies its files into a new version and keeps the history.

​
How usage is measured

Skill usage comes from traces. When an agent runs, its trace records the skills involved, and the registry matches each one to the skill version with the same content. You do not record a separate usage event. Each match states its confidence:
  • Exact match: the content matches one version exactly.
  • SKILL.md match: the instructions match, but supporting files may differ.
  • Name match: only the name matched.
Use exact matches when you compare versions.

​
Skill page

Each skill page has the tabs Overview, Source, Releases, Relationships, Usage, and Security. Source holds the package, its provenance, and the version picker. Usage lists trace-backed runs, models, tools, people, and versions. The Security tab is a preview of planned findings and trends. It is not a scan result, so review Source before you adopt a skill.

​
Example

A team keeps meeting-notes-to-actions in its shared workspace with Manual release. An author saves version 2.3.0, and 2.2.0 stays live while the team reviews the change. After release, the skill’s Usage tab shows which runs used 2.2.0 and which used 2.3.0. The team compares each trace with the exact source that was live for it.

​
What skills do not tell you

  • Usage is not quality. A high run count shows reuse, not correct results. Use evals to measure quality.
  • Empty usage is not proof of no use. It means the registry has no attributable trace for the skill.
  • A name does not identify a version. Do not infer a version from a skill’s display name.

​
See also