Claude Code Skills

Overview

Skills are custom prompts that extend Claude Code's capabilities for specific tools, configurations, or workflows. They're project-specific or user-specific context that Claude can invoke when relevant.

Skill Location

User skills: ~/.claude/skills/<skill-name>/SKILL.md

Each skill is a directory containing a SKILL.md file.

Skill Structure

---
name: skill-name
description: Brief description of when to use this skill. Claude uses this to decide when to invoke the skill.
---

# Skill Title

## Overview
Brief explanation of what this skill helps with.

## Configuration Locations
Paths to relevant config files, if applicable.

## Key Concepts
Important information Claude should know.

## When Helping Users
Guidelines for how to approach tasks with this skill.

## Common Tasks
Examples of what users might ask for.

## Best Practices
Tips and recommendations.

## Troubleshooting
Common issues and solutions.

Frontmatter Requirements

The YAML frontmatter at the top is critical:

---
name: skill-name          # Must match directory name
description: When to use this skill. Be specific about triggers like "when user asks about X, Y, or Z"
---

The description field should:

• Be clear and specific
• Mention key terms that would trigger the skill
• Explain the scope (e.g., "configuration", "debugging", "setup")

Creating a New Skill

1. Create directory:

   mkdir -p ~/.claude/skills/my-skill
   

2. Create SKILL.md:

   nvim ~/.claude/skills/my-skill/SKILL.md
   

3. Add frontmatter and content:

   • Start with YAML frontmatter
   • Include relevant paths, commands, and context
   • Reference official documentation when applicable
   • Add examples and common patterns

4. Test the skill:

   • Restart Claude or start a new conversation
   • Ask questions that should trigger the skill
   • Verify Claude has the right context

Skill Examples

aerospace skill

• Purpose: Help with AeroSpace window manager config
• Includes: Config locations, documentation links, TOML format help
• Triggers: "AeroSpace", "window management", "tiling"

lazyvim skill

• Purpose: Help with LazyVim/Neovim configuration
• Includes: Plugin management, keybindings, LSP setup
• Triggers: "LazyVim", "Neovim", "plugins", "editor"

tmux skill

• Purpose: Help with tmux/tmuxinator/sesh setup
• Includes: Template structure, session management, layouts
• Triggers: "tmux", "tmuxinator", "sessions", "terminal multiplexing"

Best Practices

1. Be specific in descriptions: Help Claude know exactly when to use the skill
2. Include file paths: Direct paths make it easy to read/edit configs
3. Reference documentation: Link to official docs for authoritative info
4. Add examples: Show concrete examples of common patterns
5. Keep it focused: One skill per tool/domain
6. Update regularly: Keep skills current with your actual setup

When to Create a Skill

Create a skill when:

• You have a complex tool configuration (e.g., tmux, vim, window manager)
• You want Claude to remember specific project patterns
• There are non-obvious conventions or workflows
• You frequently ask Claude about the same topic
• You have custom aliases, functions, or scripts

Don't create a skill for:

• Simple one-off tasks
• Standard tools without customization
• Information that's better in documentation

Skill Scope

Project skills (if supported): Specific to a single project User skills: Available across all Claude sessions for your user

User skills go in ~/.claude/skills/ and are always available.

Invoking Skills

Claude automatically decides when to invoke skills based on:

• The skill's description field
• Keywords in the user's question
• Context of the conversation

You can also explicitly mention the tool/topic to trigger the skill.

Debugging Skills

If a skill isn't being used:

1. Check the description field - is it specific enough?
2. Verify the YAML frontmatter is valid
3. Ensure name: matches the directory name
4. Try explicitly mentioning keywords from the description
5. Restart Claude or start a new conversation