This page describes the overall architecture of the skills system: how skills are structured, how Claude discovers and loads them at runtime, and how the plugin registry connects skill folders to Claude surfaces. For the exact format of the SKILL.md file, see SKILL.md Format Specification. For how skills reach users across Claude Code, Claude.ai, and the API, see Platform Integration.
A skill is a self-contained directory that contains a SKILL.md file. The SKILL.md file is the only required artifact. It carries two things:
description field) and what to call it (via the name field).Optional supporting files (Python scripts, sub-agent prompts, static assets) may live alongside SKILL.md in subdirectories, but they are invoked only when the SKILL.md body directs Claude to call them.
Sources: README.md1-18 README.md61-88
The repository organizes all skill folders under skills/, each as a flat peer directory. There is no nesting between skills.
Diagram: Repository-to-Skill Mapping
Sources: .claude-plugin/marketplace.json1-45 README.md24-27
The file .claude-plugin/marketplace.json1-45 is the single registry that groups skills into installable bundles. It defines two plugins:
| Plugin name | strict | Skills included |
|---|---|---|
document-skills | false | xlsx, docx, pptx, pdf |
example-skills | false | algorithmic-art, brand-guidelines, canvas-design, doc-coauthoring, frontend-design, internal-comms, mcp-builder, skill-creator, slack-gif-creator, theme-factory, web-artifacts-builder, webapp-testing |
Each entry in the skills array is a path relative to the repo root (e.g., "./skills/xlsx"). The source field ("./") anchors that resolution to the repository root.
The marketplace itself is registered under the name anthropic-agent-skills .claude-plugin/marketplace.json2 which is the handle used in the /plugin install command (/plugin install document-skills@anthropic-agent-skills).
Sources: .claude-plugin/marketplace.json1-45
Skills are loaded dynamically at runtime by matching the user's natural language request against the description field in each skill's SKILL.md frontmatter. No code orchestrates this: the description itself is the trigger specification.
Diagram: Runtime Skill Selection Flow
Sources: README.md49 README.md4
Every skill folder follows the same internal structure. Only SKILL.md is required; all other subdirectories are optional and present only when the skill's instructions need them.
Diagram: Skill Folder Internal Structure (using skills/docx as example)
Sources: README.md61-88
The architecture enforces several constraints that allow skills to be developed and installed independently:
No inter-skill dependencies. Each skill folder is fully self-contained. A skill's scripts/ directory carries all the Python utilities that skill needs; it does not reference files from sibling skill folders.
Flat skill registry. The skills array in marketplace.json is a plain list of paths. Adding a new skill requires only: (a) creating a new folder with a valid SKILL.md, and (b) appending its path to the appropriate plugin's skills array.
Description-driven dispatch. Because trigger logic lives in the description frontmatter field (not in routing code), changing which prompts activate a skill requires editing only the skill's own SKILL.md. No central dispatcher needs updating.
Optional tooling. Scripts, agents, and assets are additive. A minimal skill (SKILL.md only, with name and description) is complete and functional.
Sources: README.md61-88 .claude-plugin/marketplace.json1-45
Diagram: Full Architecture — From Repository to Execution
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.