Claude Code Skills Guide: File Layout, Triggers & Testing

Claude Code skills are folder-based instruction packs Claude Code can load when your task matches the skill description. Each skill lives in its own directory with a SKILL.md file at the root. The description field in that file acts as a trigger: when you ask for work the description covers, Claude Code pulls the skill into context and follows the rules inside. This guide explains what claude code skills are for, how to lay out SKILL.md, how description triggers work, how to test locally before you rely on a skill in production, and when to scaffold a first draft at https://promptmake.net/claude-skill-generator. PromptMake outputs markdown you copy into your repo. It does not install skills inside Claude Code or run tests for you.

What Claude Code skills are and when to use them

Skills teach Claude Code repeatable workflows: deploy checks, test conventions, internal CLI wrappers, doc formats, and team fences around dangerous commands. They differ from one-off chat instructions because they persist in the project or user skills directory and load only when the description trigger matches.

Use claude code skills when the same guidance would otherwise be pasted every session. Lint rules for a monorepo. Steps to cut a release branch. A standard template for incident writeups. A safe path to run database migrations in staging. Skip skills for rare one-time tasks you will never repeat. Skip them when a short CLAUDE.md note is enough and you do not need conditional loading.

Claude Code reads skills from configured paths on your machine. Personal skills apply across projects. Project skills travel with the repo so teammates inherit the same pack when they clone. As of mid-2026 Claude Code pairs with Claude Fable 5 and Claude Opus 5 model tiers depending on your plan. Skills do not replace model choice; they shape behavior once the model is active.

Think of skills as specialized playbooks the agent discovers by intent. You write the playbook once in SKILL.md. You describe when it should activate in the description trigger. You test with real prompts until loading feels reliable without over-triggering on unrelated asks.

SKILL.md file layout that Claude Code expects

Every skill is a folder. The required file is SKILL.md at the folder root. Optional supporting files can sit beside it: example configs, small scripts, templates, or reference markdown. Keep the folder focused on one job. A skill named "release-cut" should not also cover frontend design reviews.

SKILL.md opens with YAML front matter between triple-dash lines. Required fields include name and description. The name is a short identifier. The description is the trigger sentence Claude Code uses to decide whether to load the skill. Body markdown below the front matter holds instructions, steps, fences, and examples.

A minimal layout looks like this in concept: front matter with name and description, then sections for Purpose, When to use, Steps, Fences, and Examples. You do not need those exact headings, but your teammates should recognize the shape in thirty seconds.

Long skills should move reference material into sibling files and link from SKILL.md. "See examples/test-template.md" beats a 2,000 line single file that burns context when loaded. Claude Code loads the skill folder; keep SKILL.md as the map, not the entire library.

Front matter: name and description triggers

The name field should be kebab-case or snake_case consistent with your repo: release-cut, run-staging-migration, write-incident-postmortem. Avoid cute names that hide the job. Teammates search by function when triggers misfire.

The description field is the most important line in the file. It must say what task activates the skill and what scope the skill covers. Good description: "Cut a release branch, update changelog sections, and open a draft PR following team release policy." Weak description: "Helps with git stuff."

Write descriptions in third person or imperative mood as Anthropic docs suggest, and include verbs your team actually types: deploy, migrate, lint, scaffold, audit. Synonyms matter because users will not memorize your internal codename.

Keep description length honest. One or two sentences that name the task beat a paragraph of vague praise. If two skills overlap in description, merge them or narrow triggers until only one should load per ask.

Body sections: steps, fences, and examples

Purpose states the outcome in one paragraph. When to use lists signals that should load the skill versus when to stay in generic Claude Code mode. Steps are numbered actions the agent should follow in order. Fences name commands not to run, files not to touch, or approvals required before proceed.

Examples show a sample user ask and the shape of a good result. One happy path and one missing-info path is enough for v1. Missing-info examples teach the skill to ask for branch name or ticket ID instead of guessing.

Link optional assets explicitly: "Copy tests/fixtures/release-notes-stub.md when changelog section is empty." Relative paths from the skill folder keep clones portable.

How description triggers load skills in Claude Code

