To create an agent skill, make a folder named after the skill, put a SKILL.md file in it, and start that file with front matter holding a name and a description that says what the skill does and when to use it. Below the front matter, write the steps. In the 1,972 public skills we read on November 20, 2026, the median file was 91 lines.
That is the whole format. What separates a skill an agent actually uses from one it ignores is mostly the description, the length, and what you leave out. The rest of this page shows what the public skills in this directory do, so you can copy the habits that are common and avoid the ones that get a skill put in review.
What do real agent skills look like?
We read every SKILL.md in this directory's November 16, 2026 crawl (1,972 skills from 47 GitHub repositories) on November 20, 2026, from each repository's default branch, and parsed its front matter and folder by script. One repository, ComposioHQ/awesome-claude-skills, holds 864 skills built from one short template, so the second column leaves it out.
| What we counted | All 1,972 skills | The 1,108 outside the template repository |
|---|---|---|
Have a name and a description |
1,972 | 1,108 |
name matches the folder name |
1,897 | 1,098 |
| Median SKILL.md length | 91 lines | 129 lines |
| SKILL.md over 500 lines | 16 | 14 |
| Median description length | 164 characters | 234 characters |
| Description says when to use it ("Use when", "Use for") | 748 | 740 |
Uses ## section headings |
1,949 | 1,086 |
| A single SKILL.md, no other files | 1,103 | 253 |
Has a references/ folder |
721 | 721 |
Has a scripts/ folder |
186 | 178 |
Has an assets/ folder |
148 | 148 |
| Weekly scan, November 16: clear / review / flagged | 1,912 / 47 / 13 | 1,050 / 45 / 13 |
Source: Use This Skill directory (data/skills.json, crawled November 16, 2026; data/scan.json, scanned the same day). SKILL.md files and folders read on November 20, 2026. A folder counts if it sits directly inside the skill's folder.
Two things stand out. First, nearly every skill outside the template repository keeps its front matter small: after name and description, the most common fields are allowed-tools (235), metadata (231), license (211) and compatibility (178). Second, two thirds of those skills say in the description when to use them, which is the sentence an agent reads before deciding to load the rest.
How do I create my first skill, step by step?
Make the folder. For Claude Code, a personal skill goes in
~/.claude/skills/<skill-name>/and a project skill in.claude/skills/<skill-name>/inside the repository. Codex scans.agents/skillsin every directory from the current working directory up to the repository root, and$HOME/.agents/skillsfor personal skills. The Agent Skills specification limitsnameto 64 lowercase letters, numbers and hyphens and says it must match the folder name; 1,897 of the 1,972 public skills do.Write the front matter. Two fields are enough. The specification and Codex require
nameanddescription; Claude Code treats every field as optional, recommendsdescription, and uses the folder name whennameis missing.--- name: release-notes description: Writes release notes from the merged pull requests since the last tag. Use when the user asks for release notes, a changelog entry or a summary of what shipped. ---Write the steps below it. Say what to do in order, what to check, and what the finished output looks like. Use
##headings; 1,949 of 1,972 public skills do, and outside the template repository the most common general headings are "Workflow" (321 skills), "When to use this skill" (180), "When to use" (140), "Overview" (144), "Best practices" (119) and "Quick start" (96).Try it. In Claude Code, type
/release-notes, or ask for release notes in plain words and see whether the agent picks the skill on its own; Claude Code's documentation says Claude uses skills when relevant or when you invoke one with/skill-name. In Codex, run/skillsor type$to mention a skill. If it does not trigger, the description is usually the cause; our guide on why a skill does not trigger walks through the fixes.Check it before you share it. Paste the folder's GitHub link into the live check.
What should the description say?
The description is the only part of a skill an agent sees before it decides to use it, so it carries two jobs: what the skill does, and when to use it. Outside the template repository, the median public description is 234 characters, a sentence or two. Only 13 of 1,972 are under 50 characters, and one is over the 1,024-character limit in the Agent Skills specification, which also says the description should cover both what the skill does and when to use it.
Name the task in the words a person would type ("release notes", "changelog"), not only the skill's own name. Our guide on writing a skill description has worked examples.
How long should a SKILL.md be?
Long enough for the steps and the rules, and no longer. Claude Code's documentation and the Agent Skills specification both say to keep SKILL.md under 500 lines and move detailed reference material into separate files. 16 of the 1,972 public skills are over that line; 293 are 50 lines or fewer.
Length has a cost each time the skill runs. In the 15 proofs on this site with recorded tokens, loading the skill added between 683 and 48,544 input tokens to the run, with a median of 8,296 (data/proofs.json, runs of October 24 and November 1, 2026, claude-opus-5-5). Our guide on progressive disclosure explains how a references/ folder keeps that cost down: 721 public skills already use one.
When does a skill need scripts or reference files?
Add a references/ file when the skill needs long material only some tasks use: an API's field list, a style guide, worked examples. Add a scripts/ file when a step should give the same result every time, such as a validator or a converter. 186 of the 1,972 public skills ship scripts, and scripts are where most scan findings live, so keep them short and readable.
What gets a skill flagged or put in review?
The weekly scan reads every file in a skill folder. On November 16, 2026, it put 47 of 1,972 skills in review and flagged 13. The rules that matched, counted once per skill:
| Scan rule | Level | Skills |
|---|---|---|
Asks for elevated privileges (sudo, broad permission changes) |
review | 28 |
| References credential files or secrets on disk | review | 27 |
| Downloads and runs code in one step (for example, piping an installer into a shell) | flag | 13 |
| Rules-override phrasing (often quoted as a warning) | review | 5 |
| Rewrites shared git history | review | 2 |
| Destructive command against the system or home directory | flag | 2 |
| Installs something that runs on its own later | review | 1 |
Source: data/scan.json, scan of November 16, 2026. A skill can match more than one rule. The rules are listed on our safety page.
Most of these are install lines, not bad intent: a skill that tells the agent to curl an installer into sh is flagged even when the installer is genuine. If your skill needs a tool, say which one and link its official install page, rather than writing the pipe yourself. Our guide on what a malicious skill can do explains why these lines matter.
Does a skill work in Codex, Cursor and Gemini CLI too?
Codex's documentation says its skills build on the open Agent Skills standard, so the same folder works there once it sits in a folder Codex scans. Keep the front matter to name and description plus the fields every agent understands, and the skill moves with you. Our guide on skills in Codex, Cursor and Gemini CLI has each agent's folder and the fields each one reads, and how to use skills shows where to put the folder.
How we got these numbers
We cloned each of the 47 repositories in the November 16, 2026 crawl at depth 1 on November 20, 2026, opened the SKILL.md at each skill's recorded path, parsed its YAML front matter, counted its lines and listed its folder. "Says when to use it" means the description matches "use when", "use for", "use to" or "when the user". Scan counts come from the November 16 scan as published. The outside facts (folder locations, required fields, how to invoke a skill, the 500-line and 1,024-character limits) were checked on the Claude Code, Agent Skills and Codex documentation on November 22, 2026. We did not write or run any new skill for this page, and no proofs were re-run.