How to Write Agent Skills That Work on Claude Code, Codex, and Gemini CLI

A SKILL.md file is a plain-text instruction module that gives AI coding agents reusable domain expertise. Write it once, drop it into the agent's skills directory, and it activates on demand. As of May 2026, the format runs on 19 platforms -- Claude Code, Codex CLI, Gemini CLI, Cursor, and more -- with zero modifications between them.

I have been running custom skills in Claude Code for months. The moment I tested the same file unmodified in Codex CLI and Gemini CLI and it worked identically, the approach clicked -- one set of instructions, every agent you touch.

What is a SKILL.md file?

A SKILL.md file is a structured instruction document stored in a named folder inside your agent's skills directory. It has two parts: a YAML frontmatter block at the top with name and description fields, and a markdown body with the actual instructions. The agent reads the description to decide when to load the skill, then follows the body when it does. It is the functional equivalent of a reusable playbook the agent picks up when the task fits.

Here is a minimal example -- a code review skill:

---
name: code-review
description: Review changed code for quality, security issues, and performance problems. Use when the user asks for a code review, PR review, or wants feedback on changes.
---

# Code Review

1. Run git diff to read all changed files
2. Check for security vulnerabilities: SQL injection, XSS, unvalidated input
3. Flag performance problems with specific line numbers
4. Output a summary: what works, what needs a fix, what is optional cleanup

The description field is the activation trigger. The agent pattern-matches your request against this text. "Use when the user asks for a code review" is better than just "does code review" -- explicit conditions reduce false activations and missed ones.

The format was pioneered by Anthropic for Claude Code and spread fast. On January 13, 2026, Google formalized support in its Antigravity platform. A week later, Vercel launched skills.sh as the first dedicated registry -- it hit 20,000 installs within six hours of launch. By March 2026, a data-driven analysis of 40,285 listed skills found over 490,000 skills across three major marketplaces, with an 18.5x growth rate from January to February alone.

Which platforms support the SKILL.md format in 2026?

As of May 2026, SKILL.md runs natively on at least 19 platforms including Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, GitHub Copilot, Windsurf, Aider, Kiro, and Google Antigravity. The file format is identical on every platform -- the only difference is the directory where you place the skill folder. Nothing in the SKILL.md itself needs to change between agents.

Platform	Global skills path	Project-scoped path
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex CLI	`~/.codex/skills/`	`.codex/skills/`
Gemini CLI	`~/.gemini/skills/`	`.gemini/skills/`
Cursor	`~/.cursor/skills/`	`.cursor/skills/`
Antigravity	`~/.gemini/antigravity/skills/`	`.agent/skills/`

Project-scoped paths work well for skills specific to one repo -- a deployment checklist for a particular stack, or a style guide for a specific client. Global paths are for skills you want available in every session regardless of working directory.

How do you write a SKILL.md from scratch?

A working SKILL.md takes 10-15 minutes to write. The structure is always the same: a folder named after the skill, a SKILL.md file inside it with YAML frontmatter and markdown instructions, and optionally a scripts/ directory for any shell scripts the skill calls. No special syntax beyond standard YAML and markdown. The hard part is writing a description specific enough to trigger reliably.

Step 1: Create the skill directory

mkdir -p ~/.claude/skills/my-skill
cd ~/.claude/skills/my-skill

Step 2: Write the SKILL.md

---
name: my-skill
description: [Write what this skill does and WHEN to use it. The agent matches requests against this text. Be explicit: "Use when the user asks to..." or "Activates on requests involving..."]
---

# My Skill Name

## What This Does

[One paragraph. What problem does this skill solve?]

## Steps

1. [First action -- be concrete and specific]
2. [Second action]
3. [Third action]

## Output

[What should the result look like? Format, length, headings if relevant.]

Step 3: Verify it loaded

In Claude Code, type /skills at the prompt. Your skill should appear with its name and description. In Codex CLI and Gemini CLI, skills are listed in the system context at session start. If yours is missing, double-check the path -- the most common issue is a skills/ subdirectory placed one level too deep inside the project directory.

Step 4: Test the activation trigger

Send a request that matches your description. If the skill does not activate, the description is probably too vague. Add "Use when [exact phrase]" to make the trigger explicit. Specificity beats brevity here.

One practical note before you start writing long skills: according to a HuggingFace analysis of the skills ecosystem, the average published skill is 1,900 tokens, but the top 1% exceed 100,000 tokens and can consume a model's entire context window before a single task runs. Write instructions, not documentation. Keep each skill focused on one job.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool

How do you deploy one skill to every agent at once?

Once your SKILL.md is working in one agent, deploying it to the others is a copy-paste operation. Put the same folder into each agent's global skills directory. The markdown instructions contain no platform-specific syntax, so nothing needs rewriting. You can also use the project-scoped paths to deploy a skill to a single repo without affecting your global setup.

Here is the deployment script I use:

#!/bin/bash
# deploy-skill.sh -- sync a skill to all supported agents
SKILL_NAME="${1:?Usage: ./deploy-skill.sh skill-name}"
SKILL_SRC="$HOME/.claude/skills/$SKILL_NAME"

