Daniel’s Space
CTRL K

Claude Agent Skills

8 min read
aiclaude

Instead of repeating instructions every time you ask Claude to review a PR or write a commit message, you write a skill once and Claude applies it whenever the task comes up.

What Skills Are

Each skill lives in a SKILL.md file with a name and description in its frontmatter. The description is how Claude decides whether to use the skill. Claude reads your request, compares it to all available skill descriptions, and activates the ones that match.

---
name: pr-review
description: Reviews pull requests for code quality. Use when reviewing PRs or checking code changes.
---

Key takeaways:

  • Skills are folders of instructions that Claude Code can discover and use to handle tasks more accurately. Each skill lives in a SKILL.md file with a name and description in its frontmatter
  • Claude uses the description to match skills to requests. When you ask Claude to do something, it compares your request against available skill descriptions and activates the ones that match
  • Personal skills go in ~/.claude/skills and follow you across all projects. Project skills go in .claude/skills inside a repository and are shared with anyone who clones it
  • Skills load on demand — unlike CLAUDE.md (which loads into every conversation) or slash commands (which require explicit invocation), skills activate automatically when Claude recognizes the situation
  • If you find yourself explaining the same thing to Claude repeatedly, that’s a skill waiting to be written

A skill is a markdown file that teaches Claude how to do something once. Claude then applies that knowledge automatically whenever it’s relevant.

Where Skills Live

You can store skills in different places depending on who needs them:

  • Personal skills go in ~/.claude/skills (your home directory). These follow you across all your projects — your commit message style, your documentation format, how you like code explained.
  • Project skills go in .claude/skills inside the root directory of your repository. Anyone who clones the repo gets these skills automatically. This is where team standards live, like your company’s brand guidelines, preferred fonts, and colors for web design.

Skills Priority

There is a clear priority order:

  • Enterprise — managed settings, highest priority
  • Personal — your home directory (~/.claude/skills)
  • Project — the .claude/skills directory inside a repository
  • Plugins — installed plugins, lowest priority

To avoid conflicts, use descriptive names. Instead of just “review,” use something like “frontend-review” or “backend-review.”

Skills vs. CLAUDE.md vs. Slash Commands

  • CLAUDE.md files load into every conversation. If you want Claude to always use TypeScript’s strict mode, that goes in CLAUDE.md.
  • Skills load on demand when they match your request. Claude only loads the name and description initially, so they don’t fill up your entire context window. Your PR review checklist doesn’t need to be in context when you’re debugging — it loads when you actually ask for a review.
  • Slash commands require you to explicitly type them. Skills don’t. Claude applies them when it recognizes the situation.

When to Use Skills

Skills work best for specialized knowledge that applies to specific tasks:

  • Code review standards your team follows
  • Commit message formats you prefer
  • Brand guidelines for your organization
  • Documentation templates for specific types of docs
  • Debugging checklists for particular frameworks

The rule of thumb is simple: if you find yourself explaining the same thing to Claude repeatedly, that’s a skill waiting to be written.

Creating a Skill

mkdir -p ~/.claude/skills/pr-description
cd ~/.claude/skills/pr-description
touch SKILL.md

The name identifies your skill. The description tells Claude when to use it — this is the matching criteria. Everything after the second set of dashes is the instructions Claude follows when the skill is activated.

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---
 
When writing a PR description:
 
1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:
 
## What
One sentence explaining what this PR does.
 
## Why
Brief context on why this change is needed
 
## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

To test it, say something like: write a PR description for my changes. To update a skill, edit its SKILL.md file. To remove one, delete its directory. Restart Claude Code after any changes for them to take effect.

Skills Configuration

Skill Metadata Fields

  • name (required) — Identifies your skill. Use lowercase letters, numbers, and hyphens only. Maximum 64 characters. Should match your directory name.
  • description (required) — Tells Claude when to use the skill. Maximum 1,024 characters. This is the most important field because Claude uses it for matching.
  • allowed-tools (optional) — Restricts which tools Claude can use when the skill is active.
  • model (optional) — Specifies which Claude model to use for the skill.

A good description answers two questions:

  • What does the skill do?
  • When should Claude use it? If your skill isn’t triggering when you expect it to, try adding more keywords that match how you actually phrase your requests. The description is what Claude uses to decide whether a skill is relevant, so the language matters.