Claude Code evaluates available skills against your prompt. When the description semantically matches the task, the skill loads into context for that turn or session segment. Triggers are soft matches, not regex gates. Clear descriptions improve precision. Vague descriptions cause wrong loads or no loads.

Over-triggering happens when descriptions are too broad: "Helps with code" will load on every ask. Under-triggering happens when descriptions omit common verbs: a release skill that never says "changelog" may miss when a PM asks to "prep the weekly release notes."

Personal skills and project skills can coexist. Project skills should win for repo-specific workflows. Personal skills suit your private tooling preferences. Document load order expectations in your team wiki if both layers exist.

Updating a description is cheaper than rewriting the whole body when tests show misfires. Change one trigger phrase, restart the test prompt set, and log results. Version SKILL.md in git like any other source file.

Tuning triggers without breaking unrelated tasks

Build a test list of ten prompts: five should load the skill, five should not. After each description edit, rerun the list in Claude Code and note false positives and false negatives. Aim for zero false positives before you optimize false negatives.

Add negative scope in the description when needed: "For release cuts only, not hotfix cherry-picks unless user says hotfix." The model reads that line during trigger evaluation.

Split skills when triggers fight. Release cuts and hotfix recovery belong in separate folders with separate descriptions. One mega-skill with a long description paragraph loads too often.

Project skills vs personal skills paths

Project skills live under the repo so CI and teammates share them. Personal skills live in the user config path Claude Code documents for your OS. Use project skills for team law. Use personal skills for preferences that should not be committed.

When onboarding, point new hires at the project skills directory README if you maintain one. List each skill name, trigger summary, and owner for updates.

Testing claude code skills before you trust them

Testing is manual and prompt-driven in most setups. You run real Claude Code sessions with scripted asks and observe whether the skill loaded, whether steps were followed, and whether fences held. Automate later if you build wrappers; day one is human review.

Create a test log markdown in the repo or team wiki. Columns: prompt, expected skill, loaded yes/no, pass/fail, notes. Run the log after every SKILL.md edit. Skills rot when descriptions change but tests do not rerun.

Test missing inputs. A release skill should ask for version number when absent. A migration skill should refuse production when the user did not name staging. Fences only work if examples teach the refusal path.

Test destructive commands in dry-run language first. "Show me the commands you would run" before "run the deploy." Confirm the skill surfaces approval steps when your fences require them.

Local test loop in four passes

Pass 1: Happy path with all parameters provided. Confirm steps match SKILL.md order. Pass 2: Missing one required input. Confirm the agent asks instead of inventing. Pass 3: Adjacent task that should not load the skill. Confirm generic Claude Code answers without forcing the playbook. Pass 4: Edge case from last incident. Add that case to Examples if the skill failed.

Record screen or transcript snippets for failed passes. Fix SKILL.md, not the user prompt, when the skill should have loaded but did not. Fix description triggers before you add body length.

When a skill passes four passes, tag the commit and announce in team chat. Skills are team interfaces; silent changes break trust.

CI and repo hygiene for skill folders

Commit SKILL.md with the code it affects. If release steps change, update the skill in the same PR. Add a PR checklist item: "Does this change need a skill or SKILL.md update?"

Optional lint: script that verifies front matter keys exist and description length is within team max. Fail CI on missing name or empty description.

Keep secrets out of skills. Reference environment variable names, never values. Point to your vault docs for tokens.

Scaffold SKILL.md drafts with PromptMake

Blank SKILL.md files stall teams. PromptMake https://promptmake.net/claude-skill-generator turns a rough job description into structured skill markdown: front matter, purpose, steps, fences, and examples. Guests get about three runs per day. Free accounts get about five. Paste output into your skill folder and edit paths, commands, and fences to match your repo.

Honest limits: the generator does not create folders on your disk, does not register skills in Claude Code, and does not run your test log. You own git paths, description tuning, and local verification.

Practical path: write three sentences about the repeating Claude Code job offline. Generate once. Replace placeholder commands with your real scripts. Narrow the description trigger. Run the four-pass test loop. Commit when false positives are zero.

For Gemini Gems or GPT custom instructions, use other PromptMake scaffolds. This article and CTA stay on claude code skills and SKILL.md layout.

Common claude code skills mistakes

