How Does Claude Code Detect the Skills You’ve Been Using for Months?

What Problems Skills Solve

CLAUDE.md holds project‑wide facts and long‑lived rules such as code style, directory conventions, and common commands. Skills are for reusable, trigger‑based workflows that are not needed every round, like a code‑review checklist, PR‑summary process, UI‑acceptance checklist, or TDD workflow.

Code‑review checklist

Online‑issue troubleshooting steps

PR‑summary flow

UI‑acceptance specifications

TDD workflow

Putting these long, task‑specific processes into CLAUDE.md inflates the initial context and wastes tokens.

How to Write SKILL.md

A file‑system Skill typically lives under .claude/skills/ and follows this directory layout:

.claude/skills/
  pr-summary/
    SKILL.md
    scripts/
      collect-pr-info.sh
    references/
      review-checklist.md

SKILL.md

consists of two parts:

YAML front‑matter that describes name, description, allowed tools, model, effort, etc.

Markdown body that contains the actual instructions sent to Claude when the Skill is invoked.

Minimal example:

---
name: pr-summary
description: Summarize a pull request and list key risks
allowed-tools: Bash(gh *)
---

Read the pull request diff and comments, then summarize:
1. Main changes
2. Risky files
3. Missing tests
4. Suggested follow‑up

When you run /pr-summary, Claude Code renders the Skill into a prompt and passes it to the model.

How Claude Code Finds Skills

Skills are loaded from several locations:

User‑level: ~/.claude/skills/ (shared across projects)

Project‑level: .claude/skills/ (team‑specific)

Managed Skills (organization‑wide policy directory)

Bundled Skills built into Claude Code (e.g., /code-review, /debug, /loop)

Plugin‑provided Skills

MCP‑provided Skills from remote servers

Each Skill resides in a directory named after the skill with a SKILL.md file. The loader expects the exact .md file; a plain .md without the required structure is ignored.

What Happens When a Skill Is Invoked

Only the front‑matter (name, description, when_to_use) is loaded initially. The full body is fetched on demand. The processing chain is:

Expand argument placeholders like $ARGUMENTS or $0.

Replace ${CLAUDE_SKILL_DIR} with the skill’s directory path.

Replace ${CLAUDE_SESSION_ID} with the current session identifier.

If the source is not an MCP Skill, execute any embedded shell commands.

Return the final prompt to the model.

Dynamic commands are executed before the prompt reaches Claude, so the model only sees the rendered result, not the command itself.

Dynamic Context and Security Limits

Skills can embed dynamic context using syntax such as:

Current Git status:
!`git status --short`

or a fenced code block:

```
!git log --oneline -5
```

Only read‑only, low‑risk commands should be placed here. Commands that modify files, commit changes, or delete resources are prohibited.

MCP‑provided Skills are treated as untrusted; their embedded shell is skipped unless the skill originates from a trusted local source. All commands must pass the allowed-tools whitelist.

Enterprise environments can enforce strictPluginOnlyCustomization to restrict skill loading to plugins, managed settings, or built‑in capabilities, preventing user‑level or project‑level files from being loaded.

How Skills Work with Agents

Skills can run inside a Subagent by setting front‑matter fields:

context: fork
agent: Explore
allowed-tools: Bash(gh *)

This is useful when the skill is long, needs many files, or the main session only cares about the final result. Scenarios include PR risk summaries, read‑only code audits, documentation aggregation, and migration planning.

Agent Teams load CLAUDE.md, MCP servers, and all Skills, which adds extra context overhead. To keep overhead low, write clear description fields, keep long bodies in supporting files, use disable-model-invocation for manual‑only skills, and consider strictPluginOnlyCustomization for large teams.

Conclusion

Think of a Skill as an on‑demand operation manual. Keep always‑required rules in CLAUDE.md. Move task‑specific, reusable workflows to Skills, and place lengthy checklists, templates, or scripts in supporting directories ( references/, templates/, scripts/). If a section of CLAUDE.md feels like a handbook, it probably belongs in a Skill.