Agent skills in Claude Code: teach once, apply everywhere

Claude Code sessions accumulate repeated instructions quickly. A PR review gets the same checklist. A commit gets the same message format. A project gets the same architecture notes, naming conventions, and testing expectations.

Agent skills turn that repeated guidance into reusable task knowledge. A skill is written once, stored as markdown, and loaded only when the current request matches its description.

What a skill actually is

At its simplest, a skill is a folder containing a SKILL.md file with two parts: frontmatter and body. The frontmatter gives the skill a name and description. The description matters most because Claude uses it to decide when the skill applies.

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR or summarizing changes.
---

When writing a PR description:
1. Run `git diff main...HEAD` to see all changes
2. Write a description following this format:
   - **What**: One sentence explaining what this PR does
   - **Why**: Context on why this change is needed
   - **Changes**: Bullet points of specific changes

No registry or build step is required. A markdown file in the right directory is enough.

Where skills live

Two locations matter day to day:

• ~/.claude/skills/ — Personal skills that follow a developer across projects: commit message formats, explanation preferences, and document templates.
• .claude/skills/ — Project skills committed to a repo: team coding standards, brand guidelines, and project-specific workflows.

Enterprise deployment and plugin-based distribution cover organization-wide standards and shared community packages.

How matching works

Claude Code does not load every skill into every conversation. At startup, it scans available skills and reads their names and descriptions. The full instructions stay on disk until a request matches.

When a request comes in, Claude compares it against the available descriptions using semantic matching — intent overlap, not just keyword matching. “Review this PR” matches a skill described as “Reviews pull requests for code quality.” “Write a commit” matches a skill described as “Formats git commits following conventional commit standards.”

This keeps the context window focused. A debugging session does not carry the weight of a PR review checklist until the task actually calls for review behavior.

Skill priority hierarchy

When multiple skills share the same name, priority determines which one wins:

A personal “code-review” skill shadows a project one with the same name. Use descriptive, unique names (“frontend-review”, “backend-review”) to avoid unintended shadowing.

Beyond the basics

A few features make skills more useful in real repositories.

allowed-tools restricts what Claude can do when a skill is active. A codebase-onboarding skill with allowed-tools: Read, Grep, Glob, Bash can explain a repository without modifying files.

Progressive disclosure keeps SKILL.md short. Detailed reference material, validation checklists, and architecture guides can live in references/ subdirectories. Claude reads those files only when needed. Scripts in scripts/ execute without loading their source into context; only the output costs tokens.

---
name: codebase-onboarding
description: Helps new developers understand how the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Skills vs. everything else

Claude Code has several customization surfaces. Each fits a different persistence pattern.

They are complementary. A typical setup uses CLAUDE.md for global standards, skills for task expertise, hooks for automated checks, and subagents for isolated delegation.

A real example

A production skill for mirroring courses from an LMS into a static offline library starts with a narrow trigger:

---
name: download-course
description: Mirror Anthropic Skilljar courses. Use when needing to download,
  rebuild, refresh, debug, or validate a Skilljar course mirror.
---

The body contains the workflow: run discovery first, download lessons, handle cache invalidation, validate output against a checklist, and troubleshoot common failures like stale cookies, DOM changes, and broken asset links. Every request to download a course gets the same procedure instead of relying on someone to remember the flags.

Sharing skills

Skills become more valuable when shared across a team:

• Git repository — Commit to .claude/skills/ so the repo carries its own task knowledge.
• Plugins — Package skills for distribution across projects and community marketplaces.
• Enterprise managed settings — Deploy mandatory standards organization-wide.

Troubleshooting in 30 seconds

Most skill problems fall into predictable categories:

• Skill does not trigger — The description needs trigger phrases that match real requests.
• Skill does not load — SKILL.md must sit inside a named skill directory, not at the skills root.
• Wrong skill activates — Similar descriptions need sharper boundaries.
• Personal skill is ignored — A higher-priority skill with the same name may be shadowing it.
• Changes are not reflected — Skills are scanned at startup, so restart Claude Code.

Start with the pain point

The best skills come from repeated friction. A commit message skill, PR description template, or code review checklist is enough for a useful first pass.

Start with one task that already repeats. Put the skill in ~/.claude/skills/, restart Claude Code, and let the next matching request prove whether the description is specific enough.

Takeaways