if [ ! -d "$SKILL_SRC" ]; then
  echo "Skill not found: $SKILL_SRC"
  exit 1
fi

for TARGET in   "$HOME/.codex/skills"   "$HOME/.gemini/skills"   "$HOME/.cursor/skills"; do
  mkdir -p "$TARGET"
  cp -r "$SKILL_SRC" "$TARGET/"
  echo "Deployed $SKILL_NAME to $TARGET"
done

Run it as ./deploy-skill.sh my-skill. When you update the SKILL.md, re-run it to sync. I keep this in my dotfiles so any machine I set up gets it automatically.

If you are building skills to ship to a team or publish publicly, the VoltAgent/awesome-agent-skills repo is the structural model to follow. It has 1,000+ community skills organized for Claude Code, Codex CLI, Gemini CLI, and Cursor, with each skill folder containing a README, the SKILL.md, and activation tests verifying the trigger works correctly.

Where do you find pre-built skills worth installing?

The three main sources for agent skills in 2026 are skills.sh (Vercel's official registry, 19 supported agents), awesomeskills.dev (12,242 curated skills across 14 category collections), and GitHub repos from specific tool maintainers. The practical starting move is to install find-skills first -- a meta-skill that searches the registry from inside your agent -- which has accumulated 579,000+ installs on skills.sh.

# Install find-skills to browse the registry from inside your agent
npx skills add find-skills

# Browse the registry manually from the terminal:
npx skills find "code review"
npx skills find "deployment"
npx skills find "security audit"

Once find-skills is installed, you can ask your agent directly "find me a skill for React testing" and it will query the registry and suggest installs without switching context or opening a browser.

awesomeskills.dev is better for category browsing before committing to installs. It separates official skills (Anthropic, OpenAI, Microsoft Azure) from community contributions, and flags skills that have been independently reviewed. The Qt Company's official agent-skills repo is a good example of a verified, production-grade skill set -- built and maintained by the tool's engineering team, compatible with Claude Code, Codex, and Copilot.

What are the real risks with agent skills?

Two problems matter before you install skills from unknown sources: token bloat and security. A 2026 analysis of 40,285 publicly listed skills found 13.4% contained at least one critical-level security issue -- prompt injection attacks, malware payloads, or exposed credentials. Separately, 52% of tokens across the ecosystem are waste, and the worst skills consume a model's entire context window before any actual work starts.

On token bloat: agents load skills into context at session start. My rule is under 2,000 tokens per skill, and a hard cut on anything that reads like documentation rather than instruction. If the SKILL.md is explaining what a concept is rather than telling the agent what to do with it, cut it or move it to a reference/ subfolder that only loads on demand. The average skill in the wild is 1,900 tokens; the top 1% exceed 100,000 tokens and make the agent unusable for the rest of the session.

On security: skills can include a scripts/ folder with shell scripts that execute arbitrary code in the agent's environment. This is powerful when you control the source and dangerous otherwise. Vercel and Snyk now automatically scan skills uploaded to skills.sh for known CVEs and prompt injection patterns -- but that gate only covers the official registry. GitHub and third-party sources do not have the same protection.

My vetting checklist before installing any skill from an unknown source:

Read the full SKILL.md before installing, not just the description
Check the scripts/ folder for curl, wget, exec, or any network calls
Check the GitHub source: stars, recent commits, issue history, maintainer activity
Test in a throwaway repo before using in a production codebase
Never install a skill that asks you to run a separate setup script or export environment variables

FAQ

What is the SKILL.md format?

SKILL.md is an open standard for reusable AI agent instruction modules. Each skill is a folder containing a SKILL.md file with YAML frontmatter (name and description fields) and markdown instructions. The agent reads the description to decide when to activate the skill and follows the instructions when it does. As of May 2026, the format is supported on 19 platforms including Claude Code, Codex CLI, Gemini CLI, and Cursor, with zero modification required between platforms.

Does the same skill file work on Claude Code and Codex CLI without changes?

Yes. The SKILL.md format is identical across Claude Code, Codex CLI, Gemini CLI, Cursor, and 15 other agents. The only difference is the installation path: ~/.claude/skills/ for Claude Code, ~/.codex/skills/ for Codex CLI, ~/.gemini/skills/ for Gemini CLI. The SKILL.md content itself requires no modification between platforms -- write it once and copy the folder.

How many agent skills exist in 2026?

As of March 2026, over 490,000 skills existed across three major skill marketplaces, growing 18.5x from January to February 2026. Vercel's skills.sh registry supports 19 AI agents and hit 20,000 installs within six hours of its January 20, 2026 launch. awesomeskills.dev catalogs 12,242 curated skills across 14 collections. The find-skills meta-skill alone has accumulated 579,000+ installs.

Are agent skills safe to install?

Not automatically. A 2026 analysis of 40,285 publicly listed skills found 13.4% contained critical security issues including prompt injection, malware, and exposed credentials. Skills from verified sources on skills.sh -- which uses Snyk for automated scanning -- carry lower risk than arbitrary GitHub repos. Always read the SKILL.md and scripts/ directory before enabling a skill from an unknown author, and test in a sandbox first.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool

Agent-skills

How to Write Agent Skills That Work on Claude Code, Codex, and Gemini CLI