SKILL.md is the required file in an Agent Skills folder. Its YAML frontmatter gives the skill a name and a description, and its Markdown body holds the instructions. Agents read only the name and description at startup, then load the body when a task matches. The format is portable, but each agent scans different folders.
The format was originally developed by Anthropic and released as an open standard. Claude Code, OpenAI Codex, Cursor and GitHub Copilot now document support for it. That makes one skill reusable across tools, as long as you stay inside the shared spec and put the file where each client looks.
This guide covers the fields, the folder layout and how skills load into context. It then shows where each major client looks, with lessons from auditing the skills our own team uses. For how teams distribute and govern skills at scale, see what a private skill marketplace is.
Last verified: October 25, 2026, against the Agent Skills specification and each vendor’s documentation linked below.
Key Takeaways
- Only
nameanddescriptionare required. The name must match the folder, and the description should say what the skill does and when to use it. - Spec fields are portable. Fields such as
argument-hintordisable-model-invocationare vendor extensions that other clients may ignore. - Claude Code reads
.claude/skills, Codex reads.agents/skills, and Cursor and GitHub Copilot read both. No single project folder reaches all four. - Treat a skill like software you install. Scripts and instructions both run with the agent’s permissions.
Disclosure: ASCENDING builds Jarvis Registry, which includes a Skill Gateway for distributing skills. The format guidance applies to any tool; Jarvis product scope and client compatibility were reviewed October 28, 2026.
What goes in a SKILL.md file?
A SKILL.md file has two parts: frontmatter between --- lines and a Markdown body. Here’s a minimal, valid example with notes.
---
name: release-notes # required; must match the folder name
description: Drafts release notes from merged pull requests. Use when the user asks for release notes or a changelog.
license: Apache-2.0 # optional
metadata: # optional; string keys and values
owner: platform-team
version: "1.2"
---
# Release notes
1. List pull requests merged since the last tag.
2. Group them by feature, fix and breaking change.
3. Follow the template in assets/release-template.md.
The body has no required format. The specification suggests step-by-step instructions, input and output examples, and common edge cases. The agent loads the whole body once it decides to use the skill, so keep it focused.
Which frontmatter fields does the spec define?
The Agent Skills specification defines six fields. Two are required.
| Field | Required | Limit | Notes |
|---|---|---|---|
name | Yes | 1 to 64 characters | Lowercase letters, numbers and hyphens; no leading, trailing or double hyphens; must match the folder name |
description | Yes | 1 to 1,024 characters | Say what the skill does and when to use it |
license | No | None stated | A license name or a bundled license file |
compatibility | No | 1 to 500 characters | Environment needs, such as required tools or network access |
metadata | No | None stated | A map of string keys to string values |
allowed-tools | No | None stated | Pre-approved tools; marked experimental, and support varies |
Some products add stricter rules. For skills used with the Claude API, Anthropic’s docs say the name can’t contain XML tags or the reserved words “anthropic” and “claude”. The description can’t contain XML tags either.
Vendor extension fields
Vendor extension fields are frontmatter keys that one product reads and the spec doesn’t define. Claude Code adds argument-hint, disable-model-invocation, user-invocable, context, hooks, paths and others. Cursor adds paths, disable-model-invocation, icon and color. Codex keeps its extras in a separate agents/openai.yaml file instead of the frontmatter.
These fields are useful inside one tool. Just don’t count on them elsewhere. A skill that relies on disable-model-invocation to stay manual in Claude Code may be picked up automatically by a client that ignores the field.
How should you lay out the skill folder?
A skill is a folder named after the skill. SKILL.md is the only required file; three optional folders hold everything else.

scripts/holds code the agent can run, such as a validation or extraction script.references/holds extra documentation the agent reads when needed.assets/holds templates, images and data files.
The spec recommends keeping SKILL.md under 500 lines and moving detail into separate files. It also asks for file references one level deep from SKILL.md, with relative paths, so agents don’t follow long chains.
How does a skill load into context?
Progressive disclosure is the loading model that keeps skills cheap until they’re needed. The specification describes three stages:
- Metadata, about 100 tokens per skill. The name and description load at startup for every installed skill.
- Instructions, under 5,000 tokens recommended. The full SKILL.md body loads when the skill is activated.
- Resources, as needed. Files in
scripts/,references/orassets/load only when the instructions call for them.
Clients also cap the startup listing. Claude Code cuts each skill’s description and when_to_use text at 1,536 characters (Claude Code docs). Codex budgets 8,000 characters or 2% of the context window for its skill list by default (Codex docs). Put the trigger words early in the description so a cut doesn’t remove them.
Where does each agent look for skills?
Each client documents its own folders. We checked each vendor’s docs on October 25, 2026.
| Client | Project folders | Personal folders | How to call a skill | Source |
|---|---|---|---|---|
| Claude Code | .claude/skills (also nested and plugin skills) | ~/.claude/skills | Automatic, or /skill-name | Claude Code docs |
| OpenAI Codex | .agents/skills, from the working folder up to the repo root | ~/.agents/skills; admins can use /etc/codex/skills | Automatic, $skill-name or /skills | Codex docs |
| Cursor | .agents/skills, .cursor/skills, plus .claude/skills and .codex/skills for compatibility | ~/.agents/skills, ~/.cursor/skills and the Claude and Codex equivalents | Automatic, or / in Agent chat | Cursor docs |
| GitHub Copilot | .github/skills, .claude/skills, .agents/skills | ~/.copilot/skills, ~/.agents/skills | Loaded when relevant | GitHub docs |

