Skip to content

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. 1. Write a skill

    The SKILL.md format, what loads when, a description agents act on, and where each agent looks for skills.

  2. 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. 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. 4. Publish a skill

    The repository, a README people trust, versions, and the ways people install a skill: npx skills, plugins, marketplaces.

  5. 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. 6. Skill checklist

    Findable, trustworthy, maintainable: what to check before you tell anyone about it.