Progressive Disclosure is the core design of the skill ecosystem, loading in three stages, fully aligned between the official docs and the standard spec.
The three loading stages
- Level 1 metadata: at startup the name + description of every installed skill is injected into the system prompt, about 100 tokens each. The model knows each skill exists and when to use it without loading the body, so many skills can be installed without bloating context.
- Level 2 instructions: when a task matches a skill's description, the agent reads the full SKILL.md body into context.
- Level 3 resources: bundled files in scripts / references / assets are read or executed only as needed.
How Claude Code loads them: Claude Code discovers skills by scanning three layers of directories — global ~/.claude/skills/, project .claude/skills/, and plugin directories; newly added skills require a restart to be picked up. This is the landing point when you install / deploy a skill into a specific agent.
OpenAI's adoption: in 2026 OpenAI began adopting the same format — skills arrived in ChatGPT and the Codex CLI, and can be used directly in the OpenAI API via the shell tool. OpenAI's own docs describe a skill as a prompt stored as a Markdown file, often bundled with resources and scripts.
Description is the retrieval key: since the model matches tasks against descriptions, their length and precision directly determine retrieval quality. OpenAI's official GPT-6 Astra guidance states plainly that when too many skills are installed, Codex truncates descriptions to fit them in, so the model "sees less and picks worse." This points to the core tension in skill management — quantity vs. retrieval precision.
Fragmented installation and distribution: each agent has its own directory convention — Cursor uses ~/.cursor/skills, Claude Code ~/.claude/skills, Trae ~/.trae/skills, OpenCode ~/.config/opencode/skills, and so on; meanwhile the community is pushing for a generic .agents/skills-style directory. Combined with "no central registry, spread by copying folders," the early ecosystem is highly fragmented.
Sources · 参考来源