How to Create a Claude Skill: SKILL.md From Idea to Paste

Claude skills load when your task matches the skill description in SKILL.md front matter. Creating one means turning a job idea into front matter, a thin body, linked reference files, trigger tests, and a paste into Claude Code or claude.ai. This how to create a claude skill guide covers that path in five steps with description triggers and progressive disclosure. For terminal test loops see claude-code-skills-guide; for format anatomy see anthropic-skills-format. Scaffold at https://promptmake.net/claude-skill-generator when blank files stall you. PromptMake generates text only and does not upload to Anthropic. You leave with a create checklist, trigger rules, and an FAQ.

Before you create a claude skill: pick one job

A skill should cover one primary outcome you repeat weekly: release notes from git, incident postmortem shape, API changelog draft, design critique against house rules, or staging migration checklist. If the job runs once per year, skip the skill and use a one-off chat.

Write three sentences offline before you open any editor. Sentence one: outcome in plain language. Sentence two: who asks and what words they type. Sentence three: hard fences such as no production deploy without ticket id, no invented CVE numbers, ask when branch name is missing.

Confirm where the skill will live. Claude Code project skills travel with the repo. Personal skills sit in user config paths Anthropic documents for your OS. claude.ai skills use the product builder when your plan exposes skills. This guide focuses on SKILL.md content that works across hosts; verify install steps on Anthropic help pages for your version.

One skill, one job. Two overlapping skills with vague descriptions cause wrong loads. Split release cuts from hotfix recovery before you write front matter.

Jobs that fit skills versus CLAUDE.md notes

Use CLAUDE.md for always-on repo facts: stack, test command, directory map. Use a skill when the same multi-step playbook should load only on matching asks. If guidance runs every session regardless of task, CLAUDE.md is enough.

Use a skill when steps exceed what you want in every context window: phased checklists, linked templates, script references, output contracts with headers.

If two jobs share eighty percent of rules but different output shapes, make two skills with narrow descriptions instead of one mega file.

Access and safety prep

List commands the skill must never run without approval: force push, drop table, production kubectl apply. Name them in fences before you paste steps.

Remove secrets from drafts. Reference environment variable names only. Point to internal wikis for token values.

Pick an owner who approves description trigger edits in pull requests. Skills rot when triggers change without tests.

Step 1: Turn your idea into a skill outline

Open a blank doc. Header: Skill name (kebab-case), Primary user phrases, Output contract, Files to link later.

Primary user phrases are what teammates actually type: "draft release notes for 2.4," "write postmortem from this thread," "audit OpenAPI against style guide." These phrases feed the description trigger in step 2.

Output contract lists required sections in every result: Version, Highlights, Breaking changes, or Subject, Customer reply, Internal note. Models skip headers when you omit the contract.

Files to link later holds reference markdown, templates, and optional scripts. Plan progressive disclosure now so SKILL.md stays under roughly 250 lines at v1.

Optional: paste your three-sentence seed into https://promptmake.net/claude-skill-generator for a first SKILL.md scaffold. Edit every command, path, and fence before commit.

Outline template you can copy

Name: release-notes. User phrases: release notes, changelog draft, version summary from git. Output: Version, Date, Highlights, Breaking, Contributors link. Linked files: references/commit-types.md, templates/changelog-section.md. Fences: never invent issue numbers; ask for tag range when missing.

Name: incident-postmortem. User phrases: postmortem, incident writeup, blameless summary. Output: Summary, Timeline, Impact, Root cause, Action items. Linked files: templates/postmortem.md. Fences: no customer PII in paste; redact before upload.

Keep outlines in the ticket until SKILL.md passes trigger tests. Outlines are cheap; wrong triggers are expensive.

Step 2: Write front matter and description triggers

Create a folder named after the skill. Add SKILL.md with YAML front matter between triple-dash lines. Required public fields include name and description. Name matches the folder: release-notes, incident-postmortem, openapi-audit.

The description field is the trigger surface. Claude compares user prompts to descriptions and loads matching skills. Triggers are semantic, not exact regex. Precise descriptions reduce false loads.

Write description in third person or imperative mood as Anthropic docs suggest. Include verbs (audit, scaffold, summarize, cut, migrate), artifacts (CHANGELOG, OpenAPI, SKILL.md), and scope boundaries (TypeScript packages under /packages, not hotfix unless user says hotfix).

