Claude Skills explained: a library of instructions, tools and plugins
Claude Skills architecture: real directories, mirrors and client adapters
Follow a skill from its authoring folder to a marketplace or agent-specific installation
What you will learn
- Start with the source package
- Trace distribution metadata
- Keep the trust boundary visible
Before you start
- A disposable project
- A pinned repository revision
- One supported agent client
Turn a catalogue entry into a measured, reversible team decision
Key takeaways
- The mirror is a distribution surface, not the canonical authoring folder.
- Plugin metadata and installer code have different responsibilities.
- Agent permissions still govern execution.
Start with the source package
A domain directory contains the authored SKILL.md and, where needed, scripts and references. The example agent-harness skill illustrates a workflow contract with supporting material; it is not a runtime service.
The repository also exposes plugin metadata and mirrored agent directories. On Windows, those mirrors may be Git symlinks, which explains why inspecting a copied SKILL.md is more useful than counting directory names.
Trace distribution metadata
The Claude marketplace JSON groups plugins and points at their source directories. Codex has an index and a mirror tree; its installer selects entries from that tree, follows links and copies the selected package into a client directory.
The universal and conversion scripts target other tool formats. A converted rule may preserve words but not activation semantics or script permissions, so the adapter itself becomes part of the artifact to test.
Keep the trust boundary visible
SKILL.md is input to an agent, while bundled tools are code the agent or operator may execute. A marketplace listing does not sandbox either one. Client permissions, filesystem scope and human approval remain outside the skill package.
This is a source-map of the pinned repository, not a claim that every client implementation loads all packages the same way. Follow one real skill through one real client before scaling the design.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Locate a real domain skill directory.
- 2
Trace its marketplace or mirror entry to the install destination.
- 3
Test activation and bundled scripts in one client.
Copy-ready example
real skill directory -> marketplace metadata
real directory -> mirror/index -> Codex copy
real directory -> conversion -> client-specific ruleFrequently asked questions
Is SKILL.md the whole package?
Sometimes, but a skill may also rely on scripts, templates or references. Copy and review the whole selected package.
Does conversion guarantee the same behavior in Cursor and Codex?
No. Format conversion alone does not prove equivalent activation or permissions.
Sources
- Claude Skills / README.mdSource checked 2026-10-04
- Claude Skills / .claude-plugin/marketplace.jsonSource checked 2026-10-04
- Claude Skills / scripts/codex-install.shSource checked 2026-10-04
- Claude Skills / scripts/convert.shSource checked 2026-10-04
- Claude Skills / scripts/install.shSource checked 2026-10-04
- Claude Skills / engineering/agent-harness/skills/agent-harness/SKILL.mdSource checked 2026-10-04