Claude Code Skills: How to Create Reusable Expertise Packages

Claude Code Skills are prompt-based, reusable knowledge packs that transform Claude into a specialized team member through markdown-based instruction files stored in .claude/skills/ directories.

According to the datawhalechina/easy-vibe source code, Skills provide a way to encode expertise—such as coding standards, review checklists, or CI pipelines—and reuse them across projects without additional token costs when idle. Each Skill lives as a directory containing a SKILL.md file that combines YAML front-matter metadata with markdown instructions, allowing Claude to understand complex workflows and invoke them automatically when relevant requests are detected.

What Are Claude Code Skills?

Claude Code Skills are specialized instruction sets that turn Claude into a domain-specific expert. A Skill resides as a directory on the file system, with its core being a SKILL.md file containing YAML front-matter for metadata and markdown for detailed instructions.

As documented in docs/en/stage-3/core-skills/skills/index.md, the architecture employs a three-layer loading strategy to optimize token usage:

• Metadata Layer: On startup, Claude scans all *.claude/skills/ folders and loads only the name and description from the YAML front-matter (~30-50 tokens per Skill) into its context.

• Instructions Layer: When a user request matches a Skill's description, Claude injects the full markdown body of SKILL.md as hidden meta-messages (~5,000 tokens for the active Skill only).

• Resources Layer: Scripts, templates, and assets remain on disk and are accessed on-demand from the file system (0 token impact since they are not injected).

The routing mechanism operates purely through Claude's LLM rather than regex or hard-coded maps. This enables the system to understand synonyms, fuzzy matches, and multilingual descriptions, making Skills naturally discoverable across diverse projects.

Skills vs. MCP Connectors: Key Differences

Understanding the distinction between Skills and MCP (Claude Code Connector) extensions is crucial for effective architecture decisions, as explained in docs/en/stage-3/core-skills/mcp/index.md.

Claude Code Skills encode what to do—including workflows, style guides, and policies—stored as version-controlled markdown directories in ~/.claude/skills/ or project .claude/skills/. They incur no token cost when idle and activate only when the LLM determines the user's intent matches the Skill description.

MCP Connectors handle how to do it—providing access to external systems like Git, databases, or APIs through JSON configurations and server processes. These require runtime services and consume tokens on each invocation.

Installing and Using Community Skills

You can extend Claude's capabilities by installing community-created Skills from registries. The following examples work in any terminal with Claude Code installed.

First, install the find-skills search helper to enable natural language discovery:

npx skills add vercel-labs/skills@find-skills -g -y

After installation, you can ask Claude "Help me find a skill for video generation" and it will recommend appropriate Skills automatically.

To install a specific community Skill such as Remotion for video creation:

# Search first (optional)

echo "Help me find skills related to Remotion" | claude-code

# Install the skill

npx skills add remotion-dev/skills -g

Once installed, invoke the Skill with natural language:

Use Remotion to make a 5-second video where the text "Hello World" flies in from the left.

Claude will generate a complete Remotion project structure based on the instructions defined in the Skill's SKILL.md file.

Creating Your Own Reusable Skill

Build custom expertise packages using the built-in skill-creator helper documented in docs/en/stage-3/core-skills/skill-creator/index.md. This tool scaffolds the directory structure and generates the required SKILL.md with proper YAML front-matter.

Install the creator globally:

npx skills add anthropics/skills@skill-creator -g

Launch the interactive wizard:

/skill-creator

When prompted, provide:

• Skill name: format-code
• Description: "Automatically format code according to project conventions."
• Execution steps: Detect language, run appropriate formatter, show diff

The creator generates the following structure in ~/.claude/skills/format-code/:

~/.claude/skills/format-code/
├── SKILL.md        # YAML front-matter + full markdown instructions

├── scripts/        # Optional helper scripts

└── templates/      # Optional output templates

The SKILL.md file contains the metadata header and the full instruction set that guides Claude's behavior. Resources in scripts/ and templates/ are accessed on-demand from the file system without token penalty.

Invoke your custom Skill using its defined command:

/format-code
Please format the changed files in the current repo.

Claude executes the defined steps, optionally requests confirmation, and can commit the formatted changes according to the workflow encoded in the Skill.

Summary

• Claude Code Skills are prompt-based knowledge packs stored as directories with SKILL.md files containing YAML front-matter and markdown instructions.
• The architecture loads only metadata (~30-50 tokens) at startup, injecting full instructions (~5,000 tokens) only when the LLM matches a user request to a Skill description.
• Skills differ from MCP Connectors: Skills encode workflows and policies (zero cost when idle), while MCPs provide external tool access (requires runtime services).
• Install community Skills using npx skills add <publisher>/<name> -g and create custom ones using the skill-creator helper.
• Reference implementations and detailed guides are available in docs/en/stage-3/core-skills/skills/index.md and docs/en/stage-3/core-skills/skill-creator/index.md within the datawhalechina/easy-vibe repository.

Frequently Asked Questions

What file format does a Claude Code Skill use?

A Skill uses a SKILL.md file that combines YAML front-matter for metadata (name and description) with markdown content for the instruction set. This file resides in a directory named after the Skill within ~/.claude/skills/ or a project's .claude/skills/ folder.

How do Skills manage token costs compared to other extensions?

Skills minimize token costs by loading only the metadata (~30-50 tokens per Skill) into context at startup. The full instruction set (~5,000 tokens) is injected only when the Skill is triggered by a matching user request. External resources like scripts and templates are read from disk on-demand with zero token impact.

What is the difference between Skills and MCP in Claude Code?

Skills encode what to do—workflows, coding standards, and policies—through markdown instructions that require no running services. MCP (Claude Code Connector) extensions provide how to access external systems like databases or APIs through JSON configurations and server processes that consume tokens on each call.

Where should I store Skills for global vs. project-specific use?

Store Skills in ~/.claude/skills/ for global access across all projects, or in <project-root>/.claude/skills/ for project-specific expertise. Claude Code scans both locations at startup, loading metadata from all discovered Skills regardless of location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}