Good description example: "Use when the user asks for release notes, changelog draft, or version bump summary from git history. Covers conventional commits and compare links. Do not use for legal filings or support macros."

Weak description: "Helps with git and writing." That loads on unrelated asks.

Keep description to one or two sentences that a new hire would recognize as their task. Move step detail to the body.

Description trigger checklist

Include at least three phrases your team actually uses in Slack or tickets.

Add one "Do not use for …" boundary when overlap with another skill is likely.

Avoid internal codenames only engineers know unless you also list plain-language synonyms.

After every description edit, rerun five prompts that should load and five that should not.

Name field conventions

Use kebab-case consistent with repo folders: release-notes, staging-migration, design-critique.

Match folder name and name field so paths and triggers stay grep-friendly.

Do not embed version numbers in skill names; version the folder in git instead.

Step 3: Build the body with progressive disclosure

Below front matter, write markdown sections the agent can follow in order. Recommended shape: When to use, When not to use, Steps, Output contract, Fences, Examples, Linked files.

When to use mirrors positive triggers in prose. When not to use catches adjacent tasks that should stay in generic Claude mode.

Steps are numbered actions: ask for inputs, run read-only commands, draft sections, request approval before destructive actions.

Fences name refusals and approvals: never delete branches without confirm, never cite pricing not in linked docs, stop when git log is empty and say Unknown.

Examples show one happy path user ask and one missing-info path. Missing-info teaches the agent to ask for ticket id instead of guessing.

Progressive disclosure means SKILL.md is the map, not the library. Move long policy tables, style guides, and sample outputs into references/ or templates/ and link with relative paths: "See references/commit-types.md for house types."

Claude opens linked files when the task needs depth. Keeping SKILL.md thin saves context for repo files and chat.

Tier 1: SKILL.md entry file

Tier 1 holds triggers restated briefly, step overview, output contract, fences, and links. Target under 250 lines for v1.

Critical safety rules stay in Tier 1 even if examples live elsewhere. Do not hide "no production deploy" only in references/policy.md.

Tier 2: references and templates

references/ holds policy, glossaries, long tables. templates/ holds paste-ready section stubs. Link each file twice: once in Steps, once in Linked files list at bottom.

Filename by purpose: references/api-style.md beats references/misc.md.

Split when a section exceeds one screen, when policy updates monthly but steps stay stable, or when non-technical reviewers edit references without touching triggers.

Tier 3: optional scripts

scripts/ may hold lint, collect, or format helpers when Claude Code execution allows. Document "run only after user confirms range" in Steps.

Review scripts for network calls and deletes before merge. Require explicit user confirmation in the body for destructive commands.

Step 4: Test description triggers before paste

Build a trigger matrix: rows are user phrases, columns are skills, cells are should-load yes or no. Run the matrix in Claude Code or claude.ai after every description edit.

Pass criteria: zero false positives on your negative list before you chase false negatives. False loads burn trust faster than missed loads.

Paraphrase tests matter. Teammates rarely type your internal jargon. Include plain-language variants in description if real asks use them.

Log results in a test markdown in the repo: prompt, expected skill, loaded yes/no, pass/fail, date. Rerun the log when Anthropic updates skill behavior or your repo moves paths.

Four-pass loop from claude-code-skills-guide still applies: happy path, missing input, adjacent non-load task, one edge case from a past incident. Add failed edge cases to Examples when fixes land.

False positive fixes

Narrow description verbs when the skill loads on generic coding asks.

Add "Do not use for …" in description and When not to use body.

Split mega-skills into two folders with separate triggers.

False negative fixes

Add synonyms teammates use in tickets: changelog versus release notes, postmortem versus incident writeup.

Verify another skill is not stealing triggers with a broader description.

Step 5: Paste into Claude and maintain

For Claude Code: copy the skill folder into the project or personal skills path your team documented. Confirm Claude Code lists the skill in help output or settings if your version exposes that.

For claude.ai: follow Anthropic builder steps to create or upload skill content when your plan supports skills. Field names change; verify live UI labels before a team rollout.

Commit SKILL.md with the code it affects. Same pull request for release process change and release-notes skill update.

Announce skill name and trigger summary in team chat when v1 passes tests. Silent drops break trust when descriptions change.

Quarterly review: run three prompts from the test log, fix stale commands, archive skills that no longer match the repo. Stale skills that still load are worse than none.

When you onboard hires, point them at skill folder README listing name, trigger summary, and owner.

Scaffold drafts on PromptMake claude-skill-generator

