Preface¶

When adding a reusable workflow for Cursor, Claude Code, or Codex CLI, many people first write instructions into a project rules file. Such rules files will occupy the context long-term; however, Agent Skills split the same set of instructions into on-demand loading folders: only the name and description are exposed normally, and the full instruction is only read when actually needed.

On December 18, 2025, Anthropic made this format an open standard, with the specification document hosted at agentskills.io/specification. You do not need to guess the fields from scratch when writing a Skill yourself. Anthropic provides a starter skeleton in the official repository anthropics/skills, with the directory named template and the Skill name template-skill.

This article follows this template and open specification to explain what it is, how to organize the directory, how to fill in the frontmatter, how to write the main body, and how to enable it in Cursor, Claude Code, and Codex CLI.

What Is It¶

template-skill is the official maintained Skill template from Anthropic, located at github.com/anthropics/skills/tree/main/template. The “Creating a Basic Skill” section of the repository’s README clearly states: you can use the template-skill in the repository as a starting point when writing custom Skills.

It does not process PDFs, run tests, or encapsulate a specific business workflow by itself. The template directory currently only contains a single SKILL.md (~140 bytes) that provides standard YAML frontmatter and body placeholders. Its purpose is to show authors what the minimum viable structure of a valid Skill looks like.

The smallest unit of Agent Skills is a folder, and the root directory must contain SKILL.md. The file is split into two sections: the YAML metadata at the beginning, and the subsequent Markdown instructions. When the Agent starts, it only preloads the name and description; after the task matches, it reads the full body; additional files such as scripts/, references/, and assets/ are only loaded when referenced in the instructions. Anthropic’s engineering blog calls this mechanism progressive disclosure.

Official Template Text¶

The full text of the official SKILL.md is as follows, with no omissions:

---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---

# Insert instructions below

Only three places need to be modified:
- name: Replace it with your Skill identifier, and keep it consistent with the parent directory name.
- description: Clearly state what this Skill does and when it should be enabled. The Agent mainly relies on this text to determine whether to load it.
- Main body: Replace # Insert instructions below with specific steps, examples, and boundary conditions.

The repository README provides a slightly more complete filling example that can be used as the body skeleton:

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

The specification recommends adding step-by-step operations, input and output examples, and common edge cases in the main body. These are not mandatory section names, but they make it easier for the Agent to execute correctly than just leaving the sentence “Insert instructions below”.

Standard Directory Structure and Frontmatter¶

According to the Agent Skills Specification, a Skill directory must contain at least SKILL.md, with other directories optional:

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable scripts
├── references/       # Optional: on-demand reading documents
├── assets/           # Optional: templates, images, data files
└── ...

SKILL.md must first write the YAML frontmatter, then the Markdown main body. The fields in the specification are as follows:

An official example with optional fields:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

You can directly refer to the specification for valid and invalid name examples:

# Valid
name: pdf-processing
name: data-analysis
name: code-review

# Invalid
name: PDF-Processing    # Cannot have uppercase letters
name: -pdf              # Cannot start with a hyphen
name: pdf--processing   # Cannot have consecutive hyphens

The description should include specific trigger words. The specification provides this comparison:

# Better: clearly states both capability and trigger scenarios
description: 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.

# Worse: Too short, making it hard for the Agent to judge when to enable it
description: Helps with PDFs.

Regarding loading rhythm, the specification recommends: the total metadata of all installed Skills should be about 100 tokens; the main body of the activated SKILL.md should be controlled within 5000 tokens; the main file should not exceed 500 lines, and details should be placed in independent reference files. When referencing, use paths relative to the Skill root directory, and try to only reference one level to avoid nested references:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Anthropic’s official Claude platform documentation additionally states: name and description cannot contain XML tags; name cannot use reserved words anthropic or claude. This is a constraint specific to Claude products, not the open specification itself. If the Skill is mainly for Claude, follow the product documentation to avoid these words.

Installation and Activation¶

template-skill is not a business Skill that works out of the box, but a skeleton that needs to be copied and modified. First obtain the files:

git clone https://github.com/anthropics/skills.git
cp -r skills/template my-skill-name

You can also just get the SKILL.md file:

mkdir -p my-skill-name
curl -o my-skill-name/SKILL.md \
  https://raw.githubusercontent.com/anthropics/skills/main/template/SKILL.md

Then change the directory name and the name field to the same identifier, and place the directory in the location that each tool will scan. The paths in each tool’s official documentation are not exactly the same, so you need to check them separately.

Cursor (cursor.com/docs/skills) will automatically discover Skills from these locations:

For compatibility, Cursor also reads .claude/skills/, .codex/skills/, and ~/.claude/skills/, ~/.codex/skills/ under the user directory. Project-level example:

.cursor/skills/my-skill-name/SKILL.md

You can manually invoke it by entering / in the Agent conversation and searching by the Skill name; the Agent will also automatically determine whether to enable it based on the description.

Claude Code (code.claude.com/docs/en/skills) commonly uses these locations:

Personal Skill example:

mkdir -p ~/.claude/skills/my-skill-name
# Place the modified SKILL.md in this directory

Claude Code will automatically match based on the description, and you can also directly invoke it with /skill-name. In case of duplicate names, the personal directory takes precedence over the project directory.

Codex CLI (developers.openai.com/codex/skills) scans the repository location .agents/skills (searched from the current working directory up to the repository root), and the user-level location is $HOME/.agents/skills. There is also a machine-level location /etc/codex/skills. Codex will load the name, description, and file path on startup; after the task matches, it reads the full SKILL.md. You can manually invoke it via /skills in the CLI/IDE extension, or mention a Skill with $.

