Claude Code's Skills System

The first time someone encounters Claude Code often thinks of Skills as:

• A set of pre-written Prompts
• A Slash Command alias
• Or documentation stored in a repository

These understandings are partially accurate, but incomplete.

Looking at the source code, what Claude Code defines as a Skill is more precisely:

A set of skill modules that can be loaded by the system, detected by the model, and formally executed by SkillTool.

In other words, a Skill isn't an ordinary document. It has its own loading chain, discovery chain, and execution chain within Claude Code.

SKILL.md file > Parse frontmatter > Convert to command object > Enter available Skills list > Model decides whether to call > SkillTool executes

Claude Code already has many tools - so why create an entire separate Skills system?

It's because with many complex tasks, it's not "not enough tools" but rather that the model doesn't understand:

• What steps should this kind of task follow
• What rules does this team usually adhere to
• Which tools take priority in a specific scenario
• What pitfalls should be avoided beforehand

Take a very typical example:

• "Help me submit code" isn't just a simple command
• "Perform a security audit" isn't just a single-step action
• "Troubleshoot issues on production" is definitely not something that can be reliably completed with one prompt

What these tasks truly require is an entire workflow. And what Skills do is to formalize this kind of process.

The most common format for a Skill is SKILL.md. Claude Code first reads the frontmatter, then processes the main body content.

Commonly seen elements in frontmatter include:

• description
• whenToUse
• allowedTools
• model
• context
• hooks

The main text section contains specific operational instructions for this skill. You can think of it like:

• Frontmatter tells the system "what kind of skill this is"
• The main content explains to the model "exactly how this skill works"

The core file in the source code that handles this specific task is skills/loadSkillsDir.ts.

What it does isn't complicated, but it's very engineering-focused:

1. Scans multiple directories for skills
2. Finds each Skill's corresponding SKILL.md
3. Parses frontmatter
4. Converts it to an internal Command object
5. Adds it to the current session's list of available Skills

Scan skills directory > Read SKILL.md > Parse frontmatter > createSkillCommand > Generate prompt-type command > Add to Claude Code command system

You can see very straightforward sets of functions in the source code:

parseSkillFrontmatterFields(...)
createSkillCommand(...)
getSkillDirCommands(...)

The names for these clearly convey their logic:

• First parse fields
• Then create Skill's corresponding command
• Finally return this batch of commands

Thus, a Skill's identity within Claude Code isn't "additional attachment" but rather as first-class members in the command system.

getSkillDirCommands() will gather Skills from multiple locations.

You don't need to memorize specific paths - just understand priority order:

• Platform/strategy-delivered Skills
• User-specific Skills
• .claude/skills within the project
• Skills in additional specified directories
• Compatibility with earlier commands directory skill formats

This means Skills can be either:

• Officially built-in experiences
• Team-shared experiences
• Personal workflow tools
• Project-specific rules

That's also why it is much better than "ordinary Prompt collections." It was designed from the beginning not just for individuals, but with organization-scale reusability in mind.

Here's a particularly key design decision.

Many people might assume: Since Skills have already been loaded into memory, shouldn't Claude Code just send all Skill content to the model every single round?

It doesn't do that.

A more appropriate approach is:

• First expose only Skill names, descriptions, and applicable scenarios
• Let the model know "what Skills are available"
• Only when the model decides it's necessary does it then provide the full details

This separates "discovery" from "execution."

The source code makes this distinction very clear with:

• skill_discovery
• discoveredSkillNames
• invoked_skills

utils/messages.ts even directly turns Skill discovery into a system prompt:

`Skills relevant to your task:

${lines.join('
')}

` +
`These skills encode project-specific conventions. ` +
`Invoke via Skill("<name>") for complete instructions.`

This clearly states:

First, tell the model "these Skills relate to your current task." The full details will only be expanded once you invoke Skill(...).

You can think of this layer as a "recommended skills" system.

When Claude Code determines that the current task matches certain Skills, it doesn't simply dump the entire Skill text. Instead, it gives the model a concise notification:

• What's this Skill's name
• What kind of problems is it intended to solve
• If necessary, should invoke via SkillTool

Current Task > Skill discovery > Tell Model about available Skills' names and descriptions > Model decides whether to call SkillTool > Expand complete Skill content

This approach offers two clear benefits:

1. Saves context
2. Allows the model only to enter detailed Skill flows when truly needed

This is consistent with Claude Code's general design philosophy:

First expose a capability overview, then expand details on demand.

Skills don't run automatically on their own.
What actually handles executing them is tools/SkillTool/SkillTool.ts.

The tool's overall process can be broken down into five steps:

1. Locate the corresponding Skill by name
2. Validate whether it's a legitimate prompt-type command
3. Check permission rules
4. Expand the full content of the Skill
5. Decide whether to execute it inline or via fork

The two most critical points in the source code are very clear:

async function getAllCommands(context: ToolUseContext): Promise<Command[]> {
  const mcpSkills = context
    .getAppState()
    .mcp.commands.filter(
      cmd => cmd.type === 'prompt' && cmd.loadedFrom === 'mcp',
    )
  ...
}

This shows that when SkillTool searches for a Skill, it doesn't just look at local Skills—it also includes any Skills exposed via MCP in the search.

Another key point is:

async function executeForkedSkill(...) {
  ...
  for await (const message of runAgent({...})) {
    ...
  }
}

This indicates that when a Skill becomes genuinely complex, it doesn't necessarily run directly in the main thread; it can be forked into a sub-agent for execution.

This is the point worth remembering most about the Skills system.

It's typically how things work by default. This means:

• Skill content expands directly into the current main workflow
• After reviewing this set of instructions, the main agent continues working within the same context

Suitable for:

• Relatively lightweight workflows
• Simply supplementing a specific set of rules
• Tasks that don't require additional context isolation

This is where Claude Code Skills becomes truly interesting. Once a Skill gets complex enough, rather than polluting the current main workflow, it can:

• Spawn a new sub-agent
• Hand off the Skill's workflow to that sub-agent to run
• Return the results once the sub-agent finishes

Doing this brings very practical benefits:

• Keeps the main workflow's context cleaner
• Makes complex skills easier to isolate
• Prevents a wayward Skill from disrupting the entire main thread

So you'll realize that:

A Skill in Claude Code isn't just a "longer prompt," but rather "a workflow that can spawn a sub-agent for execution when needed."

This is a crucial question. If you temporarily draft a prompt, its characteristics are:

• Valid only for this session
• Must be rewritten next time
• The system has no idea what capability it represents

But a Skill is different. A Skill is:

• Persisted/saved
• Reusable
• Loadable by the system
• Discoverable by the model
• Formally executable by SkillTool

So you can think of it as:

• A prompt is a one-off instruction
• A Skill is an encapsulated workflow module

Because what Skills solve isn't "insufficient model capability," but rather "hard-to-reuse expertise." What many teams truly want to crystallize isn't a tool, but rather:

• How specific types of tasks should be approached
• What standards a particular repository must follow
• The sequence of steps in a given workflow
• Which tools to invoke in certain scenarios

Writing these down as documentation doesn't guarantee the model will proactively adhere to them.
But when turned into a Skill, the system can treat it as a formal capability.
That's where its real value lies.

One-sentence summary:

The Skills in Claude Code aren't just a few Markdown prompts, but a complete skill runtime: "first loaded, then discovered, ultimately executed by SkillTool."

Understanding this clarifies why Skills aren't an afterthought in Claude Code, but rather a core part of its platformized capabilities.