How to Create a Claude Skill (or Any Agent Skill), Step by Step

Home > Learn > Create an Agent Skill

You create a Claude skill in six steps. Pick a repeated task, write test prompts, and make a folder holding a SKILL.md. An Agent Skill is a folder of instructions that an agent loads when a task matches its description. The SKILL.md file inside it holds a name, a description and the steps. A Claude skill is one instance of that open standard. The same folder works in Claude Code and other agents. Start with what Agent Skills are for the background.

Each step follows Anthropic's docs and the agentskills.io guides, checked on 2026-10-21. Each one maps to the evidence our verdicts use: baseline runs, trigger reliability and the safety grade.

No code? Let Claude draft it, as covered under "Can Claude create a skill for you without coding?".

How do you create a Claude skill?

You create a Claude skill in six steps. Pick a repeated task, write test prompts, and make a folder holding a SKILL.md. Add instructions, test against a no-skill baseline, then upload or share the skill.

1. Pick a repeated task. Claude Code's docs name the signal: you "keep pasting the same instructions, checklist, or multi-step procedure into chat". Anthropic's Academy gives a similar rule: you keep explaining the same thing repeatedly.
2. Write evaluations first. Anthropic's platform best practices ask for three scenarios before you write much. Run them once without any skill to get a baseline.
3. Create the folder and SKILL.md. The folder takes the skill's name. The file opens with a name and a description of what the skill does and when to use it. Each field rule is in the SKILL.md format, field by field.
4. Add instructions, references and scripts. Keep SKILL.md under 500 lines, per the Agent Skills specification and Claude Code's docs.
5. Test against a baseline in a fresh session. Claude Code's docs warn that leftover authoring context hides gaps.
6. Upload, commit or share the skill. Claude apps take a ZIP upload, Claude Code reads a folder, and teams share through repositories or plugins.

Claude drafts steps 3 and 4 on request. The next section covers that route and where it fails.

Can Claude create a skill for you without coding?

Yes, Claude can draft a skill for you from a chat description or Anthropic's skill-creator. Cowork on Mac can build one from a screen recording. Review every draft: our skill-creator verdict is Conditional, 57/100.

Three routes produce a skill with no code from you. Each one ends with a SKILL.md you still need to read.

Through conversation: Open a chat, describe the task and answer Claude's follow-up questions. Claude reads its own skill-creator skill and writes the SKILL.md. It adds code where the task needs it, then packages a skill file. To check it works, look for "Using [skill name]" in Claude's thinking, per the Help Center. The Academy tutorial gives the label as "Reading [skill name]" instead. Both labels appeared on Anthropic's pages on 2026-10-21.

skill-creator in Claude Code: Install it with /plugin install skill-creator@claude-plugins-official. Claude Code's docs say it stores tests in evals/evals.json and runs isolated subagents. It writes a benchmark.json comparing runs with and without the skill. It runs blind A/B comparisons and tunes descriptions. Anthropic's Complete Guide, built on its January 2026 model, says otherwise. It states that skill-creator "does not execute automated test suites or produce quantitative evaluation results". The two Anthropic sources disagree, and both were current on 2026-10-21.

Record a skill: Cowork in Claude for Mac turns a screen recording into a skill. The Help Center lists Pro, Max and Team plans. It excludes chat, Windows, Free and Enterprise. A recording runs about 10 minutes, and the video and audio are not retained.

Our review of Anthropic's skill-creator sits behind any of these routes:

The strength is the authoring loop: interview, draft, paired runs with and without the skill, and a review page. One user reported an 84% to 100% pass-rate lift on 41 assertions (community-reported). The weaknesses sit in the trigger-eval harness. Issues #1721, #1352 and #1412 report false negatives. Issue #1478 reports crashes counted as passes on negative queries. Issue #1412 reports 121 claude -p calls exhausting a Max plan in about 3 minutes. Windows users hit script failures on pipe reads and UTF-8 text. Pro users and anyone on tight usage limits are a poor fit, given the parallel claude -p fan-out. The full evidence is in Anthropic skill-creator: full verdict.

A draft is only as specific as your input. The agentskills.io best practices say to "start from real expertise". Feed Claude your own checklist, examples and past corrections. Generic prompts produce generic skills.

Third-party generators exist too, such as Skill Seekers. We name them here without a recommendation.

When is a workflow worth turning into a skill?

A workflow is worth turning into a skill when you explain it to Claude repeatedly. Good candidates need your own knowledge and have a clear trigger. One-off tasks stay prompts, and must-hold rules become hooks.

Signs a skill pays off:

• Repetition: the same instructions, checklist or procedure goes into chat again and again (Claude Code docs).
• Refinement: you found an approach that works and want Claude to reuse it (Academy tutorial).
• Materials: the task depends on specific templates, schemas or reference files (Academy tutorial).
• Setup: the job has several pieces that must come together the same way each time (Academy tutorial).