The table shows a gap. .claude/skills reaches Claude Code, Cursor and Copilot, but Codex doesn’t list it. .agents/skills reaches Codex, Cursor and Copilot, but Claude Code’s docs don’t list it. A team using all four tools needs one source copy synced into both folders. A copy step, a symlink or a distribution tool can do it. Test symlinks on Windows before you rely on them.
Does Codex read SKILL.md the same way as Claude Code?
For the format, mostly. Codex and Claude Code both read a SKILL.md file with the spec’s name and description fields, so the instructions travel. Two things differ. Codex looks in .agents/skills rather than .claude/skills, and Codex keeps its extra settings in an agents/openai.yaml file instead of the frontmatter. Fields that only Claude Code defines may be ignored by Codex, so keep them out of any skill you share.
Loading behavior is the part to test rather than assume. The vendor docs linked above describe discovery and activation as of October 25, 2026, and these can change by version. Run the same skill in each client version your team uses, and confirm it is found and activated as expected.
Why does a downloaded skill not appear in the client?
A download only places files on disk. A client lists a skill only from the folders it scans, under the scope it was installed into. When a developer has the package but the assistant does not show it, check these in order:
- Folder. The
SKILL.mdsits in a folder from the client table above, under the scope you used: personal or project. - Name. The
namematches the folder name, as the spec requires. - Mode. The CLI mode matches the client:
claude,codexorcopilot. Cursor has no separate CLI mode. Its compatible route is the.claude/skills/folder, so check that folder. - Activation. Invoke the skill by name in the client, using the call method in the table. If it still does not run, record the client version, scope and folder path, then compare the result in a second client.
This is the failure our own audit hit below: skills in .claude/skills were invisible to Codex. Keep the check repeatable, using the same skill, client version and scope each time.
Lessons from auditing our own SKILL.md files
Methodology. On October 25, 2026, we inspected the four skills our team uses to run this blog’s repository: blog-seo, format-blog, generate-llms-txt and seo-geo-strategy-builder. The recorded audit refers to the publication snapshot 7d6e2a5. We checked each SKILL.md against the spec limits and the client folder table above. We counted lines and description characters, and looked for non-spec fields and bundled folders.
Here’s the frontmatter of one of them, unchanged:
---
name: format-blog
description: "Format supplied Markdown for this Astro blog's content schema, frontmatter, headings, images, FAQs, and breadcrumb routes while preserving the author's content."
argument-hint: "Format a supplied post draft or existing post path for this repo"
---
What the audit found:
- All four names pass the spec. Each uses lowercase letters and hyphens and matches its folder.
- Descriptions range from 160 to 835 characters. All are under the 1,024 limit and well under Claude Code’s 1,536-character listing cap.
- Bodies are 85 to 134 lines; complete SKILL.md files are 90 to 139 lines. That’s far below the 500-line guidance. Two skills move detail into
references/(one file and four files). - Three of four use
argument-hint. It’s a Claude Code field, so other clients will likely ignore it. - Codex can’t see any of them. They live in
.claude/skills. Cursor and Copilot can read that folder, but Codex scans only.agents/skills.
Two fixes follow. We’d add a “use when” clause to format-blog, the only description that doesn’t say when to use it. And if Codex joins the toolset, we’d sync the folder into .agents/skills rather than keep two hand-edited copies.
How do you write a description that triggers?
The description is what an agent matches against your request. It decides whether the skill loads at all. The spec asks for both what the skill does and when to use it, with specific keywords.
Compare the spec’s own examples. “Helps with PDFs.” is too vague. “Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.” works because it names the tasks and the trigger words.
A few habits help:
- Lead with the action and the object, such as “Drafts release notes from merged pull requests.”
- Add a “Use when” sentence with the words people actually type.
- Name the file types, systems or commands involved.
- Keep it short enough that the trigger words survive any listing cut.
What should you check before installing a skill?
Treat a skill like software. Its instructions steer the agent, and its scripts can run with the agent’s permissions. In a January 2026 study of 31,132 skills from two marketplaces, 26.1% contained at least one vulnerability and 5.2% showed high-severity patterns that suggest malicious intent (Liu et al., arXiv 2601.10338). The same study found that skills bundling scripts were 2.12 times more likely to be vulnerable than instruction-only skills (Liu et al., 2026).
Anthropic’s guidance is to use skills only from trusted sources and to audit every bundled file. Before a skill reaches your team:
- Read SKILL.md and every script, and look for network calls or file access the description doesn’t explain.
- Validate the frontmatter with the spec’s
skills-ref validatetool. - Pin the version you reviewed, and review again when it changes.
The research and a review checklist are in is it safe to use public agent skills?. For how skills differ from tools an agent calls, see AI skills vs MCP tools.
When a skill calls an external tool, MCP vs function calling explains which component executes the request, and the MCP OAuth guide covers the remote server’s sign-in path. Use the LLM gateway vs MCP gateway comparison to place runtime controls. Before distributing a vendor-supplied skill, include its scripts, network destinations and publisher in the AI vendor risk assessment. For rollout controls, pair that review with Claude Code managed settings.
Where does Jarvis Registry fit?
ASCENDING publishes this blog and maintains Jarvis Registry. Its Skill Gateway page describes private skill management, while the AI Skills CLI docs cover delivery commands. Use the intended client and environment when checking the installed package.
Teams can create and edit skills in the Registry UI or API, track versions and attach supporting files. Skill Gateway supports GitHub, GitLab and other Git providers. Repository import is read-only and runs one way into Registry; Registry edits are not pushed back. The published GitHub connection setup is one provider-specific example. Skills are private by default, with view, edit, delete and share permissions per user and group.
Jarvis supports skills for Claude Code, Codex, Cursor and GitHub Copilot. The CLI’s named modes are claude, codex and copilot. Cursor reads compatible directories, including .claude/skills/, so it can use skills delivered into that layout without a separate cursor mode. The CLI reconciles its managed set during sync, including access changes; that does not recall offline or independently copied files. Verify discovery and use of the complete package in each intended client.
For the approval, update and offboarding side, see private AI skill management for developer teams. To check the sync against your own client mix, bring two or three real skills to a Jarvis demo.
References
- Agent Skills specification
- Agent Skills overview
- ASCENDING repository skill snapshot (
7d6e2a5) - Anthropic: Agent Skills overview
- Claude Code: Skills
- OpenAI Codex: Build skills
- Cursor: Agent Skills
- GitHub Docs: About agent skills
- Liu et al.: Agent Skills in the Wild (arXiv 2601.10338)
- Jarvis Skill Gateway
- Jarvis AI Skills CLI
SKILL.md questions from engineering teams
What is a SKILL.md file and what goes in the frontmatter?
It's the one required file in an Agent Skills folder. YAML frontmatter holds the fields and the Markdown body holds the instructions an agent loads when a task matches. Only name and description are required: the name is 1 to 64 lowercase letters, numbers and hyphens and must match the folder name, and the description can be up to 1,024 characters and should say what the skill does and when to use it. License, compatibility, metadata and allowed-tools are optional. The format is defined in the Agent Skills specification.
Do Codex and Cursor use SKILL.md the way Claude Code does?
For the format, yes: Claude Code, Codex, Cursor and GitHub Copilot document support for Agent Skills, so one skill can be reused across them inside the shared spec. They differ in where they look. Claude Code reads .claude/skills, Codex reads .agents/skills, and Cursor reads both. Vendor extension fields may be ignored by other clients, so test the skill in each client you use.
Where should we put skills so Claude Code, Codex and Cursor all find them?
No single project folder is documented for all three today. Claude Code reads .claude/skills, Codex reads .agents/skills, and Cursor reads both. Keep one source copy and sync it into each folder, or use a tool that writes each client's layout. Check the Cursor and Claude Code docs before relying on a path.
Why can developers download a skill but not see it in their coding assistant?
A download only places files on disk. A client lists a skill only from the folders it scans, under the scope it was installed into. Check that the folder matches the client's entry in the table above, that the name matches the folder, and that the CLI mode and scope match the client. Record the client version, because loading behavior can change by version.
Do installed skills use context when they aren't used?
A little. Agents load each skill's name and description at startup, about 100 tokens per skill according to the specification. The full SKILL.md body loads only when the skill is activated, and bundled files load only when the instructions call for them.

