Agent Skills

The skill folder

Everything a skill needs sits in one folder, named after the skill and placed where your agent looks for skills.


What goes in it

PartWhat it holds
SKILL.mdRequired, at the top of the folder.
scripts/Code the agent can run, such as a Python or shell script the instructions call.
references/Longer documents the agent reads only when the instructions send it there.
assets/Templates, images, fonts and data the skill uses as they are.

Only SKILL.md is required, and the folder names are a convention, not a rule: what matters is that SKILL.md links to each file the agent needs.

  • Leave out build clutter such as __pycache__/, node_modules/, a top-level evals/ folder, .DS_Store and .pyc files. Anthropic’s packaging script leaves them out too.
  • Replace each symbolic link, a shortcut to a file elsewhere, with a copy of the file. A link can point outside the skill, and it can break when the skill is zipped, copied or uploaded.

Its name

Name the folder exactly as the name field in its SKILL.md. Cursor, VS Code, OpenCode and Roo Code expect the two to match, and the Claude apps refuse a zip whose folder is named differently. Claude Code reserves two folder names, synced and anthropic-skills, so don’t use either.


Where it goes

Put the folder in your agent’s skills folder: the project one, for that project only, or the one in your home folder (~), for all your projects.

These are the folders the install steps on qai.io/skills copy into:

AgentThis projectAll your projects
Claude Code.claude/skills/~/.claude/skills/
Codex.agents/skills/~/.agents/skills/
Cursor.cursor/skills/~/.cursor/skills/
GitHub Copilot and VS Code.github/skills/~/.copilot/skills/
Gemini CLI.gemini/skills/~/.gemini/skills/

Each agent reads other folders as well: Cursor also loads the Claude Code and Codex folders, and most agents read .agents/skills in a project. Agents lists every folder for every agent we list.

Put each skill directly inside the skills folder, one level down. VS Code, Zed and Claude Managed Agents don’t look deeper, so a skill at .claude/skills/group/my-skill/ isn’t found.


Zipping it for an upload

The Claude apps and OpenAI’s Skills API take a skill as a zip. Zip the folder itself, so the zip opens to the folder with SKILL.md inside it:

cd skills
zip -r pdf-forms.zip pdf-forms
WhereWhat it takes
Claude apps and APIA zip that opens to one folder named exactly as the skill’s name field, with SKILL.md inside. The Claude API takes up to 30 MB of files in all, counted unzipped.
OpenAI Skills APIOne SKILL.md and one top-level folder per skill, up to 500 files, 25 MB per file and 50 MB zipped.

Skills inside skills

A SKILL.md in a subfolder makes that subfolder a skill of its own. Copying the outer folder copies the inner skill with it, so on qai.io/skills a skill whose folder holds a skill we don’t list gets no install command.