Anthropic's Complete Guide asks you to "identify 2-3 concrete use cases" before you build. It sorts skills into 3 categories: document creation, workflow automation and MCP enhancement. A document skill makes a report in your house style. A workflow skill runs a multi-step process such as a release checklist. An MCP enhancement skill teaches Claude how to use a connected tool well.

Signs a skill is the wrong tool:

• One-off tasks: the Academy tutorial says to "just prompt well" instead.
• Must-hold rules: Claude Code's docs move these into a hook, which runs on every matching event.
• Live data: access to an outside system belongs to an MCP server; see skills vs MCP: which to use.
• Simple tasks: agents consult skills only for work beyond what they handle alone (agentskills.io).

The best source for a skill is a task you just finished. Anthropic's best practices call this "Complete a task without a Skill". Do the task with Claude, correct it as you go, then capture the steps that worked. The Complete Guide says the same thing in its own words: "iterate on a single challenging task" first.

How do you build a skill step by step?

Build a skill step by step from one folder you name after the skill. Write a SKILL.md with a name, a trigger-rich description, numbered steps and one example. Move long reference material into separate files, then test it.

The worked example below is ours: writing-release-notes, a skill that turns merged pull requests into customer-facing notes. It uses only fields from the Agent Skills specification. That choice lets the same folder load in Claude Code, upload to Claude and work in other clients.

1. Create the folder where your agent scans for skills. Claude Code reads ~/.claude/skills/writing-release-notes/ for personal skills. Other agents read .agents/skills/writing-release-notes/. The folder name matches the skill's name.
2. Write the frontmatter with spec fields only. Claude Code-only keys break uploads elsewhere.
3. Write the description in third person, as Anthropic's best practices advise. Name what the skill does and when it applies, using words people type, such as "changelog".
4. Write the body as numbered steps, one input and output example, and the edge cases.
5. Move detail out. Tone rules go in references/STYLE.md, linked straight from SKILL.md, one level deep.
6. Add a script only for deterministic work. A script caps the best possible safety grade at B; see how a script changes the safety grade.
7. Try it with a matching request such as "Draft release notes for this week". In Claude Code, /writing-release-notes calls it directly.

writing-release-notes/
├── SKILL.md
├── references/
│   └── STYLE.md
└── scripts/
    └── list_merged_prs.sh

---
name: writing-release-notes
description: Writes customer-facing release notes from merged pull requests, grouped by New, Improved and Fixed. Use when the user asks for release notes, a changelog entry or a "what's new" summary.
---

# Writing release notes

1. Run scripts/list_merged_prs.sh to list pull requests merged since the last tag.
2. Group each change under New, Improved or Fixed.
3. Rewrite each title in customer language. Drop internal ticket IDs.
4. Follow the tone rules in references/STYLE.md.

## Example
Input: "Fix null pointer in invoice export (#4512)"
Output: "Fixed: invoice exports no longer fail on empty fields."

The script lists merged pull requests, and Claude sees only its output, not its code. The platform docs describe this split: scripts run, and only the result enters context. Each field, plus a fully annotated file, is in every frontmatter field and an annotated example.

What mistakes stop a new skill from working?

Six mistakes stop a new skill from loading or triggering. Anthropic's Complete Guide and Claude Code's docs name each one.

The Help Center differs on two of these rows. Its custom-skills article writes the file as skill.md and allows "Brand Guidelines" as a name. The Complete Guide and the specification are stricter. Use SKILL.md and a kebab-case name to meet the stricter rule.

Where do you create a skill: Claude, Claude Code or another agent?

Create a skill in Claude Code when you want versioned files on disk. Use the Claude app to upload a ZIP or let Claude draft it. Use .agents/skills/ when other agents need the same skill.

Anthropic's own pages disagree on the upload location in Claude apps. The Help Center's skills article says "Customize > Skills". The create-through-conversation article and the Complete Guide say "Settings > Capabilities > Skills". The platform overview says "Settings > Features". Check each path in your own app.

Plans differ too. The Help Center lists Free through Enterprise. The platform overview lists "Pro, Max, Team, and Enterprise" only. Both pages were live on 2026-10-21.

Portability depends on the frontmatter. Spec-only frontmatter works everywhere, per Claude Code's docs. Claude Code-only fields make uploads to Claude apps and the API fail. The app route has a full guide: turn skills on and upload them in the Claude app. The terminal route, with every folder location, is in add skills to Claude Code.

How do you test a skill you are developing?

Test a skill you are developing for triggering and for output quality. Run realistic prompts with the skill and without it, each in a fresh session. Anthropic's checklist asks for at least three evaluations.

Triggering tests whether the skill loads on the right prompts and stays out of the wrong ones. The agentskills.io guide on descriptions sets the method:

• Write about 20 queries: 8 to 10 that must trigger and 8 to 10 near-misses that must not.
• Run each query 3 times and compute a trigger rate.
• Count a rate above 0.5 as a pass for queries meant to trigger.
• Split the queries 60/40 into training and validation sets before you tune the description.

