Agent skills: how SKILL.md works across coding agents

Agent skills are reusable instructions that a coding agent loads for a particular task. Each skill is a directory with a SKILL.md file: YAML frontmatter with a name and description, followed by Markdown instructions and optional scripts, references and assets.

The Agent Skills open standard defines this package format. Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode support skills, but they differ in discovery paths, invocation and permissions. A shared SKILL.md is a starting point for portability; test it in each agent your team uses.

What an agent skill is

A skill is a directory. The only required file is SKILL.md:

release-notes/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs the agent reads when needed
└── assets/           # optional: templates, schemas, data files

release-notes/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs the agent reads when needed
└── assets/           # optional: templates, schemas, data files

release-notes/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs the agent reads when needed
└── assets/           # optional: templates, schemas, data files

SKILL.md starts with YAML frontmatter. The spec requires two fields:

• name: 1 to 64 characters, lowercase letters, numbers and single hyphens, and it must match the folder name.

• description: 1 to 1,024 characters that say what the skill does and when to use it.

Optional fields in the standard are license, compatibility, metadata and an experimental allowed-tools. Everything after the frontmatter is free-form Markdown: steps, examples, edge cases, links to files in references/, commands that call scripts/.

The file is SKILL.md. People also search for "skill.md" and "skills.md", but the spec, and every agent covered here, names the file SKILL.md, one per skill folder. A root-level skills.md is not the standard skill entry point; use a separate folder containing SKILL.md.

The description helps the agent decide when the skill applies. Name the task, expected inputs and trigger phrases. A focused description such as "Draft release notes from Git commits when the user asks for a changelog" gives it more useful context than "Helps with writing."

How agent skills load with progressive disclosure

Agents load skills in three stages, which the spec calls progressive disclosure:

This keeps the initial skill list smaller than loading every instruction file at startup. It still uses context, and clients can shorten or omit descriptions when many skills are installed. Put the task and trigger phrases first.

The standard recommends keeping SKILL.md under 500 lines and moving detail into referenced files. OpenAI documents a separate budget for Codex’s initial skill list; changing that budget does not shorten the full file when a skill is selected.

A portable SKILL.md example

Start with the standard fields and instructions that do not depend on a particular agent’s tools. This one writes release notes from the commits since the last tag:

---
name: release-notes
description: Drafts release notes from git commits since the last tag, grouped into Features, Fixes and Breaking changes. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`.
2. List commits since it: `git log <tag>..HEAD --oneline --no-merges`.
3. Group each commit under Features, Fixes or Breaking changes.
   Put anything that changes a public API, config key or CLI flag under Breaking changes.
4. Write one line per change in plain language. Link the PR number if the commit has one.
5. If there are no commits since the tag, say so and stop.

See [references/style.md](references/style.md) for the team's tone and formatting rules.

---
name: release-notes
description: Drafts release notes from git commits since the last tag, grouped into Features, Fixes and Breaking changes. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`.
2. List commits since it: `git log <tag>..HEAD --oneline --no-merges`.
3. Group each commit under Features, Fixes or Breaking changes.
   Put anything that changes a public API, config key or CLI flag under Breaking changes.
4. Write one line per change in plain language. Link the PR number if the commit has one.
5. If there are no commits since the tag, say so and stop.

See [references/style.md](references/style.md) for the team's tone and formatting rules.