Restricting Tools with allowed-tools:

Sometimes you want a skill that can only read files, not modify them. This is useful for security-sensitive workflows, read-only tasks, or any situation where you want guardrails.

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

If you omit allowed-tools entirely, the skill doesn’t restrict anything. Claude uses its normal permission model.

Progressive Disclosure: Cramming everything into one 2,000-line file has two problems: it takes up a lot of context window space, and it’s not fun to maintain.

Progressive disclosure solves this. Keep essential instructions in SKILL.md and put detailed reference material in separate files that Claude reads only when needed.

The open standard suggests organizing your skill directory with:

  • scripts/ — Executable code
  • references/ — Additional documentation
  • assets/ — Images, templates, or other data files

A good rule of thumb: keep SKILL.md under 500 lines. If you’re exceeding that, consider whether the content should be split into separate reference files.

Use Scripts Efficiently Scripts in your skill directory can run without loading their contents into context. The script executes and only the output consumes tokens. The key instruction to include in your SKILL.md is to tell Claude to run the script, not read it.

Key takeaways

  • name and description are required — allowed-tools and model are optional but powerful additions
  • A good description answers two questions: What does the skill do? When should Claude use it?
  • allowed-tools restricts which tools Claude can use when the skill is active — useful for read-only or security-sensitive workflows
  • Progressive disclosure: keep SKILL.md under 500 lines and link to supporting files (references, scripts, assets) that Claude reads only when needed
  • Scripts execute without loading their contents into context — only the output consumes tokens, keeping context efficient

Skills vs. Other Claude Code features

A typical setup might include:

  • CLAUDE.md loads into every conversation and is best for always-on project standards. Skills load on demand and are best for task-specific expertise
  • Subagents run in isolated execution contexts — use them for delegated work. Skills add knowledge to your current conversation
  • Hooks are event-driven (fire on file saves, tool calls). Skills are request-driven (activate based on what you’re asking)
  • MCP servers provide external tools and integrations — a different category entirely from skills

Each handles its own specialty. Don’t force everything into skills when another option fits better — and you can use multiple at a time.

Sharing Skills

  • Project skills in .claude/skills are shared automatically through Git — anyone who clones the repo gets them. Works well for:
    • Team coding standards
    • Project-specific workflows
    • Skills that reference your codebase structure
  • Plugins let you distribute skills across repositories via marketplaces for broader community use
    • This approach is best when your skills aren’t too project-specific and can be useful to community members beyond your immediate team.
  • Enterprise managed settings deploy skills organization-wide with the highest priority, ideal for mandatory standards and compliance
  • Subagents don’t automatically see your skills — you must explicitly list skills in a custom agent’s frontmatter skills field
  • Built-in agents (Explorer, Plan, Verify) can’t access skills at all — only custom subagents defined in .claude/agents can
    • Custom subagents you define can use skills, but only when you explicitly list them
    • To create a custom subagent with skills, add an agent markdown file in .claude/agents.
    • You can use the /agents command in Claude Code to create one interactively
    • Skills are loaded when the subagent starts, not on demand like in the main conversation

Troubleshooting Skills

  • Start with the skills validator tool — it catches structural problems before you spend time debugging other things
  • If a skill doesn’t trigger, the cause is almost always the description — add trigger phrases that match how you actually phrase requests
  • If a skill doesn’t load, check that SKILL.md is inside a named directory (not at the skills root) and the file name is exactly SKILL.md
  • If the wrong skill gets used, your descriptions are too similar — make them more distinct
  • For runtime errors, check dependencies, file permissions (chmod +x), and path separators (use forward slashes everywhere)

Quick Troubleshooting Checklist

  • Not triggering? Improve your description and add trigger phrases.
  • Not loading? Check your path, file name, and YAML syntax.
  • Wrong skill used? Make descriptions more distinct from each other.
  • Being shadowed? Check the priority hierarchy and rename if needed.
  • Plugin skills missing? Clear cache and reinstall.
  • Runtime failure? Check dependencies, permissions, and paths.

Lesson Reflection

Think about your most recent interactions with Claude Code. Which instructions did you find yourself repeating? How might a skill have saved you time? Consider your team’s workflow. Which standards or processes would benefit most from being encoded as skills?

MIT 2026 © Daniel Guo.