The Complete Guide sets a target of triggering on 90% of relevant queries, tested with 10 to 20 queries. It labels that target aspirational. In Claude apps, check Claude's thinking for the skill's name, as the "Using" or "Reading" label shows.

Output quality tests whether the skill beats the same prompt run without it. The agentskills.io guide on evaluating skills starts small:

• Write 2 to 3 realistic test cases, each with a prompt and an expected output.
• Store them in evals/evals.json next to the skill.
• Run each case with the skill and without it.
• Compare the two outputs against the expected result.

{
  "skill_name": "writing-release-notes",
  "evals": [
    {
      "id": 1,
      "prompt": "Draft release notes for everything merged since v2.3.0",
      "expected_output": "Notes grouped under New, Improved and Fixed, in customer language, with no internal ticket IDs",
      "files": []
    }
  ]
}

Anthropic's best practices add 3 rules. Build at least three evaluations. Test on Haiku, Sonnet and Opus, because a skill that guides Opus can under-guide Haiku. Use two sessions: Claude A helps you write the skill, and Claude B uses it on real tasks. You bring Claude B's misses back to Claude A. For plugin skills, claude plugin eval runs the checks and gates CI, per Claude Code's docs.

What our verdicts check that home tests often miss (how we score skills):

• Effectiveness: the gain over a no-skill baseline.
• Trigger reliability: whether the skill loads when it applies.
• Instruction weight: the tokens it costs against the value it adds.
• Safety grade: what its scripts and network calls can do.
• Maintenance: whether the publisher fixes reported bugs.

Test tools need checking as well. Skill Creator's own trigger-eval detector scores 15 for measurement validity in our verdict. At commit 8a1541c it reports recall of 0% in many setups (repository-confirmed). Check trigger numbers by hand before you rewrite a description to fit them.

The selection logic behind these tests is in how Claude picks which skill to run. For a skill that still won't load, read when a new skill won't trigger.

The skill works and passes its tests. Check it the way a reviewer does before anyone else installs it.

How do you publish and share a skill you created?

Share a skill you created through a repository, a Claude Code plugin, or Claude's Team and Enterprise sharing. Public skills go on GitHub so others can install them. Run a pre-publish check first.

Claude Code offers 3 sharing routes. Commit the skill to the project's .claude/skills/ folder in git. Bundle it in a plugin's skills/ folder. Push it to a whole organisation through managed settings. Claude apps on Team and Enterprise plans add Share, Publish to org and Provision, per the Help Center.

Public skills live in a GitHub repository. The Complete Guide puts a human README at the repository root, outside the skill folder. The folder itself holds no README.

Anthropic's pages disagree about sharing in Claude apps. The platform overview calls claude.ai custom skills "Individual user only". The Help Center documents sharing on Team and Enterprise plans. The Complete Guide dates organisation-wide deployment to 2025-12-18. We found no official channel for selling skills in Anthropic's docs as of 2026-10-21.

Run this 8-item check before anyone else installs the skill:

The secrets row maps to our safety grades: a skill with hidden endpoints or telemetry earns an F. The full reviewer routine is in how reviewers vet a skill before installing it. Registries and marketplaces such as skills.sh list public skills. Our own index of reviewed skills is linked in the FAQ.

Which courses teach you to create Agent Skills?

Two free courses teach you to create Agent Skills from the official side. Anthropic Academy's Introduction to agent skills runs six lessons in one hour. DeepLearning.AI's Agent Skills with Anthropic has ten video lessons.

• Anthropic Academy, Introduction to agent skills: free per its course page on academy.claude.com, 6 lessons, 1 hour.
• Anthropic Academy, Claude Code 101: a Skills lesson, number 10 of 12.
• DeepLearning.AI, Agent Skills with Anthropic: free, beginner level, 2 hours 19 minutes, 10 video lessons.
• agentskills.io quickstart: a written walk-through of the first skill folder.

The older anthropic.skilljar.com listing marks the Academy course as not free. The academy.claude.com page listed it as free on 2026-10-21.

Common questions

Do you need to code to create a Claude skill?

No. Simple skills are Markdown files, and Claude writes any scripts the task needs.

How long does a first skill take to create?

Anthropic's Complete Guide estimates 15 to 30 minutes for a first skill built with skill-creator.

How long should a SKILL.md file be?

Keep it under 500 lines, per the specification.

Is there a SKILL.md template?

Yes. Anthropic's skills repository on GitHub holds template/SKILL.md, and we explain a ready-made SKILL.md template field by field.

Where can you find Claude skill examples?

Anthropic's skills repository on GitHub holds official examples. Our index lists skills already reviewed, file by file.

Can a Claude skill include code?

Yes, in a scripts/ folder, and only the script's output enters context. Any script changes the safety grade a skill can earn.

Can you edit a skill after you create it?

Yes. Claude apps let you edit with Claude beside the chat, and Claude Code reloads an edited folder live.

Why doesn't my new skill trigger?

Usually the description lacks the words users type. Our guide shows how to fix a skill that doesn't trigger.