Agent Skills
How agents differ
One SKILL.md can load in one agent and fail in another. These are the differences that decide it.
Five ways to read a skill
The format check on qai.io/skills reads every SKILL.md five ways, and says for each whether the skill passes, passes with warnings or fails:
| Read as | How it reads a skill |
|---|---|
| Agent Skills spec | The format our Agent Skills docs set out, held to the strictest version of each rule among the agents we check. |
| Claude Code | Claude Code reads its own extra fields, ignores unknown ones, and still loads a skill whose frontmatter is broken, without its fields. |
| Claude apps & API upload | Uploading to claude.ai or the Claude API, or packaging with Anthropic's script, accepts only the six spec fields and stops on anything else. |
| OpenAI (Codex & API) | Codex finds SKILL.md by its exact name and needs a description; OpenAI's Skills API checks the frontmatter against the spec and caps uploads. |
| VS Code & Copilot | VS Code reads skills one folder below .github/skills, .claude/skills or .agents/skills and falls back to the folder name when the name is missing or differs; GitHub's Copilot docs require the exact name SKILL.md. |
A skill fails on any error and passes with warnings on any warning. How Skills works lists every rule and the level it reaches for each.
Where they differ most
| When | Claude Code | Claude apps and API upload | Codex and OpenAI | VS Code and Copilot |
|---|---|---|---|---|
| Fields it can’t read | Loads the skill with no fields | Refuses the file | Skips the skill | Reads them leniently |
| No description | Uses the first line of the instructions | Refuses the file | Skips the skill | Lists the skill with nothing to match |
| Name differs from the folder | Answers to both | Refuses the file | Accepts it | Uses the folder’s name |
| Fields outside the six | Reads its own, ignores the rest | Refuses the file | Codex ignores them | Reads its own, ignores the rest |
Claude Code is the most forgiving: it loads a skill even when its fields can’t be read, so a skill that works there can still fail elsewhere. Validate a SKILL.md checks yours all five ways.
Fields some agents add
Besides the six fields SKILL.md defines, these agents read fields of their own. Others ignore them, and the Claude apps upload refuses any of them.
| Agent | Its own fields |
|---|---|
| Claude Code | when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, background, hooks, paths, shell |
| Cursor | paths, globs, disable-model-invocation, icon, color |
| VS Code | argument-hint, user-invocable, disable-model-invocation, context |
| Zed | disable-model-invocation |
| Factory Droid | enabled, user-invocable, disable-model-invocation, version |
| Amp | mcpServers |
| OpenClaw | homepage, user-invocable, disable-model-invocation, command-dispatch, command-tool, command-arg-mode |
| Hermes Agent | version, author, platforms, required_environment_variables, required_credential_files |
| Grok Build | when-to-use, when_to_use, paths, argument-hint, user-invocable |
Codex takes its display name, icon and whether to pick the skill on its own from an agents/openai.yaml file beside SKILL.md, not from these fields.
The agents we list
Claude Code, Claude apps, Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenCode, Goose, Windsurf (Devin Desktop), Zed, Roo Code, Factory Droid, Junie, Amp, Kiro, Antigravity, Cline, Kilo Code, OpenClaw, Hermes Agent, Grok Build and Muse Code all load skill folders. Agents has the folders each one reads and what to watch for in each, from its maker’s own docs.
These have a setup page of their own, with every folder, field and caveat:
These come up alongside them, but don’t load SKILL.md folders:
| Agent | What it does instead |
|---|---|
| Grok Bot (SpaceXSI) | Keeps its skills in a library of its own, made by asking it or installed from Connect apps; its docs describe no SKILL.md folders. Its maker’s coding agent, Grok Build, reads them. |
| Muse (Meta) | Takes on new abilities through connectors that Meta reviews; its docs describe no way to add a SKILL.md skill. Meta’s coding agent, Muse Code, reads them. |
| OpenBot (CopilotKit) | Keeps skills of its own, written, recorded or proposed in the app or shipped in a skills.yaml file; its docs describe no way to install a SKILL.md folder. |
| OpenShell (NVIDIA) | A sandbox that runs other agents, such as OpenCode, rather than an agent; it loads no skills itself, so install them in the agent you run inside it. |
Install a skill in your agent
- On any skill’s page on qai.io/skills, sign in and pick your agent in the install card. Its steps copy the skill into the folder your agent reads, at the commit we checked unless a step says otherwise.
- Some agents have a tab of their own. The others read a folder another tab installs to, or need the folder copied by hand; their page in Agents says which.
- Pick your agent once on Agents and every skill page opens on its steps.