Guides · Updated November 22, 2026

How to create an agent skill, based on 1,972 real ones

By Tineessa Nelson, Use This Skill

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?

  1. 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/skills in every directory from the current working directory up to the repository root, and $HOME/.agents/skills for personal skills. The Agent Skills specification limits name to 64 lowercase letters, numbers and hyphens and says it must match the folder name; 1,897 of the 1,972 public skills do.

  2. Write the front matter. Two fields are enough. The specification and Codex require name and description; Claude Code treats every field as optional, recommends description, and uses the folder name when name is 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.
    ---
    
  3. 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).

  4. 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 /skills or 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.

  5. 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.

Questions

Which front matter fields does a skill need?

A name and a description. The Agent Skills specification and Codex require both; Claude Code requires neither but recommends the description. All 1,972 public skills we read on November 20, 2026 have both, and the next most common field outside one template repository, allowed-tools, appears in 235. Add other fields only when you need what they do, such as disable-model-invocation for a skill you want to start yourself.

How long should a SKILL.md be?

Long enough to hold the steps and rules, and no longer. Outside one template-generated repository, the median public SKILL.md is 129 lines, and only 16 of 1,972 are over 500 lines. Move long tables, API notes and examples into a references/ folder so they load only when a task needs them.

How do I check my skill before I share it?

Paste its GitHub link into the free check at usethisskill.com/scan. It runs the same rules as the weekly scan, which put 47 of 1,972 public skills in review and flagged 13, mostly for sudo lines, credential file paths and download-and-run installers.