Where do I put skill files?

The most common locations are .github/skills/ /SKILL.md for project-level skills and .claude/commands/ .md for slash-command skills. The exact location depends on how you want to trigger them.

Can I share skills with other developers?

Yes. Skills are plain Markdown files, so they can be shared as gists, GitHub files, or on platforms like PasteBox. Remove any project-specific paths or secrets before sharing so the skill is reusable by others.

How do auto-trigger patterns work?

In your CLAUDE.md you list a skill name and a pattern, for example: "use the code-review skill whenever a diff is reviewed." Claude Code reads this and applies the skill when the condition is met during a session.

How long should a skill file be?

A well-written skill is usually 50 to 200 lines. Long enough to be precise, short enough to stay focused. If a skill covers too many cases, split it into two narrower skills.

Claude Code Skills Guide — How to Write and Share Agent Skills

Claude Code skills are reusable instruction files that give the agent deep, focused context for a specific task. Instead of keeping all agent guidance in a single CLAUDE.md, you split specialized tasks into separate SKILL.md files and trigger them when needed. This keeps each piece of context concise and task-specific.

A skill is just a Markdown file. It describes what the skill does, when to use it, what steps to follow, and what the expected output looks like. The agent reads it the same way a human reads a brief — as a focused set of instructions for a particular job.

Skill file structure

There is no enforced schema, but a practical skill file covers four things:

Trigger: When should this skill activate?
Goal: What is the agent trying to accomplish?
Steps: What actions should it take, in what order?
Output: What does a good result look like?

# Code Review Skill

## Trigger
Use this skill whenever you are asked to review a pull request diff.

## Goal
Find real bugs, missing test coverage, and safety issues.
Do not flag style issues that the linter handles automatically.

## Steps
1. Read the full diff before commenting on any part.
2. Identify changes with security implications (user input, auth, secrets).
3. Check that error paths are handled.
4. Verify that new behavior is covered by tests.
5. List findings with: file, line range, severity (high/medium/low), and fix suggestion.

## Output format
Group findings by file. Lead with the highest-severity items.
Include a one-line summary at the end: X high, Y medium, Z low.

Where to put skill files

Two locations are common:

.github/skills/<name>/SKILL.md — project-level skills that live in the repository and are version-controlled with the code
.claude/commands/<name>.md — slash-command skills that appear in the Claude Code command menu

For personal skills that should apply across all your projects, you can keep them in ~/.claude/ on your machine.

Auto-trigger in CLAUDE.md

Skills can be triggered manually or automatically. To trigger one automatically, list the condition in your CLAUDE.md:

## Skills (.github/skills/)
- code-review — auto: any PR diff, code review request
- web-research — auto: new package, unfamiliar API, external service
- release-checklist — auto: deploy, release, ship
- nextjs-conventions — auto: Next.js, App Router, middleware

When Claude Code sees a message that matches the pattern, it loads the skill file as additional context before responding.

Practical skill examples

Release checklist

# Release Checklist Skill

## Trigger
Use when the user mentions deploying, shipping, or releasing.

## Steps
1. Confirm all tests pass: npm run test
2. Confirm no type errors: npm run type-check
3. Check for uncommitted changes: git status
4. Verify the CHANGELOG or release notes are updated.
5. Confirm environment variables are set on the target environment.
6. Run the deploy command and monitor the first request logs.

Keyword research skill

# Keyword Research Skill

## Trigger
Use when starting SEO planning for a new page or site.

## Steps
1. Identify the primary user intent: informational, navigational, or transactional.
2. Find 3 to 5 head terms with clear search intent.
3. Find 10 to 20 long-tail variants with lower competition.
4. Group keywords by intent cluster, not by similarity.
5. Prioritize keywords where the page can rank in the top 5 within 6 months.

Sharing skills

Skills are shareable because they are plain text. Before sharing, check that the file contains no private paths, internal hostnames, client names, or credentials. A skill that references /home/yourname/projects/client-x will not work for anyone else, and it leaks information about your setup.

Generic skills — code review, release checklist, documentation generation, keyword research, API integration patterns — translate well across projects. Team-specific skills — migration workflows, internal tool conventions, custom deploy steps — usually need editing before they are useful to others.

Shared skills improve faster than private ones. When teams compare approaches, they find which steps are unnecessary, which output formats are more useful, and which trigger conditions avoid false positives. Contributing to a shared library of skills is the same value exchange as contributing to shared libraries of code.

FAQ

What is a Claude Code skill?

A reusable SKILL.md file that gives Claude Code detailed, focused instructions for a specific task. Skills are loaded as context when triggered, so the agent gets precise guidance without cluttering your main CLAUDE.md.

What is the difference between a skill and a slash command?

Slash commands are invoked manually by typing /skill-name in the chat. Skills can also auto-trigger based on patterns defined in CLAUDE.md. Both use the same Markdown format.

How long should a skill be?

50 to 200 lines is a reasonable range. Precise enough to be useful, focused enough to stay relevant. If a skill covers too many different situations, split it.