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
| Part | What it holds |
|---|---|
| SKILL.md | Required, 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:
| Agent | This project | All 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| Where | What it takes |
|---|---|
| Claude apps and API | A 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 API | One 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.