Master Claude Code Skills: Build, Organize, and Trigger Custom AI Assistants

What Are Skills?

A Skill is a Markdown file that teaches Claude Code to perform a specific task once; thereafter Claude can apply it automatically whenever the context matches, without slash commands or repeated explanations. Each Skill lives in a SKILL.md file whose frontmatter contains a name and description, followed by the concrete instructions.

---
name: pr-description
description: Use this skill when writing a pull request description to ensure it follows our team's template.
---
# PR Description Template
Always include these sections:
- **Summary**: What changed?
- **Testing**: How was it tested?
- **Screenshots**: If UI changes.

The description field is what Claude uses to decide whether to load the Skill. When you ask Claude to review a PR, it matches your request against available Skill descriptions; a successful match triggers loading the full Skill.

Where Skills Are Stored

Skills can be placed in two locations, each with a different scope:

Personal Skills are stored in ~/.claude/skills (Windows: C:/Users/<your-user>/.claude/skills) and travel with you across all projects.

Project Skills reside in the repository under .claude/skills. Anyone who clones the repo automatically receives them, making them ideal for team standards, review checklists, onboarding guides, or architecture references.

Each Skill has its own directory whose name matches the Skill name:

.claude/skills/
└──pr-description/
    └──SKILL.md

Creating Your First Skill

1. Create the directory:

mkdir -p ~/.claude/skills/pr-description

2. Add a SKILL.md file with frontmatter and the desired template:

---
name: pr-description
description: Use this skill when writing a pull request description.
---
Follow this format for all PR descriptions...

After adding a Skill, restart Claude Code so it rescans the Skills folder. Then simply say, “Write a PR description for my changes,” and Claude will load and apply the Skill.

Skill Metadata (Frontmatter)

The frontmatter supports four fields: name (required) – lowercase, hyphen‑separated, up to 64 characters. description (required) – up to 1,024 characters; used for matching. allowed-tools (optional) – restricts which tools the Skill may use. model (optional) – specifies the Claude model to run.

---
name: code-analyzer
description: Analyze the codebase for architectural patterns.
allowed-tools: [ls, grep, read_file]
---

Using allowed-tools is useful for read‑only workflows; the Skill can only invoke the listed tools and cannot modify files.

Writing Precise Descriptions

The description is the most critical field because it determines whether Claude will use the Skill. A good description answers two questions:

What does the Skill do?

When should Claude invoke it?

Include natural keywords you would use when asking for the task. If a Skill fails to trigger, add synonyms. For example, “when creating a PR, writing a PR, or summarizing changes” provides more matching opportunities than the generic “write PR description.”

Priority System

If two Skills share the same name, Claude resolves the conflict in this order (highest to lowest):

Enterprise

Personal ( ~/.claude/skills)

Project ( .claude/skills)

Plugins

This hierarchy lets organizations enforce enterprise‑wide standards while still allowing personal customization. Use descriptive names (e.g., frontend-review) to avoid collisions.

Organizing Complex Skills

All Skills share Claude’s context window, so stuffing everything into a single large file wastes tokens and becomes hard to maintain. Keep each SKILL.md under about 500 lines and place heavy reference material in separate files, loading them only when needed.

.claude/skills/architecture-guide/
├──SKILL.md
├──patterns.md
└──examples.sh

Inside SKILL.md, tell Claude when to read auxiliary files:

If the user asks about design patterns, read `patterns.md`.
If the user needs to see examples, run `examples.sh`.

Only the output of a script consumes tokens; the script itself is not loaded into the context.

Skills vs. Other Customization Options

CLAUDE.md – always loaded; ideal for global project standards (e.g., “always use strict TypeScript”).

Skills – loaded on demand when a request matches the description.

Hooks – event‑driven, such as running a linter every time Claude saves a file.

Subagents – run in isolated contexts, receive delegated tasks, and can have independent tool access.

Typical configurations combine them: CLAUDE.md for permanent rules, Skills for task‑specific expertise, Hooks for automation, and Subagents for delegated work.

Sharing Skills

Repository Commit : place Skills in .claude/skills and commit; anyone who clones the repo gets them—best for team standards.

Plugins : distribute via a marketplace when the Skill is not project‑specific but useful to the broader community.

Enterprise Settings : administrators deploy Skills organization‑wide; this has the highest priority and enforces compliance.

Skills and Subagents

Subagents do not automatically see your Skills. When you delegate a task to a Subagent, it starts with a clean context. Built‑in agents (Explorer, Plan, Verify) cannot access Skills at all. Custom Subagents defined under .claude/agents can, but you must list the required Skills in the Subagent’s frontmatter:

---
name: reviewer-agent
skills: [pr-description, security-audit]
---

These listed Skills are pre‑loaded when the Subagent starts, which differs from the on‑demand loading used in the main conversation.

Rule of Thumb

If you find yourself repeatedly explaining the same thing to Claude, it’s a strong candidate for a Skill. The cost to create one is low: write it once, and Claude will apply it automatically thereafter. Start with the topics you explained most often in the past week—that’s likely your first useful Skill.