All three tools can read the same compliant SKILL.md. The main differences are the scan directories and invocation prefixes (/ or $), not the template format itself.

If you just want to try the pre-made example plugins in the official repository in Claude Code without modifying the template yourself, you can use:

/plugin marketplace add anthropics/skills

Then follow the documentation to install document-skills or example-skills. This process installs the example Skills in the repository, and will not turn template-skill into an executable business capability. To write your own Skill, you still need to copy the template, modify the fields, and place it in the scan directory.

Write a Runnable Example from the Template¶

Let’s use the “summarize uncommitted changes” scenario from Claude Code’s documentation to demonstrate how to flesh out the template. First create the directory:

mkdir -p ~/.claude/skills/summarize-changes

Write SKILL.md similar to the following (the description comes from Claude Code’s official getting started example; the dynamically injected !git`` is Claude Code’s extended syntax, not part of the open specification, do not copy this line when switching to Cursor or Codex):

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Instructions

Summarize the uncommitted changes in two or three bullet points, then list any risks such as missing error handling, hardcoded values, or tests that need updating. If there are no uncommitted changes, say so.

Make any changes to a file in a git repository, then test it after starting Claude Code:

What did I change?

Or directly:

/summarize-changes

To use it in Cursor, change the directory to .cursor/skills/summarize-changes/SKILL.md or ~/.cursor/skills/summarize-changes/SKILL.md, and keep the same name/description in the frontmatter. To use it in Codex, use .agents/skills/summarize-changes/ or ~/.agents/skills/summarize-changes/.

How to Expand After Writing the Main Body¶

The template only has one page of instructions. When tasks become more complex, the specification recommends splitting details out instead of turning SKILL.md into a full manual.
- scripts/: Code directly executed by the Agent. Suitable for deterministic steps, such as validation, format conversion. Scripts should be self-contained or clearly state dependencies, and include easy-to-understand error messages.
- references/: Supplementary documents for on-demand reading, such as REFERENCE.md, form instructions, domain handbooks. A single file should stay focused, avoid stuffing all background information at once.
- assets/: Static resources such as templates, diagrams, lookup tables.

Anthropic’s engineering blog used the official PDF Skill to explain why splitting files is beneficial: after moving the form filling instructions to forms.md, the main SKILL.md can remain concise, and the Agent only reads that file when filling out forms. Code can also be used as a tool: the same blog mentioned that the PDF Skill has a Python script for extracting form fields, and Claude can directly run the script without loading both the script and the PDF into the context.

In terms of writing principles, Claude Platform’s Skill authoring best practices emphasizes: by default assume the model already has general knowledge, only write the processes, conventions, and pain points it lacks. If you can explain it clearly with short instructions, do not first explain what the file format is.

After writing, you can validate it using the reference implementation provided in the specification:

skills-ref validate ./my-skill-name

This command checks whether the frontmatter is valid and whether the naming conforms to the conventions. The tool is hosted at github.com/agentskills/agentskills.

Applicable Scenarios and Notes¶

The situations where it is appropriate to start with template-skill are specific: you already have a set of repeatedly pasted operation instructions, want to turn them into discoverable, shareable Skills, but do not yet have scripts and long documents. Starting from the official skeleton can avoid missing the required YAML delimiters, and also avoid writing name in uppercase or mismatching it with the directory name.

It is not suitable as a “Skill writing tutor”. There is another skill-creator in the repository, which is a complete Skill with evaluation scripts and reference documents used to guide how to design, test, and iterate. template-skill only provides the minimum valid file. Do not mix the two: one is a blank sheet of paper, the other is a writing guide.

There are several easy-to-make mistakes when writing:
1. The directory name and name must be consistent. The specification requires name to match the parent directory name, as tools discover Skills by directory.
2. description determines whether it will be automatically invoked. Just writing “helps with X” is usually not enough, you need to include the words the user might say.
3. First write short instructions, confirm that they can be triggered and executed, then add scripts/ and references/. The official help documentation also recommends: start with Markdown instructions, add code only when determinism is needed.
4. Each product will add its own extensions beyond the open fields. For example, Cursor’s paths, disable-model-invocation, Claude Code’s dynamic context injection, Codex’s agents/openai.yaml. These fields are not part of template-skill. When sharing across tools, first ensure that name and description conform to agentskills.io, and add extension fields according to the target product documentation.
5. Skills can include executable scripts. Anthropic recommends only installing trusted sources, and reading through bundled scripts and external network requests before enabling them. Do not hardcode secrets in instructions or scripts.

The repository README also states: these Skills are mainly for demonstration and education, and the actual product behavior may not exactly match the implementation in the repository. The template can ensure a correct format starting point, but cannot guarantee that the modified version will perform consistently across every Agent, you need to test triggering and execution with real tasks in the target tool.

Summary¶

template-skill is the starter skeleton in Anthropic’s official Skill repository: a SKILL.md with name and description placeholders. Agent Skills have become an open standard, and the same file can be placed in the skills directories of Cursor, Claude Code, and Codex CLI for use.

The steps to write your first Skill from it can be summarized in four sentences: Copy the template; Make the directory name match the name; Write the description as “what it does + when to use it”; Write executable steps and examples in the main body. Use skills-ref validate when you need to check the format.

Official template: https://github.com/anthropics/skills/tree/main/template

Format specification: https://agentskills.io/specification

Mechanism explanation: Equipping agents for the real world with Agent Skills