Blank SKILL.md stalls teams. PromptMake https://promptmake.net/claude-skill-generator turns your three-sentence job seed into structured markdown: front matter, purpose, steps, fences, example blocks, and placeholder links for references/.

Workflow: paste seed, generate once, replace placeholder commands with real scripts, narrow description, add references/ files, run trigger matrix, commit.

Honest limits: the generator does not create folders on disk, does not register skills in Anthropic products, and does not run your test log. You own install paths, trigger tuning, and local verification.

For cross-platform standing config, the main https://promptmake.net/skills hub also drafts Claude, Custom GPT, and Gemini Gem shapes. This article stays on how to create a claude skill with SKILL.md specifically.

Guests receive about three runs per day on skills generator paths; registered free accounts receive about five. Quotas are separate from /text and /image tools.

Common mistakes when you create a claude skill

Mistake 1: Generic description triggers that load on every coding ask.

Mistake 2: Essay-length SKILL.md with no linked references.

Mistake 3: Two skills with overlapping descriptions in one repo.

Mistake 4: Secrets or live tokens in examples.

Mistake 5: No missing-info example, so the agent guesses branch names and ticket ids.

Mistake 6: Assuming PromptMake uploaded the skill because markdown was generated.

Mistake 7: Duplicating the same deploy rules in CLAUDE.md and three skills with conflicting wording.

Mistake 8: Skipping trigger tests after a one-word description edit.

How this guide differs from related articles

Claude-code-skills-guide goes deep on Claude Code paths, four-pass terminal testing, and project versus personal skill directories. Anthropic-skills-format explains description triggers and progressive disclosure as format spec with router and reference skill shapes. How-to-use-claude-skills covers install and day-to-day use after skills exist.

This how to create a claude skill page is the create path: idea, outline, front matter, body tiers, test, paste. Read claude-code-skills-guide next when your draft is ready for local Claude Code verification.

PromptMake product pages may target claude skill creator phrasing for transactional intent. This blog article targets the how-to query without competing for that head term.

FAQ

What do I need before I create a claude skill?

You need one repeating job, three sentences describing outcome and fences, a chosen host (Claude Code project path, personal path, or claude.ai builder when available), and a test list of prompts that should and should not load the skill. You do not need Anthropic marketplace access or a published skill store listing. PromptMake drafts text; you paste and test locally.

What belongs in SKILL.md front matter?

At minimum name and description. Name is a short identifier matching the folder. Description is the trigger sentence listing tasks and scope boundaries. Optional fields may appear in Anthropic docs over time; verify against your Claude version when you upgrade. Keep description specific with verbs and artifacts, not praise.

How do description triggers work when I create a claude skill?

Claude compares user prompts to each skill description and loads matching skills into context. Triggers are semantic matches, not exact keywords. Write descriptions with real task phrases, synonyms, and "Do not use for …" boundaries. Rerun a trigger matrix after every description edit to catch false positives and false negatives.

What is progressive disclosure in a claude skill?

Progressive disclosure keeps SKILL.md thin as an entry map and moves long policy, templates, and scripts into linked files under references/, templates/, and scripts/. Claude loads deeper files when the task needs them. Critical fences stay in SKILL.md even when examples live elsewhere.

Can PromptMake create a claude skill for me?

PromptMake https://promptmake.net/claude-skill-generator drafts SKILL.md markdown you copy into your skill folder. It does not upload to Anthropic or install in Claude Code. Guests get about three runs per day on skills paths; free accounts about five. Edit commands, paths, and triggers to match your repo before commit.

How is this different from claude-code-skills-guide?

Claude-code-skills-guide focuses on Claude Code file layout, load paths, and terminal test loops. This page walks from job idea through front matter, body tiers, trigger testing, and paste for any Claude skill host. Use both: create here, then deep-test in Claude Code with the other guide.

How is this different from anthropic-skills-format?

Anthropic-skills-format is a format reference for triggers, progressive disclosure tiers, and skill shapes like router versus workflow. This how-to adds step order, outline templates, trigger matrix habits, and paste maintenance. Read format spec for anatomy; read this page when you ship your first skill the same day.

What is the fastest path to a working claude skill?

Pick one weekly chore. Write three sentences offline. Generate scaffold at https://promptmake.net/claude-skill-generator if helpful. Create folder with SKILL.md, narrow description, add one references/ file, run five positive and five negative prompts, commit with your next related code change.