Claude Code Skills: A Complete Guide from Basics to Advanced Usage (2026)

Claude Code Skills is a modular system that lets developers extend Anthropic's Claude AI capabilities using SKILL.md files. These files combine YAML frontmatter (for configuration) and Markdown instructions (for execution), enabling Claude to use the skill either via direct /skill-name commands or automatic recognition in conversations. Skills adhere to the Agent Skills open standard (agentskills.io), making them shareable across multiple AI tools.

Code Skills are a superset of Claude's existing Commands feature. Both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md create a /deploy command with identical behavior—so existing Commands don’t need migration. However, Skills add key enhancements: directory structures for supporting files (templates, scripts, examples), frontmatter controls (e.g., invocation permissions, model selection), subagent execution in independent contexts, dynamic context injection using !`command` to prefill real-time data, and parameter placeholders like $ARGUMENTS or $0.

Skills can be stored at four levels, each with a specific scope and priority:

• Enterprise: Managed settings (applies to all users in an organization).
• Personal: ~/.claude/skills//SKILL.md (applies to all your projects).
• Project: .claude/skills//SKILL.md (applies only to the current project).
• Plugin: /skills//SKILL.md (applies where the plugin is enabled).

Higher-level Skills override lower ones (enterprise > personal > project > plugin). Plugin Skills use a plugin-name:skill-name namespace to avoid conflicts.

Creating your first Skill is straightforward. Let’s build an 'explain-code' skill that breaks down code with analogies and diagrams:

1. Create the directory: Run `mkdir -p ~/.claude/skills/explain-code` to set up the skill folder.
2. Write SKILL.md: This file has two parts. The YAML frontmatter defines when and how to use the skill, while the Markdown body gives execution instructions. For example:

   ---
   name: explain-code
   description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
   ---
   When explaining code, always include:
   1. **Start with an analogy**: Compare the code to something from everyday life.
   2. **Draw a diagram**: Use ASCII art to show flow, structure, or relationships.
   3. **Walk through**: Step-by-step explanation of what happens.
   4. **Highlight a gotcha**: Common mistakes or misconceptions.
   

3. Test the skill: Trigger it either by asking Claude a question like "How does this code work?" (auto-recognition) or directly calling `/explain-code src/auth/login.ts`.

The YAML frontmatter in SKILL.md controls critical aspects of the skill. Key fields include:

• `name`: Skill name (defaults to directory name if omitted).
• `description`: Helps Claude decide when to auto-load the skill.
• `argument-hint`: Hint for command-line completion (e.g., "[filename]").
• `disable-model-invocation`: If true, only users can trigger the skill (Claude won’t auto-use it).
• `user-invocable`: If false, only Claude can use the skill (not visible in / menu).
• `allowed-tools`: Tools the skill can use without user confirmation (e.g., Read, Grep).
• `model`: Specify the Claude model to use (sonnet, opus, haiku, or full ID).
• `context: fork`: Runs the skill in an independent subagent context.

Three common invocation control combinations exist: default (both user and Claude can trigger), `disable-model-invocation: true` (user-only), and `user-invocable: false` (Claude-only).

Skills can include supporting files alongside SKILL.md. A typical structure might look like:

my-skill/
├── SKILL.md (main entry point)
├── template.md (Claude uses this as a response template)
├── examples/ (sample outputs)
│   └── sample.md
└── scripts/ (executable scripts)
    └── validate.sh

You can reference these files in SKILL.md using relative links, e.g., "[examples.md](examples.md)".

Sources

• SegmentFault: "A Complete Guide to Claude Code Skills: From Basics to Advanced Usage (2026)" (https://segmentfault.com/a/1190000047673949)