Claude Code Skills: How to Create, Install, and Use Custom Skills

71% of developers who use AI coding agents rely on Claude Code as their primary tool, according to the February 2026 Pragmatic Engineer survey of 15,000 developers. Yet almost none of them go beyond typing prompts. They paste the same testing checklist into every session. They re-explain their deployment process each time. They write long CLAUDE.md files that balloon into unreadable procedure manuals.

Claude Code skills solve this. A skill is a SKILL.md file that packages instructions Claude loads on demand, either when you invoke it with a slash command or when Claude detects it is relevant to your current task. Unlike CLAUDE.md content (which loads into every conversation), a skill's body only enters context when needed. You can bundle scripts, templates, and reference files alongside it.

The key distinction: CLAUDE.md is for facts about your project. Skills are for procedures. "Our API uses camelCase" belongs in CLAUDE.md. "Deploy to staging by running tests, building, and pushing to the target" belongs in a skill.

Claude Code skills follow the Agent Skills open standard at agentskills.io, which means the same SKILL.md file works across Claude Code, Gemini CLI, Cursor, Aider, Windsurf, and four other coding agents. Write once, use everywhere.

Every skill is a directory containing a SKILL.md file. The directory name becomes the slash command you type to invoke it. A skill at .claude/skills/deploy/SKILL.md creates the /deploy command.

The SKILL.md file has two parts: YAML frontmatter between --- markers, and markdown content with the instructions Claude follows.

---
description: Deploy the application to staging
disable-model-invocation: true
allowed-tools: Bash(npm *) Bash(git *)
---

### Deploy steps

1. Run the test suite with `npm test`
2. Build the application with `npm run build`
3. Push to the staging target
4. Verify the deployment health check passes

The description field is the most important piece of frontmatter. Claude uses it to decide when to load the skill automatically. If you ask "deploy my app" in a conversation, Claude scans all available skill descriptions and matches yours. A vague description like "does deployment stuff" triggers less reliably than "Deploy the application to staging or production. Use when the user asks to deploy, ship, or push to an environment."

The disable-model-invocation: true flag prevents Claude from triggering the skill on its own. Use it for anything with side effects: deployments, sending messages, or publishing releases. You want to control timing on those, not let Claude decide.

The allowed-tools field pre-approves specific tools so Claude can run them without asking permission each time. This is additive: it grants extra permissions for this skill, it does not restrict Claude from using other tools.

Where to store skills

Where you put a skill determines who can use it:

• Personal skills at ~/.claude/skills/<name>/SKILL.md work across all your projects
• Project skills at .claude/skills/<name>/SKILL.md apply to one project and can be committed to version control
• Plugin skills live inside a plugin directory and use a namespaced command like /plugin-name:skill-name
• Enterprise skills deploy organization-wide through managed settings

Personal overrides project when names collide. Both override bundled skills. If you create a code-review skill in your project, it replaces the built-in /code-review.

Start with a real problem. If you keep pasting the same instructions into Claude Code, that is your first skill.

Here is a practical example: a skill that reviews your uncommitted changes and flags risks before you commit.

First, create the directory:

mkdir -p ~/.claude/skills/review-changes

Then write the SKILL.md file:

---
description: Summarize uncommitted changes and flag risks. 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: missing error handling, hardcoded values, exposed secrets, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

The ! backtick syntax is dynamic context injection. Before Claude sees the skill content, Claude Code runs git diff HEAD and replaces that line with the actual output. Claude receives the rendered prompt with your real diff already inlined.

Test it two ways. Ask "what did I change?" and Claude should load the skill automatically based on the description match. Or type /review-changes to invoke it directly.

Adding supporting files

Skills can include more than just SKILL.md. Put templates, examples, and scripts alongside it:

review-changes/
├── SKILL.md
├── checklist.md
└── scripts/
    └── lint-diff.sh

Reference supporting files from SKILL.md so Claude knows when to read them:

For the full review checklist, see [checklist.md](checklist.md)

Claude loads supporting files on demand, not upfront. Keep SKILL.md under 500 lines and move detailed reference material to separate files to keep context costs low.

Store Your Skill Outputs Where Agents and Humans Collaborate

A shared workspace with built-in RAG, semantic search, and MCP server access. Your skills generate the files. Fast.io makes them searchable, shareable, and queryable. Starts with a 14-day free trial.

Start 14-Day Trial

The alirezarezvani/claude-skills repository on GitHub catalogs 345 production-ready skills across 17 domains, from engineering and DevOps to marketing, compliance, and C-level advisory personas. Each skill follows the Agent Skills standard, so installation works the same way regardless of source.

Install from the official marketplace using Claude Code's plugin system:

/plugin marketplace add alirezarezvani/claude-skills
/plugin install engineering-skills@claude-code-skills

The repository organizes skills into tiers. The core engineering tier includes 51 skills covering architecture, QA, DevOps, and security. The POWERFUL tier adds 78 more advanced skills for RAG pipelines, database design, CI/CD automation, and security auditing. Marketing gets 46 skills for SEO, CRO, growth, and sales enablement. There are even 66 C-level advisory personas that simulate executive perspectives on technical decisions.

Beyond installing full packages, you can also copy individual SKILL.md files directly into your project. Download the file, place it in .claude/skills/<name>/SKILL.md, and it is immediately available.

Evaluating skills before you trust them