Mistake 1: Empty or generic description triggers. Fix the description before adding body length.

Mistake 2: One mega-skill for unrelated jobs. Split by outcome.

Mistake 3: Steps that reference missing files in the skill folder. Add assets or fix links.

Mistake 4: No fences around destructive shell commands. Name approvals explicitly.

Mistake 5: Never rerunning tests after a description edit. Treat SKILL.md like code.

Mistake 6: Committing secrets or internal URLs that should stay private. Redact and use env vars.

Mistake 7: Duplicating the same guidance in CLAUDE.md and three skills with conflicting wording. Pick one source of truth.

Mistake 8: Assuming PromptMake installed the skill because markdown was generated. You still copy files and test in Claude Code.

Skills vs CLAUDE.md and other instruction files

CLAUDE.md or project-level agent notes set baseline repo context: stack, test command, directory map. Skills load conditionally for specialized workflows. Put always-on facts in CLAUDE.md. Put repeatable playbooks in skills with tight descriptions.

Cursor rules and other editor hooks may overlap. Avoid duplicating conflicting deploy instructions in three places. Link from CLAUDE.md to skill names when teammates should know a skill exists.

When a workflow runs every session, consider CLAUDE.md only. When it runs sometimes, prefer a skill so context stays smaller on unrelated tasks.

Maintain skills as your repo evolves

Schedule a quarterly skill review the same week you review dependencies. Open each SKILL.md, run three prompts from the test log, and fix stale commands. Deprecated scripts cause silent skill failure faster than model drift.

Assign an owner per skill folder for PR review. Owners do not need to write every line; they approve trigger and fence changes.

Archive skills by moving folders to an _archived path or deleting with git history intact. Stale skills that still load are worse than no skill.

When Claude Code ships UI changes, re-read Anthropic docs for path or front matter updates. This guide describes mid-2026 patterns; verify field names if your CLI version differs.

FAQ

What are claude code skills?

Claude code skills are folder-based instruction packs for Claude Code. Each skill has a SKILL.md file with YAML front matter and markdown body. The description field in front matter acts as a trigger so Claude Code loads the skill when your task matches. They teach repeatable workflows like releases, migrations, and doc formats without pasting the same rules every chat.

What belongs in SKILL.md front matter?

At minimum name and description. The name identifies the skill folder. The description tells Claude Code when to load the pack. Keep description specific with verbs and scope. Optional fields may appear in Anthropic docs over time; verify against your Claude Code version when you upgrade.

How do description triggers decide when a skill loads?

Claude Code compares your prompt to each skill description and loads matching skills into context. Triggers are semantic, not exact keyword regex. Precise descriptions reduce wrong loads. Test with prompts that should and should not activate the skill after every description edit.

How should I test claude code skills locally?

Build a prompt list with happy path, missing-info, negative control, and one incident-derived edge case. Run each prompt in Claude Code and log whether the skill loaded and followed steps. Rerun the list after every SKILL.md change. Add failed edge cases to Examples when fixes land.

Can PromptMake write claude code skills for me?

PromptMake https://promptmake.net/claude-skill-generator drafts SKILL.md structure you paste into your repo. It does not install skills in Claude Code or run tests. Guests get about three runs per day; free accounts about five. Edit commands, paths, and fences to match your project before commit.

Should I use a skill or CLAUDE.md for the same rules?

Put always-on repo context in CLAUDE.md. Put conditional playbooks in skills with tight description triggers so unrelated tasks stay lean. Do not duplicate conflicting deploy steps in both places. Link skill names from CLAUDE.md when teammates need a map.

How is this guide different from general Claude prompting articles?

General Claude prompting covers chat patterns with Claude Fable 5 or Claude Opus 5 in the browser. This claude code skills guide covers SKILL.md layout, triggers, and test loops inside Claude Code. Use those articles for one-off asks; use this page when you package team workflows as loadable skills.

What is the fastest path to my first working skill?

Pick one weekly Claude Code chore. Draft three sentences offline. Generate scaffold markdown at https://promptmake.net/claude-skill-generator if helpful. Create a folder with SKILL.md, narrow the description, add steps and fences, run the four-pass test log, commit with your next related PR.