Create your first reusable skill

What to understand

• A skill is procedural knowledge packaged as a folder. At minimum it is a directory containing one SKILL.md file; it can also bundle scripts/, references/, and assets/ the agent loads only when needed. The official framing is identical across tools: a skill packages instructions, resources, and optional scripts so the agent can follow a multi-step workflow reliably every time, the same way you'd write a runbook for a teammate rather than re-explaining the task each shift.
• SKILL.md has exactly two parts: frontmatter and body. The frontmatter is YAML between --- markers; the body is markdown instructions. The open standard requires two frontmatter fields, name and description, and treats everything else (license, compatibility, metadata, allowed-tools) as optional. In Claude Code only description is strictly needed (name defaults to the folder), but writing both keeps you portable across tools.
• name is the identity, and the standard constrains it tightly: 1-64 characters, lowercase letters, numbers and hyphens only, no leading/trailing or consecutive hyphens, and it must match the parent directory name. The folder name, not the frontmatter name, is what becomes your slash command in both tools, so ticket-themes becomes /ticket-themes. Name after the action, in kebab-case.
• description is the most important line you will write, and it has a hard budget. The standard caps it at 1,024 characters; Claude Code additionally truncates the combined description + when_to_use text at 1,536 characters in the skill listing and only keeps all descriptions in context up to a budget (~1% of the model's context window). The description is what the agent reads to decide whether to fire the skill, so it must say both what the skill does AND when to use it, in the exact words you'd naturally say. A vague description ('helps with tickets') is why a skill never fires; a concrete one with trigger phrases is why it fires at the right moment and stays quiet otherwise.
• The body is instructions, not narration. There are no format restrictions, but every line you write becomes a recurring token cost once the skill loads, so state what to do, not why, in the same terse register you'd use for CLAUDE.md. Keep the body well under the recommended ~5,000 tokens / 500 lines and push anything long (templates, reference tables, example outputs, scripts) into sibling files the agent reads only on demand. This is progressive disclosure, and it is the whole reason a skill is cheap.
• Skills load in three progressive stages, and understanding them explains every design rule. (1) Discovery: at startup the agent loads only each skill's name + description (~100 tokens each), just enough to know it exists. (2) Activation: when a task matches the description, the agent reads the full SKILL.md body into context. (3) Execution: it follows the instructions, loading referenced files or running scripts only as needed. So a hundred skills can sit on hand for the cost of a hundred one-line descriptions; the expensive body is paid only when the skill actually runs.
• Skills are invoked two ways, and the difference is about control. Implicitly, the agent loads the skill when your request matches its description, that's the discovery/activation flow above, and it's why the description has to be good. Explicitly, you name it yourself: Claude Code uses /skill-name; Codex uses $skill-name, the /skills picker, or a direct mention. Explicit invocation gives you control over timing, essential for anything with side effects, where you don't want the agent deciding when to act.
• Location decides scope, and both tools mirror the same idea at different paths. Claude Code: ~/.claude/skills/<name>/ is personal (all your projects).claude/skills/<name>/ is project-only (ships with one repo, committed to version control). Codex: $HOME/.agents/skills/<name>/ is user-level, and .agents/skills/<name>/ in a repo (or its root) is repository-scoped, with /etc/codex/skills for system/admin. Same concept, different folders, and the portable SKILL.md drops cleanly into either.
• Both tools let you make a skill manual-only, the safety control for side effects. Claude Code: set disable-model-invocation: true so only you can trigger it with /name and the agent never auto-fires it. Codex: set allow_implicit_invocation: false in agents/openai.yaml so it won't trigger implicitly while still working via $name. Anything that sends, posts, deploys, or writes to a system of record belongs behind one of these, don't let the agent decide when to touch the outside world.
• allowed-tools is convenience, not a security boundary, know the difference. It pre-approves a narrow set of tools (e.g. allowed-tools: Read Grep, or a scoped pattern like Bash(git status:*)) so the agent uses them without per-use prompts while the skill is active. The Agent Skills spec marks this field experimental, and Claude Code is explicit that it does not restrict what's available, it only waives the prompt for the listed tools, and for a project skill it takes effect only after you accept the workspace trust dialog. A skill in an untrusted repo can grant itself broad access, so review project skills before trusting them.
• Claude Code adds power beyond the open standard, worth knowing even if you don't use it yet: dynamic context injection with !`command` (and ```! fenced blocks), which runs a shell command and inlines its output into the skill before the agent ever reads it (e.g. !`git diff HEAD` to ground a review in your real working tree); $ARGUMENTS / $0 / $1 substitution for passing parameters; context: fork to run the skill in an isolated subagent; and paths: globs that auto-activate a skill only when you're working on matching files. These are the same SKILL.md, extended.

Deeper dive

The skill format compared (open standard vs Claude Code vs Codex, June 2026)

The same SKILL.md is portable; the required core is identical and only the optional, tool-specific extras differ. Skills move fast, field names and defaults change between releases; verify against the official docs linked below before relying on specifics.

Sources (as of June 2026): Agent Skills. Specification (frontmatter, limits, progressive disclosure) · Claude Code. Skills (frontmatter reference, scopes, advanced) · OpenAI Codex. Skills (SKILL.md, locations, invocation)

Step by step

1

Decide scope, then create the folder

12

Choose personal or project scope. For a workflow you'll reuse everywhere, go personal; for one that belongs to a specific repo and should travel with it, go project (and commit it). In Claude Code: mkdir -p ~/.claude/skills/<your-skill-name> (personal) or .claude/skills/<your-skill-name> (project). In Codex: $HOME/.agents/skills/<your-skill-name> (user) or .agents/skills/<your-skill-name> in the repo. Name the folder after the ACTION in kebab-case (lowercase words joined by single hyphens), e.g. ticket-themes, and remember the folder name must match the skill name and becomes your slash command. You should see the new empty folder (ls ~/.claude/skills) before moving on.

HintThe folder name is the command and the identity. Pick it once, carefully: ticket-themes gives you /ticket-themes in Claude Code and $ticket-themes in Codex. (The terminal stills in this lesson use summarize-changes as their worked example, the shape is identical to your ticket-themes.)

On this screen

1. 1Personal vs project. Personal (~/.claude/skills, $HOME/.agents/skills) works across all projects; project (.claude/skills.agents/skills) ships with one repo and is committed to version control.
2. 2Folder = command = name. The directory name sets the slash command AND must equal the frontmatter name (standard rule), so ticket-themes -> /ticket-themes.

2

Write the frontmatter, name and a trigger-rich description

12

Create SKILL.md inside the folder. Open with ---, then name: <your-skill-name> (lowercase, hyphens, matches the folder), then description: a single line (<=1,024 chars) that says BOTH what the skill does AND when to use it, in the exact words you'd naturally say, with a boundary for when it should NOT fire. Close with ---. Lead with the key use case and concrete trigger phrases; the agent matches your request against this text at Discovery, so a vague description means the skill never fires. Done when the description, read aloud, sounds like the sentence you'd naturally type when asking for the task.

HintWrite the description as a trigger, not a title. 'Cluster support tickets into themes. Use when asked to digest, triage, or theme recent tickets' beats 'Ticket themer', the second never activates implicitly.

On this screen

1. 1Same standard, Codex side. The Agent Skills page shows the identical SKILL.md format, name + description required, folder tree with SKILL.md as the entrypoint.
2. 2How Codex uses skills. Explicit ($name or the /skills picker) vs implicit (your request matches the description), the visible reason your description must contain the words you actually say.

3

Write the body as a terse procedure

12

After the closing ---, write the instructions the agent follows when the skill runs. Use short labelled sections (Task / Inputs / Steps / Output format / Boundaries). State what to do, not why. Capture the one or two pieces of judgement you'd otherwise re-type every time (e.g. 'cluster by root cause, not symptom'). Include an explicit output-format block so results are deterministic. Keep it well under ~500 lines / ~5,000 tokens, once a skill loads, its whole body stays in context for the session, so every line is a recurring cost. Done when the body fits on one or two screens and contains an explicit output-format block.

HintPut the irreversible steps in a Boundaries section in writing ('read and summarise only; never send or close anything'). Stating the no-go keeps the dangerous action out of the procedure.

On this screen

1. 1Description-only frontmatter. This minimal example omits name:, legal in Claude Code, where name defaults to the folder. Add name: in yours for portability.
2. 2## Instructions. Two terse sentences, not an essay. Your version adds Task/Inputs/Steps/Output format/Boundaries, including the explicit output block this minimal example skips, which is what makes runs deterministic.

4

Decide who can invoke it

12

If the workflow has side effects or you want to control timing, make it manual-only: in Claude Code add disable-model-invocation: true so only you trigger it with /name; in Codex set allow_implicit_invocation: false in agents/openai.yaml so it won't fire implicitly but still works via $name. For pure read-and-summarise skills, leave the default so the agent can also load it automatically when relevant. Done when you can say which invocation mode the skill uses and why.

HintAnything that sends, posts, deploys, or writes to a system of record should be manual-only. Don't let the agent decide when to act on the outside world, that decision is yours.

On this screen

1. 1Frontmatter reference (right-hand contents). Where disable-model-invocation is documented, check current field names here before relying on them.
2. 2Troubleshooting entries (right-hand contents). 'Skill not triggering' / 'Skill triggers too often', the two failure modes this invocation decision controls; for side effects, manual-only ends the second one by design.

5

Pre-approve only the tools you need

If the skill must run tools, add allowed-tools listing only the narrow set required, e.g. allowed-tools: Read Grep, or a scoped pattern like Bash(git status:*). This waives the per-use prompt for those tools while the skill is active; everything else stays governed by your normal permissions. Be stingy, allowed-tools is convenience, not a security boundary, and for a project skill it only takes effect after you accept the workspace trust dialog. Done when every listed tool is one the procedure actually uses.

HintReview any project skill before trusting a repo: a skill can grant itself broad tool access via allowed-tools. Treat an unreviewed .claude/skills or .agents/skills folder like any other untrusted code. allowed-tools only waives prompts for the listed tools, deny rules in your permission settings are the real boundary.

6

Test both ways, then tighten

12

Trigger the skill explicitly first, /<your-skill-name> in Claude Code, $<your-skill-name> or the /skills picker in Codex, with real input, and check the output against the success criterion you wrote in lesson 13. Then start a FRESH request phrased the way you'd naturally ask and confirm the agent loads it implicitly. Finally trim: move any long reference material, templates, or examples into a sibling file (reference.md, template.md) referenced from SKILL.md, so it loads only when needed and the activation stays cheap.

HintIf it doesn't fire implicitly, the description is almost always the culprit. Read it aloud as if asking for the task, if it's missing the words you actually said, add them.

On this screen

1. 1Both invocation paths on one screen. 'what did I change?' fires it implicitly via the description; '/summarize-changes' calls it by name. Run your own test explicit-first to confirm it works before testing retrieval.
2. 2'Using skill: ...' line. The activation confirmation to look for. If a natural request doesn't produce it, the description is missing your real words, add them.

Production prompt examples

---
name: ticket-themes
description: Cluster a batch of support tickets into 3-5 root-cause themes and produce a short, urgent-first markdown report. Use when asked to digest, triage, theme, or summarise recent support tickets, or when the user pastes three or more tickets and asks what the common issues are. Do NOT use for replying to a single ticket. This skill only reads and summarises, it never sends, posts, or closes anything.
allowed-tools: Read Grep
---

## Task
Group the provided support tickets into 3-5 themes by ROOT CAUSE (the underlying problem), not by SYMPTOM (the surface wording). Produce one short markdown report. Read-only: do not send, post, label, or close anything.

## Inputs
- A batch of tickets pasted into the conversation, OR a path/glob the user names (e.g. tickets/*.md). Use only what the user provides, do not go looking for other files.
- If fewer than 3 tickets are provided, say so and stop; this skill is for batches.

## Steps
1. Read every ticket in scope.
2. Cluster by root cause. Merge tickets that share an underlying problem even if their wording differs; split a cluster if it actually hides two distinct causes.
3. For each theme: a one-line name, a count of tickets, a one-sentence root-cause summary, and ONE representative ticket quote (<=15 words, verbatim).
4. Identify anything URGENT (outage, data loss, security, paying-customer blocker) and pull it to the very top, regardless of cluster size.
5. If something doesn't fit a theme, list it under "Unclustered" rather than forcing it.

## Output format
```
## Support themes - <date> (<N> tickets)

### ⚠️ Urgent (act first)
- <one line per urgent item, with ticket id>

### Themes
1. <Theme name> - <count> tickets
 Root cause: <one sentence>
 Example: "<verbatim quote>"
2. ...

### Unclustered
- <ticket id>: <one line> (only if any)
```

## Boundaries
- Read and summarise ONLY. Never send, reply, label, assign, or close a ticket; never call an external API.
- Do not invent tickets, counts, or quotes. Every quote must be verbatim from an input.
- Keep the whole report under ~250 words; detail belongs in the source tickets, not here.

Common mistakes to avoid

• Writing the description as a title ('Ticket themer') instead of a trigger ('...Use when asked to digest, triage, or theme recent tickets'), so the skill never fires implicitly.
• Putting a procedure into CLAUDE.md (where it costs tokens every turn and bloats the file) when it should be a skill, or making a skill for a plain project fact that should just be a standing instruction.
• Letting a side-effect skill stay model-invocable instead of setting disable-model-invocation: true (Claude Code) / allow_implicit_invocation: false (Codex).
• Stuffing long reference material, templates, or examples into SKILL.md, inflating the recurring token cost on every activation instead of pushing it to sibling files.
• Naming the folder and the frontmatter name differently, or using uppercase/spaces/double-hyphens, the standard requires lowercase kebab-case that matches the folder.
• Granting broad allowed-tools (or trusting an unreviewed project skill) and treating it as a security boundary, when it only waives per-use prompts.
• Copying one tool's manual-only flag into the other (e.g. putting disable-model-invocation into a Codex skill, or allow_implicit_invocation into Claude Code), they're tool-specific.

Source conflicts to review

• The open standard requires both name and description; Claude Code treats name as optional (defaults to the folder) and only strongly recommends description. Writing both keeps you portable, verify the minimal requirement at the tool you actually use.
• Manual-only invocation is spelled differently per tool: Claude Code uses disable-model-invocation: true in frontmatter; Codex uses allow_implicit_invocation: false in agents/openai.yaml. Don't copy one into the other.
• Description/listing length limits differ by layer (open standard: 1,024 chars; Claude Code listing: 1,536 combined chars within a ~1% context budget that is configurable via skillListingBudgetFraction / maxSkillDescriptionChars). Treat the figures as accurate as of June 2026 and re-check the docs before relying on exact numbers.
• Skills ship fast in both tools; field names, defaults, and invocation syntax (e.g. Codex's $ mention vs /skills picker) shift across point releases. Confirm against agentskills.io, code.claude.com, and developers.openai.com before relying on specifics.