Third-party skills can include allowed-tools that grant themselves broad permissions. Before installing a community skill into a shared project:

1. Read the SKILL.md frontmatter to check what tools it pre-approves
2. Look for dynamic context injection (! backtick commands) that run shell commands during skill load
3. Check if the skill uses context: fork to run in isolation or has access to your full conversation context

The skill-creator plugin from Anthropic's official marketplace automates evaluation. Install it with /plugin install skill-creator@claude-plugins-official, then ask Claude to evaluate any skill. It runs test cases in isolated subagents, grades assertions, benchmarks token usage, and compares with-skill versus without-skill performance.

Once you have basic skills working, three patterns unlock more powerful workflows.

Dynamic context injection The ! backtick syntax runs shell commands before Claude sees the skill content. This is preprocessing, not something Claude executes. Use it to pull live data into the prompt:

---
description: Summarize the current pull request
context: fork
agent: Explore
---

### Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

### Task
Summarize this pull request in three bullets.

For multi-line commands, use a fenced code block opened with triple backticks followed by !:

### Environment
```!
node --version
npm --version
git status --short

### Subagent execution with context: fork

Adding `context: fork` to frontmatter runs the skill in an isolated subagent. The skill content becomes the subagent's prompt. It does not see your conversation history. This is useful for research tasks, large code analysis, or anything you want sandboxed from your main session.

Pair it with the `agent` field to pick the execution environment:

- **Explore**: Read-only codebase search with Glob, Grep, and Read tools. Skips CLAUDE.md loading to keep context small
- **Plan**: Architecture-focused agent for designing implementation strategies
- **general-purpose**: Full tool access, same as the main session

You can also point `agent` at custom subagent configurations defined in `.claude/agents/`.

### Argument substitution Pass arguments to skills using `$ARGUMENTS` or positional `$0`, `$1`, `$2` placeholders:

```yaml
---
description: Migrate a component between frameworks
arguments: [component, source, target]
---

Migrate the $component component from $source to $target.
Preserve all existing behavior and tests.

Running /migrate-component SearchBar React Vue replaces $component with SearchBar, $source with React, and $target with Vue. Named arguments make the skill self-documenting compared to raw positional indexes.

Other substitution variables include ${CLAUDE_SESSION_ID} for the current session, ${CLAUDE_EFFORT} for the active effort level, and ${CLAUDE_SKILL_DIR} for the directory containing the SKILL.md file. Use ${CLAUDE_SKILL_DIR} to reference bundled scripts regardless of where the skill is installed.

Skills become more powerful when your agent's work persists between sessions. A skill that generates test reports, builds documentation, or scaffolds project structures needs somewhere to store its output. Local filesystems work for solo developers, but fall apart when multiple agents collaborate or when you need to hand results to a human teammate.

Cloud storage options like S3 or Google Drive handle file persistence, but they were not designed for agent workflows. They lack semantic search across stored files, built-in AI chat for querying document contents, and the ability to transfer workspace ownership from an agent to a human.

Fast.io addresses this gap as an intelligent workspace where agents and humans collaborate on the same files. When you upload a file, it is automatically indexed for semantic search and AI-powered Q&A through Intelligence Mode. An agent can create workspaces, populate them with skill-generated outputs, and transfer ownership to a human client or team lead, while retaining admin access.

For Claude Code specifically, Fast.io exposes a MCP server with Streamable HTTP at /mcp. Your skills can write outputs directly to Fast.io workspaces, where they become searchable, shareable, and queryable through built-in RAG. This closes the loop between skill execution and persistent collaboration.

Every org starts with a 14-day free trial, with storage, monthly credits, and workspaces scaled to each plan. For teams running multiple agents with specialized skills, the shared workspace model means every agent's output is visible to every team member without manual file transfers.

Skills that look correct in the editor can still fail in practice. These patterns cover the most common failure modes.

Skill does not trigger automatically. Claude matches skills by scanning descriptions for keywords that align with your prompt. If your description says "deploy to production" but you ask Claude to "push my changes live," the match may not fire. Write descriptions that include the phrases users actually say, not just the technical terminology. Test in a fresh session, since leftover context from authoring the skill can mask description gaps.

Skill triggers too often. Narrow the description or add disable-model-invocation: true to limit it to manual invocation only. For path-scoped skills, add a paths glob pattern so the skill only activates when working with specific files.

Skill descriptions get truncated. With many skills installed, Claude Code allocates a character budget (1% of the model's context window) for skill descriptions. Skills you invoke least get shortened first. Run /doctor to check which descriptions are affected. Trim description and when_to_use text to put the key use case first, since each entry is capped at 1,536 characters.

Skill content drifts after many turns. Once loaded, a skill's content stays in context for the rest of the session. Auto-compaction preserves the first 5,000 tokens of each invoked skill and re-attaches them after summarization, with a combined budget of 25,000 tokens across all active skills. If behavior drifts, re-invoke the skill to restore its full content.

Writing effective SKILL.md files

• Keep SKILL.md under 500 lines. Every line is a recurring token cost once loaded
• State what to do, not why. Explanations waste tokens on every invocation
• Put the most important instructions first. Auto-compaction keeps the first 5,000 tokens
• Use dynamic context injection for live data instead of asking Claude to run commands
• Bundle scripts in the skill directory and reference them with ${CLAUDE_SKILL_DIR}
• Test each skill in a fresh session, not the session where you wrote it