how to create
agent skills.

What is an agent skill?

Agent Skills are an open folder format for reusable instructions, scripts, references, and assets. Compatible agents first read only each skill's name and description. When a task matches, the agent loads the full instructions and any supporting files it needs. That progressive disclosure makes skills more reusable than repeatedly pasting a long prompt into a chat.

A skill is best for procedural knowledge: a code-review checklist, a publishing workflow, a document template, or a repeatable research method. Use a plain prompt for one-off requests. Use MCP when the agent needs a standardized connection to an external tool or data source. A skill can instruct an agent how to use MCP, but the two are not substitutes.

How do you create an agent skill?

1. Choose one repeatable job. Define a narrow task with a clear input, output, and finish condition. If the workflow cannot be described in one sentence, split it before writing files.
2. Create the skill folder. Use a lowercase kebab-case folder name and put an uppercase SKILL.md file at its root.
3. Write valid frontmatter. Add a name that matches the folder and a description that says what the skill does and when an agent should load it.
4. Write the smallest useful workflow. State required inputs, ordered actions, the output contract, important edge cases, and a final verification step.
5. Test activation and results. Try prompts that should and should not trigger the skill, then run a realistic task and verify the output instead of judging the wording alone.
6. Review and publish. Remove secrets, review bundled scripts, add a license when sharing publicly, validate the folder, and publish it from a trustworthy source.

The directory is intentionally small. Do not add scripts, configuration, or references until the workflow needs them.

pull-request-review/
├── SKILL.md
├── scripts/       # optional
├── references/    # optional
└── assets/        # optional

What do Claude Code and Codex agree makes a good skill?

Anthropic and OpenAI use the same open folder model and converge on the same authoring discipline. Build one reusable workflow, make its trigger easy to retrieve, load detail only when needed, and verify behavior with real tasks.

Read the Anthropic skill-authoring guide and OpenAI's Codex skill guide for current client-specific behavior.

What belongs in SKILL.md?

The file has YAML frontmatter followed by Markdown instructions. The open specification requires name and description. The name must match the folder, use lowercase letters, numbers, and hyphens, and stay within 64 characters. The description can use up to 1,024 characters and should explain both what the skill does and when to use it.

---
name: pull-request-review
description: Reviews pull requests for correctness, security, and missing tests. Use when asked to review a PR, diff, patch, or proposed code change.
license: MIT
---

# Review the change

1. Read the request and the complete diff.
2. Trace changed behavior through its callers.
3. Report only actionable defects with file and line references.
4. Check security boundaries and missing regression coverage.
5. If no defects remain, say so and list any residual test gaps.

Good instructions define the order of work, evidence to inspect, output format, and finish condition. Avoid motivational prose and facts the agent already knows. Put long API documentation in references/, deterministic operations in scripts/, and templates in assets/.

How do you make a skill trigger reliably?

The description is the retrieval layer. Write it like a precise search result: lead with the capability, name the objects it handles, then include natural phrases that signal when it applies. "Helps with code" is too broad. "Reviews pull requests, diffs, and patches for correctness, security, and missing tests" gives an agent useful matching terms and boundaries.

Test at least three positive prompts, two close negative prompts, and one ambiguous prompt. If the skill fails to load, improve the description before making the body longer. If it activates too often, narrow the trigger conditions. Reliable selection matters more than an elaborate workflow the agent never loads.

A 2026 study of 138,133 public skills identified routing metadata as the clearest functional bottleneck: skills without routing defects were retrieved more reliably than skills with missing, vague, overlong, or misplaced descriptions. See What Keeps Agent Skills from Being Reusable? for the dataset, detector, and limitations.

How should you test an agent skill?

• Validate the format: run skills-ref validate ./pull-request-review.
• Test activation: confirm relevant prompts load it and unrelated prompts do not.
• Test the outcome: run a realistic task and check the produced artifact, not just the agent's explanation.
• Test failure paths: remove a required input or tool and confirm the skill stops with a useful message.
• Test portability: when claiming cross-client support, run the same fixture in every named client.
• Review safety: inspect commands, network calls, permissions, secrets, and destructive operations.

Keep one small fixture that can be rerun after every change. Version the folder in Git so users can inspect history, pin revisions, and report problems against a specific release.

Which SKILL.md smells should you avoid?

A July 2026 empirical study analyzed 238 real-world skills and found that more than 99% contained at least one authoring smell, with 10.5 smells per skill on average. The most common, a rationalization loophole, appeared in 94% of the sample. Treat these findings as review prompts rather than a universal quality score.

• Rationalization loopholes: remove vague exceptions that let the agent skip a required check; state measurable conditions instead.
• No validation step: finish with an observable check against the promised output, not a claim that the task is complete.
• Rigid command sequences: explain the objective and constraints; move deterministic, environment-specific operations into a reviewed script.
• Unclear names or descriptions: name the job plainly and include realistic activation language in frontmatter.
• Oversized instructions: keep the core procedure focused and move deep background into references; the study's static detector flags files above 5,000 words.

Read From Anatomy to Smells: An Empirical Study of SKILL.md in Agent Skills for the study design, full taxonomy, and limitations.

How do you publish and help people discover a skill?

Publish the skill in a public repository with a clear license, maintainer identity, examples, compatibility notes, and a changelog when behavior changes. Make the repository's human-facing README answer the job the skill solves, supported clients, installation command, required permissions, and how it was tested. Never put a second README inside the skill folder when the client expects all agent instructions in SKILL.md.

Use the same descriptive name in the folder, repository title, page title, and link text. Earn references by shipping useful examples, contributing to client documentation and community lists, and maintaining the skill after publication. A copied directory with hundreds of thin listings is easy to index; original tests, transparent audits, and genuinely useful guides are much harder to replace.

Follow the complete Agent Skill publishing guide to test the public install path and understand how skills.sh discovery works.

Ready to compare patterns? Browse the complete agent skill catalog, study the agent category, or adapt a stop condition from the agent loop library. You can also explore coding, research, creative, and productivity skills.

Continue with the safe installation guide, compare Agent Skills and MCP, or use the security review checklist before adopting third-party workflows.

What do people ask about agent skills?

Which official sources define the format?

The cross-client guideline follows Anthropic's Skill authoring best practices and OpenAI's Build skills guide for Codex.

This guide was checked against the Agent Skills specification, Claude Code skills documentation, Anthropic's custom skill guide, OpenAI's Skills documentation, and the 2026 empirical SKILL.md authoring study. Client behavior changes, so verify installation paths and optional fields in the documentation for the product you use.

The Matt Pocock case study was checked against the mattpocock/skills repository, its skill-writing reference, and the source for to-questionnaire.