Claude Code skills: how to create them, with examples and best practices

What Claude Code skills are

Make a skill when you keep pasting the same instructions, checklist or multi-step procedure into chat, or when part of your CLAUDE.md has grown from a fact into a procedure. Skills follow the open Agent Skills standard (agentskills.io), which other AI tools also read; Claude Code adds extras such as invocation control, subagent runs and live shell output in the prompt.

• Two ways to run one: Claude loads it when your request matches its description, or you type /skill-name.
• Cheap until used: only the name and description sit in context; the body loads when the skill runs. A skill set to run only by hand doesn't list its description at all.
• Custom slash commands are skills now: .claude/commands/<name>.md still works, but a skill folder can also hold supporting files. See Claude Code slash commands.
• Claude Code ships bundled skills too, such as /simplify, /loop, /batch and /debug.

Skills vs CLAUDE.md vs subagents vs plugins vs MCP

How to create a Claude Code skill

1. Pick where it lives

   ~/.claude/skills/<name>/ for yourself in every project; .claude/skills/<name>/ in a repository, committed, for everyone who works there. The folder name becomes the command, so summarize-changes gives /summarize-changes.

2. Write SKILL.md: a description, then instructions

   Frontmatter goes between --- lines at the very top. Only description is recommended: put the use case and the words people would actually say first. Below it, write the instructions in Markdown. A line starting with ` !command ` runs that command first and pastes the output in, so the skill works from your real state.

   ---
   description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
   ---
   
   ## Current changes
   
   !`git diff HEAD`
   
   ## Instructions
   
   Summarize the changes above in two or three bullet points, then list any
   risks such as missing error handling, hardcoded values or tests to update.

3. Test both ways

   Start claude in a git project with an uncommitted edit. Ask "What did I change?" to see whether Claude picks the skill up by itself, then type /summarize-changes to run it directly. Skills you add during a session load on their own; run /reload-skills if one doesn't appear.

4. Decide who may run it

   Add disable-model-invocation: true for anything with side effects, such as deploys or sending messages, so only you can start it. Add user-invocable: false for background knowledge only Claude should load. Pass input with $ARGUMENTS, as shown in the slash commands guide.

5. Share it

   Commit .claude/skills/ to the repository, or package skills as a plugin for several repositories or teams.

Source: Claude Code docs, Extend Claude with skills

Claude Code skill examples

1. A reference skill that loads only for matching files

   Reference skills hold conventions Claude applies while it works. paths limits automatic loading to files that match the globs.

   ---
   description: API design conventions for this codebase. Use when writing or reviewing HTTP endpoints.
   paths: ["src/api/**"]
   ---
   
   When writing API endpoints:
   - Use RESTful names and plural resources
   - Return errors as { error: { code, message } }
   - Validate the request body with the schemas in src/api/schemas/

2. A task skill with supporting files

   Keep SKILL.md short and point to the rest. Claude reads checklist.md only when SKILL.md tells it to, and runs bump.sh without reading it, so the details cost nothing until needed.

   release/
   ├── SKILL.md          # the steps, and when to read the other files
   ├── checklist.md      # loaded only when SKILL.md points Claude to it
   └── scripts/
       └── bump.sh       # run, not read into context

3. A skill that runs in its own subagent

   context: fork starts a subagent (here the read-only Explore type) with the skill as its prompt. It doesn't see your conversation, so the instructions must stand alone; it runs in the background unless you set background: false.

   ---
   description: Audit dependencies for known vulnerabilities and outdated majors
   context: fork
   agent: Explore
   disable-model-invocation: true
   ---
   
   Run the package manager's audit, list every high or critical finding with the
   fix version, and report which majors are behind. Don't change any files.

Installing skills from plugins and marketplaces

Skills other people wrote usually arrive inside plugins. Claude Code registers Anthropic's official marketplace (claude-plugins-official) the first time you start an interactive session; browse it with /plugin, or install directly, for example /plugin install skill-creator@claude-plugins-official. For a team or community marketplace, add it first with /plugin marketplace add owner/repo.

• Plugin skills are named /plugin-name:skill-name.
• The official marketplace shows each plugin's context cost per turn and when invoked.
• The skill-creator plugin helps write a skill and runs evals that compare results with and without it.
• Read a repository's or plugin's skills before you trust them: allowed-tools can pre-approve tools for the turn a skill runs.

Best practices, and when Claude ignores a skill

• Write the description for matching: lead with the job and the phrases users say. Description plus when_to_use is cut off at 1,536 characters in the listing.
• Put the most important instructions near the top: after the conversation is compacted, Claude Code may keep only the start of an invoked skill. Invoke it again to restore it.
• Word guidance for the whole task ("run the tests after every edit"), because the skill file isn't re-read on later turns. A rule that must never be skipped belongs in a hook.
• To cut token usage, move procedures out of CLAUDE.md into skills, set disable-model-invocation: true on skills you run by hand, and check /skill-doctor for skills that cost context but are rarely used.
• Not triggering? Check the description has the right keywords, ask "What skills are available?", and run claude plugin validate .claude/skills to find frontmatter that doesn't parse.
• Triggering too often? Make the description narrower, or switch the skill to manual with disable-model-invocation: true.

Skills teach Claude Code how. Crewmark gives it something to do every hour.

A library of skills makes each session capable, but it still waits for you to ask. Crewmark turns a Claude Code, Codex, DeepSeek Harness or OpenCode session into an AI employee with a role, a goal and working hours, and wakes it on a heartbeat to take the next issue from a board, with your project's skills loaded.

1. Keep skills in the repository

   The employee's session reads .claude/skills/ and CLAUDE.md like yours, so a release skill or a review checklist comes along.

2. Let the heartbeat start the work

   During its working hours the employee wakes every 15, 30 or 60 minutes in the same conversation and takes the next issue; see how to make Claude Code proactive.

3. Assign issues and answer its messages

   Put work on the board; the employee comments as it goes and messages you when it needs a decision. Read what an AI employee is.

Claude Code skills FAQ