---
name: release-notes
description: Drafts release notes from git commits since the last tag, grouped into Features, Fixes and Breaking changes. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`.
2. List commits since it: `git log <tag>..HEAD --oneline --no-merges`.
3. Group each commit under Features, Fixes or Breaking changes.
   Put anything that changes a public API, config key or CLI flag under Breaking changes.
4. Write one line per change in plain language. Link the PR number if the commit has one.
5. If there are no commits since the tag, say so and stop.

See [references/style.md](references/style.md) for the team's tone and formatting rules.

Save it as release-notes/SKILL.md inside a skills directory your agent reads (next section). This avoids common portability problems:

• The folder name and name match the standard’s naming rules.

• It uses no agent-specific frontmatter. Claude Code supports extra fields such as disable-model-invocation and context, and Cursor adds paths, but other agents may ignore them.

• The description names the triggers ("release notes", "changelog entry") so the agent can match a plain request.

You can check the package with the standard’s reference validator: skills-ref validate ./release-notes. The example also refers to references/style.md: create that file with your team’s writing rules, or remove the reference. It needs Git, a repository with a tag, and permission to read its history.

For a review workflow, use the copyable code review SKILL.md or install cubic’s code review skills. They illustrate how instructions can coordinate a CLI review and codebase context without putting every step in your prompt.

Where coding agents look for skills

The paths below are documented by each agent as of October 2026. These are local project and user locations; plugin packages, enterprise settings and remote agents can add other discovery rules.

The agents can select skills from a matching request, subject to their invocation and permission settings. Discovery does not guarantee activation. Confirm that the skill appears in the agent’s skill list, then try both an explicit invocation and a natural-language request.

What changes between agents

• Claude Code: Uses .claude/skills/ for project skills and supports symlinked skill folders. Its extra frontmatter can control automatic invocation or run a skill in a separate context. See our Claude Code skills guide for writing and placing one, or the best Claude Code skills for workflows to install.

• Codex: Scans .agents/skills/ from the current directory up to the repository root, plus user, admin and bundled locations. Its optional agents/openai.yaml can set invocation policy and tool dependencies. The Codex skills guide covers installation and testing.

• Cursor: Also reads Claude and Codex compatibility folders. Local user skills are not automatically available in every remote environment; commit team skills to the project and check the target environment. See how Cursor skills work.

• Copilot, Gemini CLI and OpenCode: Share some discovery paths, but expose different invocation and permission controls. Check the installed client’s skill list and permissions rather than assuming one client’s settings carry over.

How to share one set of skills across agents

~/.agents/skills/ (personal) and .agents/skills/ (project) are read by Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Claude Code's skills docs don't list .agents/skills; it reads .claude/skills/ and ~/.claude/skills/.

One way to share the files across these local agents:

1. Keep project skills in .agents/skills/<name>/SKILL.md and commit them.

2. For Claude Code, add a symlink per skill: .claude/skills/<name> pointing at ../../.agents/skills/<name>. Claude Code's docs say a skill folder in the personal or project location can be a symlink and that it loads the skill once even when several locations point at the same target.

3. Do the same at user level, from ~/.claude/skills/<name> to ~/.agents/skills/<name>, for personal skills.

4. Keep agent-specific frontmatter out of shared skills, or accept that other agents ignore it.

Cursor, Copilot in VS Code and OpenCode also read .claude/skills/ directly, so if your team only uses those plus Claude Code, a single .claude/skills/ folder is enough. Codex and Gemini CLI are the two that need .agents/skills/ or their own folder.

Keep a short compatibility check for every agent: does the skill appear, does a representative request select it, can it read its references, and are its scripts and tools available? Try one request that should not trigger it too. A valid package can still fail because of missing dependencies, permissions or a different execution environment.

Agent skills vs MCP vs AGENTS.md vs subagents

These four get mixed up because they all change what an agent knows or can do. They load at different times and solve different problems.

Use AGENTS.md or CLAUDE.md for project guidance the agent should have before working: build commands, conventions and repository layout. Use a skill for a reusable procedure that only some tasks need. Use a subagent when a delegated task benefits from a separate context. Exact file loading and delegation behavior depends on the client; the CLAUDE.md and AGENTS.md guide explains how to share project instructions.

Skills and MCP also combine. A skill can tell the agent which MCP tool to call and what to do with the result, so the skill carries the procedure and the server carries the connection.

For example, cubic’s skills define the review workflow, while cubic’s MCP server provides access to review findings and codebase context. Installing a skill does not authenticate the server or grant access to repositories.

Read a skill before you install it

Skills can contain executable scripts and instructions to use external tools. Review them as you would other software before letting an agent use them with your accounts and filesystem.

• Read the package. Inspect SKILL.md, referenced files and scripts. Look for credential access, network calls and actions unrelated to the stated task.

• Check dependencies. Confirm which commands, packages and MCP servers the skill expects, where they run and what account they use. Installing instructions does not install or authorize every dependency.

• Inspect permission settings. Fields such as allowed-tools are not portable security boundaries. Their meaning and enforcement depend on the agent.

• Pin and test the version. Start from a commit or release you reviewed, try it on a small task, and inspect changes before you commit or publish. Recheck the package when updating it.

Find a skill for your workflow

Start with one recurring task, then choose the guide that matches your agent or review workflow:

• Best Claude Code skills: a focused set of skills for writing, testing and reviewing code.

• Codex skills: installation, discovery paths and the built-in creator and installer.

• Cursor skills: skill paths, invocation and how skills relate to rules.

• Code review skill: a copyable review procedure for local changes before you push.

cubic publishes its skills in mrge-io/skills. To install them for detected supported agents, run:

npx @cubic-plugin/cubic-plugin install --skills-only

npx @cubic-plugin/cubic-plugin install --skills-only

npx @cubic-plugin/cubic-plugin install --skills-only

The installer supports Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Droid and Pi; --to universal targets agents that read ~/.agents/skills. Local reviews require the cubic CLI and sign-in; codebase context requires a separate MCP connection. Follow the cubic skills setup guide to install the tools your workflow needs.

Common questions about agent skills

Do agent skills depend on the model?

The package format belongs to the agent client, not one model. A client can expose the same skill to different models, but selection and execution quality can change. Test the workflow with the client, model and permissions your team uses.

Can a skill run code?

A skill can include scripts and instruct the agent to run them. The available languages, network access and approval rules depend on the execution environment. Check those requirements before installing a script-backed skill.

How do I know a skill is working?

Check that the agent discovers it, invoke it explicitly, and inspect the resulting commands and output. Then test a natural-language request that should activate it and one that should not. Validate the work itself; a successful invocation does not prove the output is correct.