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 asHow it reads a skill
Agent Skills specThe format our Agent Skills docs set out, held to the strictest version of each rule among the agents we check.
Claude CodeClaude Code reads its own extra fields, ignores unknown ones, and still loads a skill whose frontmatter is broken, without its fields.
Claude apps & API uploadUploading 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 & CopilotVS 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

WhenClaude CodeClaude apps and API uploadCodex and OpenAIVS Code and Copilot
Fields it can’t readLoads the skill with no fieldsRefuses the fileSkips the skillReads them leniently
No descriptionUses the first line of the instructionsRefuses the fileSkips the skillLists the skill with nothing to match
Name differs from the folderAnswers to bothRefuses the fileAccepts itUses the folder’s name
Fields outside the sixReads its own, ignores the restRefuses the fileCodex ignores themReads 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.

AgentIts own fields
Claude Codewhen_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, background, hooks, paths, shell
Cursorpaths, globs, disable-model-invocation, icon, color
VS Codeargument-hint, user-invocable, disable-model-invocation, context
Zeddisable-model-invocation
Factory Droidenabled, user-invocable, disable-model-invocation, version
AmpmcpServers
OpenClawhomepage, user-invocable, disable-model-invocation, command-dispatch, command-tool, command-arg-mode
Hermes Agentversion, author, platforms, required_environment_variables, required_credential_files
Grok Buildwhen-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:

AgentWhat 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.