How to create a Claude skill, step by step

This guide shows how to create a Claude skill from nothing: one folder, one SKILL.md, and the files it needs. The example is a small skill that makes Open Graph images, because a skill that produces a file is easy to check: either the PNG is right or it isn’t. Everything here follows the Agent Skills specification (opens in a new tab), which Claude Code’s docs say its skills follow, so the same folder also loads in Codex, Cursor and other agents that read the format.

What a skill is made of

A skill is a folder. The only required file is SKILL.md: a header in YAML between --- markers, then Markdown instructions. The spec suggests three optional folders beside it.

release-og-card/
├── SKILL.md          # required: header + instructions
├── scripts/          # code the agent runs
├── references/       # longer docs it reads only when needed
└── assets/           # templates, images, data

Write both name and description even though Claude Code needs neither: the spec requires them, and so do Codex and Cursor. Cursor also requires the name to match the folder.

How to create a Claude skill in six steps

1. 1

   Step 1: Make the folder

   Name it after the skill, in lowercase with hyphens. In your home folder it serves every project; in .claude/skills/ inside a repository it serves that repository.

   TerminalCopy Terminal

   mkdir -p ~/.claude/skills/release-og-card/scripts

2. 2

   Step 2: Write the header

   The description is the only part the agent reads before it decides to use the skill, so say what it makes, what it needs and the words people use when they ask for it. Write a description that makes a skill trigger covers this in detail.

3. 3

   Step 3: Write the instructions

   Numbered steps the agent follows: what to ask for, which script to run with which arguments, how to check the result, and what to do when something fails. Write them for a capable colleague who has never seen your project.

4. 4

   Step 4: Add scripts and reference files

   Put anything that must come out the same every time in a script, not in prose. Move long reference material into references/ and link it from SKILL.md so the agent reads it only when needed. Both Anthropic and the spec say to keep SKILL.md under 500 lines.

5. 5

   Step 5: Check it loads and triggers

   Start a new session, ask for the job in plain words, and see whether the skill is used. Then run it by name. Details are in the next section.

6. 6

   Step 6: Share it

   Commit it to a repository, wrap it in a plugin, or zip it for the Claude app. See Share your skill.

A complete SKILL.md example

Here is a whole skill that makes a 1200×630 release card. It uses only the spec’s fields, so it isn’t tied to one agent. Its script, scripts/render.mjs, is yours to write: in this design it fills an HTML template with the text and screenshots it with headless Chrome, which is how Lookbk’s free Editorial OG Card works.

---
name: release-og-card
description: Make a 1200x630 PNG link-preview card (Open Graph image) announcing a software release, from a version number, a headline of up to 60 characters and a brand colour. Use when someone asks for a release card, an OG image or social card for a changelog, or a link preview for a new version.
license: MIT
compatibility: Needs Node.js 18+ and Chrome, Chromium or Edge.
---

# Release OG card

This skill's folder is `<skill>` below: the folder this SKILL.md is in.

## Steps

### 1. Get the text

Ask for anything missing. Never invent a version number or a claim.

- `version`: such as `v2.4` (up to 12 characters)
- `headline`: what changed, up to 60 characters
- `color`: a hex colour, default `#2433e8`

### 2. Write card.json

```json
{ "version": "v2.4", "headline": "Exports are three times faster", "color": "#2433e8" }
```

### 3. Render

```bash
node <skill>/scripts/render.mjs card.json out/release-card.png
```

The script checks every field first and lists all problems at once. Fix them
and run it again. It exits non-zero if the PNG is not 1200x630.

### 4. Show the result

Open the PNG and tell the person where it is. If the headline wrapped onto
three lines, suggest a shorter one.

## Troubleshooting

- **No Chrome found**: set `CHROME_PATH` to the browser's executable.
- **Text in a fallback font**: the font didn't load; render with network access.

A few choices in it are worth copying. The header names the output, the size and the file type. The instructions tell the agent to ask rather than invent. The script validates before it renders and exits non-zero on a bad result, so the agent can tell success from failure without looking at the image. In Claude Code you can write ${CLAUDE_SKILL_DIR} in place of <skill>, but the plain wording works in every agent.

Test that it triggers

• Ask for the job without naming the skill, such as “make a link preview for our v2.4 release”, in a new session. If Claude uses the skill, the description works.
• Run it by name with /release-og-card. Claude Code’s troubleshooting list also suggests asking “What skills are available?” to see whether it loaded.
• Check the header parses. If the YAML is broken, Claude Code still loads the body with no description, so /release-og-card works but Claude never picks it on its own. claude plugin validate ~/.claude/skills finds such files (Claude Code v2.1.233 or later), and claude --debug shows the parse error. Outside Claude Code, the spec’s skills-ref validate ./release-og-card checks the header and naming rules.
• Check the output, not just the trigger. Anthropic’s docs put it plainly: seeing a skill trigger tells you Claude found it, not that it did what you intended. Run it with and without the skill and compare.

Let a skill write the skill

Each of the big agents has a helper for this. In Claude Code, install Anthropic’s skill-creator plugin with /plugin install skill-creator@claude-plugins-official; its README says it creates new skills, improves existing ones and runs evals, and the skills docs say it can generate should-trigger and should-not-trigger prompts and suggest description edits. Codex has a built-in $skill-creator that asks what the skill does, when it should trigger and whether it needs scripts. Cursor has a /create-skill command. Treat what they write as a draft and review it like any other code.

Share your skill

Make it work in Codex and Cursor too

The format is the same, so portability is mostly about folders and fields. Claude Code reads .claude/skills. Codex reads .agents/skills, from your working folder up to the repository root, and ~/.agents/skills. Cursor reads .agents/skills and .cursor/skills, and .claude/skills and .codex/skills for compatibility. Where skills live has the full table, including Copilot, Gemini CLI and OpenCode.

• Keep the header to the spec’s fields, and the folder name equal to name.
• Refer to files by paths relative to the skill folder, one level deep, as the spec recommends.
• Put Claude Code-only behaviour, such as context: fork, in a copy you keep for Claude Code, or leave it out.
• Install for everything at once by copying the folder to both ~/.claude/skills/ and ~/.agents/skills/. An agent that reads both may then list it twice; Where skills live explains which copy wins.

What a skill that makes something visual needs

Every skill on Lookbk is built the same way, and the pattern suits any skill whose result is an image, a video, a deck or a page. Take Editorial OG Card: its folder holds SKILL.md, a scripts/ folder (one script turns Markdown front matter into cards.json, another renders the PNGs), a template/ with the card’s HTML, CSS and JavaScript, two fictional examples under examples/, and a NOTICE.md listing the fonts and software it uses.

• The design lives in a template, not in the prompt. The agent fills in words; it doesn’t redraw the layout, so the tenth card looks like the first.
• Every field has a limit, and the script enforces it. Its render script checks every card and lists every problem at once before drawing anything.
• The script checks its own output. It confirms every PNG is 1200×630 and writes a preview page to look at.
• Examples ship with the skill. They show the agent a finished input, and the previews on its Lookbk page are rendered from them.

To read a complete one, install a free skill and open its folder. Free skills need no account:

curl -fsSL https://lookbk.dev/cli.js | node - add editorial-og-card

Free

image

Editorial OG CardClaude CodeCodexCursor+3 more agents

Free

image

Blueprint Architecture DiagramClaude CodeCodexCursor+3 more agents

Free

video

Kinetic Title DropClaude CodeCodexCursor+3 more agents

Free

slides

Swiss Grid DeckClaude CodeCodexCursor+3 more agents

Free

web

Mono Editorial LandingClaude CodeCodexCursor+3 more agents