Build your own skill
Last reviewed October 24, 2026
A skill is a folder with a SKILL.md file in it: a name, a one-paragraph description, and instructions the agent follows. It can carry scripts, reference documents and templates alongside. The agent keeps only the name and description in mind until a task matches, then reads the rest, so a skill costs almost nothing until it is useful.
The format is an open standard (Agent Skills specification), first written by Anthropic. Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, OpenCode and Antigravity all read it, so one folder can serve all of them.
A skill, an MCP server or a plugin?
Write a skill when the agent already has the tools it needs and lacks the know-how: your release process, your house style, the right order to run three commands in. Build an MCP server when it needs access it does not have, like an API with its own login. Package a plugin when you want to ship skills together with commands, hooks or servers for one agent, installed in one step.
One snag before you start
The standard suggests a shared folder, .agents/skills/, and most agents read it. Claude Code does not: it reads .claude/skills/ (Claude Code skills). A skill meant for everyone has to be in both places, or installed by a tool that handles it. The port and publish steps cover both.
The six steps
- 1. Write a skill
The SKILL.md format, what loads when, a description agents act on, and where each agent looks for skills.
- 2. Test a skill
Check that it triggers when it should, stays quiet when it should not, and does better than no skill at all.
- 3. Port a skill to another agent
Move a skill between Claude Code, Codex, Gemini CLI and the rest: what carries over and what does not.
- 4. Publish a skill
The repository, a README people trust, versions, and the ways people install a skill: npx skills, plugins, marketplaces.
- 5. Make a skill safe to install
Skills run with their user's privileges: allowed-tools, bundled scripts that behave, and passing a safety scan.
- 6. Skill checklist
Findable, trustworthy, maintainable: what to check before you tell anyone about it.