Claude Code Skills Explained

Claude Code Skills are reusable markdown files that act as custom slash commands. Drop a file into .claude/commands/ and every team member gets the same workflow when they type the slash command.

Skills solve the biggest problem teams hit after adopting Claude Code: inconsistency. One developer writes great prompts. Another gets garbage. Skills close that gap by packaging the good prompt once and sharing it through the repo.

This guide covers how Claude Code Skills work, the difference between project and user skills, how CLAUDE.md fits in, and practical patterns for teams shipping skills today.

What Claude Code Skills actually are

A Claude Code Skill is a markdown file stored in your repo or home directory. The filename becomes the slash command. A file named deploy-check.md becomes /deploy-check.

The markdown body is the prompt that Claude Code follows when someone invokes the command. You can include frontmatter to declare which tools the skill can use, add a description, or restrict behavior.

Skills are not plugins or compiled code. They are plain text instructions that Claude Code reads at invocation time. This means anyone who can edit markdown can create or update a skill.

• Project skills live in .claude/commands/ inside your repo.
• User skills live in ~/.claude/commands/ and work across all projects.
• The filename minus .md becomes the slash command name.
• Frontmatter supports allowed-tools, description, and model fields.

How skills differ from CLAUDE.md

CLAUDE.md is your persistent project context. Claude Code reads it automatically on every session. It sets coding standards, architecture rules, and project-specific constraints that apply to all work.

Skills are on-demand commands for specific tasks. They run only when someone invokes them. A skill might deploy to staging, run a security audit, or generate a changelog. CLAUDE.md tells Claude Code how your project works. Skills tell it what to do right now.

The two work together. CLAUDE.md sets the baseline rules. A skill can build on those rules for a focused task. For example, CLAUDE.md might say all code uses TypeScript strict mode. A skill for adding API endpoints inherits that rule without restating it.

• CLAUDE.md runs automatically. Skills run on demand.
• CLAUDE.md sets project-wide rules. Skills define specific tasks.
• Child CLAUDE.md files in subdirectories extend the parent.
• Skills inherit CLAUDE.md context when they run.

How to create Claude Code Skills

Create a .claude/commands/ directory in your repo if it does not exist. Add a markdown file with a clear, verb-first name like review-pr.md or generate-migration.md.

Start the file with optional YAML frontmatter between triple dashes. The description field appears in autocomplete when users type a slash. The allowed-tools field restricts which tools the skill can access. Then write the prompt body as plain markdown.

A real example: a deploy-check skill might say: Read the current git diff against main. Check for console.log statements, hardcoded secrets, and missing tests. Report each issue with file path and line number. Run the type checker and report errors. The skill captures your team's deploy checklist in a format Claude Code can execute.

• Use verb-first filenames: review-pr.md, not pr-stuff.md.
• Keep the prompt body under 500 words for reliable execution.
• Use allowed-tools to prevent skills from running destructive commands.
• Test the skill on a known repo state before sharing.

Project skills vs user skills

Project skills in .claude/commands/ travel with your repo. Every team member who clones the repo gets the same skills. This is the right choice for team workflows like deploy checks, code review checklists, and project-specific generators.

User skills in ~/.claude/commands/ are personal. They work in every project but are not shared through version control. Use these for personal productivity commands like summarize-diff, format-commit-message, or quick-test.

When a project skill and user skill share the same name, the project skill wins. This lets teams override personal habits with team standards.

• Project skills: shared via git, team-standard, version-controlled.
• User skills: personal, cross-project, not in version control.
• Project skills override user skills with the same name.
• Subdirectory skills use slash notation: /subdir/skill-name.

Practical skill patterns for teams

The deploy-gate pattern runs your full pre-deploy checklist: lint, type check, test suite, secret scan, and changelog diff. One slash command replaces a five-step manual process.

The content-workflow pattern generates a draft, then spawns a subagent to audit it against your style guide and SEO rules. The skill produces both the content and the audit report in one run.

The onboarding pattern walks a new developer through the repo: explains the folder structure, identifies key files, summarizes recent commits, and generates a starter task list. This replaces hours of tribal knowledge transfer.

The incident-response pattern reads error logs, identifies the likely root cause, drafts a fix, and generates the postmortem template. It does not deploy the fix. A human reviews and ships.

• Deploy gate: lint, type check, test, secret scan, changelog.
• Content workflow: draft, audit, and report in one command.
• Onboarding: repo tour and starter tasks for new hires.
• Incident response: diagnose, draft fix, generate postmortem.

Sharing and versioning skills across a team

Because project skills live in .claude/commands/, they go through the same pull request process as any other code change. A new skill or skill update gets reviewed before it merges to main.

This review step matters. A skill shapes agent behavior for everyone on the team. A poorly written skill can generate bad code, skip tests, or ignore constraints. Treat skill PRs like you treat changes to CI configuration.

Version your skills with your repo. Tag releases so you can roll back a skill that causes problems. Add a brief comment header to each skill explaining its purpose, author, and last review date.

• Skills go through code review like any other file.
• Use PR descriptions to explain what the skill does and why.
• Tag releases so skills can be rolled back.
• Add a comment header with purpose, author, and review date.

Advanced skill features

Skills can spawn subagents for parallel work. A code-review skill might launch one agent to check security, another to check performance, and a third to check style. Each runs independently and reports back.

Skills can accept arguments using $ARGUMENTS in the prompt body. A generate-page skill might take a slug and keyword as arguments: /generate-page pricing-guide "ai pricing". Claude Code substitutes the values into the prompt.

You can also define custom agent types in .claude/agents/ with their own model, tools, and instructions. Skills can then reference these agent types for specialized work.

• Use $ARGUMENTS for parameterized skills.
• Spawn subagents from skills for parallel work.
• Define custom agent types in .claude/agents/ for specialized roles.
• Chain skills by having one skill invoke another.

Governing Claude Code Skills at scale

Every skill needs an owner. Without one, skills rot. The deploy-check skill from six months ago might miss your new infrastructure requirements.

Audit skills quarterly. Check whether each skill still matches the current process, uses the right tool restrictions, and produces the expected output. Retire skills that no longer apply.

For regulated industries, document which skills run in production workflows and what guardrails they enforce. Skills are auditable because they are plain text, but only if someone actually reviews them.

• Assign an owner to every skill.
• Audit skills quarterly against current processes.
• Document production-critical skills for compliance.
• Retire outdated skills rather than leaving them to confuse new hires.