how-skills-work.md

How Claude Code Implements Skills

This document explains how the Skills system works in Claude Code, based on analysis of the Skill tool documentation and observed behavior.

Overview

Skills are a mechanism for injecting domain-specific knowledge and instructions into Claude's context at runtime. They don't execute code directly—instead, they provide detailed guidance that Claude follows when performing tasks.

Architecture

The Skill Tool

The Skill tool is defined with a simple interface:

{
  "properties": {
    "skill": {
      "description": "The skill name. E.g., \"commit\", \"review-pr\", or \"pdf\"",
      "type": "string",
      "required": true
    },
    "args": {
      "description": "Optional arguments for the skill",
      "type": "string",
      "required": false
    }
  }
}

Skill Naming Convention

Skills use a namespaced naming convention:

<plugin-name>:<skill-name>

Examples:

• document-skills:xlsx
• document-skills:docx
• frontend-design:frontend-design

Skills can be invoked using either:

• Short name: xlsx, pdf
• Fully qualified name: document-skills:xlsx

Skill Locations

Each skill has a location attribute indicating where it comes from:

• plugin - Loaded from Claude Code's plugin system

Skills are cached locally at:

~/.claude/plugins/cache/<org>/<plugin-name>/<hash>/<plugin-name>/<skill-name>/

Example:

/home/user/.claude/plugins/cache/anthropic-agent-skills/document-skills/0f77e501e650/document-skills/xlsx

How Skills Work

1. Registration

Skills are registered in the system prompt under <available_skills>. Each skill entry contains:

• name: The fully qualified skill name
• description: When to use this skill
• location: Where the skill comes from

2. Invocation

When the Skill tool is called:

1. Claude Code locates the skill by name
2. Loads the skill's content from its cache directory
3. Returns the skill content as the tool result

3. Context Injection

The skill's output is injected into Claude's context as the tool result. This typically includes:

• Base directory: Where supporting files (scripts, templates) are located
• Requirements: Standards and constraints for outputs
• Workflows: Step-by-step processes to follow
• Code examples: Reference implementations
• Best practices: Domain-specific guidance

4. Execution

Claude then uses its standard tools (Bash, Write, Edit, etc.) to complete the task, following the injected instructions.

Invocation Triggers

Skills can be invoked in two ways:

Slash Commands (User-Initiated)

Users can explicitly invoke skills using slash command syntax:

/xlsx
/pdf
/frontend-design

Automatic (Claude-Initiated)

Claude is instructed to invoke relevant skills automatically:

"When a skill is relevant, you must invoke this tool IMMEDIATELY as your first action"

The skill descriptions help Claude determine when to invoke each skill.

Skill Content Structure

Based on the document-skills:xlsx example, a skill's content typically contains:

# Requirements for Outputs
[Domain-specific quality standards]

# [Domain] creation, editing, and analysis
[Overview of capabilities]

## Workflows
[Step-by-step processes]

## Code Examples
[Reference implementations]

## Best Practices
[Guidelines and tips]

Key Design Principles

1. Prompt Engineering, Not Code Execution

Skills are essentially prompt templates—they don't run code, they inject instructions that guide Claude's behavior.

2. Tool Augmentation

Skills work alongside Claude's existing tools. The xlsx skill, for example, provides guidance on using Python libraries (pandas, openpyxl) and helper scripts (recalc.py) that Claude executes via the Bash tool.

3. Domain Expertise Injection

Skills encode domain expertise (financial modeling conventions, Excel best practices) that wouldn't be appropriate in the base system prompt.

4. Composability

Skills can reference external resources in their base directory:

• Helper scripts (recalc.py)
• Templates
• Configuration files

Example Flow

User: "Create a financial model spreadsheet"
         │
         ▼
┌─────────────────────────────┐
│ Claude recognizes xlsx task │
│ Invokes Skill tool          │
└─────────────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│ Skill tool returns:         │
│ - Base directory path       │
│ - Excel requirements        │
│ - Color coding standards    │
│ - Formula best practices    │
│ - Workflow instructions     │
└─────────────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│ Claude follows instructions │
│ Uses Bash to run Python     │
│ Uses Write to save files    │
│ Uses recalc.py for formulas │
└─────────────────────────────┘
         │
         ▼
      Output: Excel file with proper formatting,
              formulas, and conventions

Comparison to Other Systems

Aspect	Skills	MCP Tools	Built-in Tools
Execution	Prompt injection	Direct execution	Direct execution
Purpose	Domain knowledge	External capabilities	Core operations
Extensibility	Plugin system	Server configuration	Fixed
State	Stateless	Can be stateful	Stateless

Implications

1. Skills are prompts: Creating a skill means writing effective instructions, not code
2. No runtime isolation: Skills run in the same context as the main conversation
3. Composable with tools: Skills guide how other tools are used
4. Cacheable: Skills are cached locally for fast access
5. Versionable: The hash in the cache path suggests version/integrity tracking