Skip to main content
Skill discovery is the process of finding and loading skills from the filesystem, making them available for invocation by users, agents, and commands.

​
Discovery Paths

Skills are discovered from three locations in order of precedence:
1

Project Skills

Path: .claude/skills/*/SKILL.mdScope: Current project onlyUse for: Project-specific patterns, conventions, and workflowsExample: .claude/skills/api-conventions/SKILL.md
2

User Skills

Path: ~/.claude/skills/*/SKILL.mdScope: All projects for this userUse for: Personal coding patterns, language-specific knowledge, tool configurationsExample: ~/.claude/skills/typescript-patterns/SKILL.md
3

Plugin Skills

Path: ~/.claude/plugins/*/skills/*/SKILL.mdScope: Installed pluginsUse for: Reusable community skills, framework-specific patternsExample: ~/.claude/plugins/marketplaces/pro-workflow/skills/wrap-up/SKILL.md

​
Naming Convention

​
Directory Name
string
required
The skill name comes from the directory name, not the file name.
skills/
├── wrap-up/
│   └── SKILL.md        # Skill name: wrap-up
├── api-conventions/
│   └── SKILL.md        # Skill name: api-conventions
└── replay-learnings/
    └── SKILL.md        # Skill name: replay-learnings
The file must be named SKILL.md (uppercase). Other names are ignored.

​
Precedence Rules

When multiple skills have the same name:
  1. Project → Overrides user and plugin skills
  2. User → Overrides plugin skills
  3. Plugin → Lowest priority
Plugin skill: ~/.claude/plugins/pro-workflow/skills/wrap-up/SKILL.md
---
name: wrap-up
description: Generic wrap-up ritual
---

Generic checklist for all projects.
User skill: ~/.claude/skills/wrap-up/SKILL.md
---
name: wrap-up
description: My custom wrap-up ritual
---

My personal wrap-up checklist with extra steps.
Project skill: .claude/skills/wrap-up/SKILL.md
---
name: wrap-up
description: Project-specific wrap-up
---

Project-specific checklist with team conventions.
Result: When you run /wrap-up, the project skill is used.

​
Discovery Process

1

Scan Directories

Claude Code scans all skill directories at startup:
find .claude/skills -name 'SKILL.md'
find ~/.claude/skills -name 'SKILL.md'
find ~/.claude/plugins/*/skills -name 'SKILL.md'
2

Parse Frontmatter

For each SKILL.md, parse YAML frontmatter:
---
name: wrap-up
description: End-of-session ritual
user-invocable: true
---
3

Register Skills

Skills are registered by name with metadata:
{
  "wrap-up": {
    "path": ".claude/skills/wrap-up/SKILL.md",
    "description": "End-of-session ritual",
    "user-invocable": true,
    "source": "project"
  }
}
4

Make Available

Skills are available for:
  • User invocation: /wrap-up
  • Agent preloading: skills: ["wrap-up"]
  • Model invocation: Claude can call skills when relevant

​
Discovery Filters

​
User-Invocable

Only skills with user-invocable: true appear in the / menu: 
---
name: wrap-up
user-invocable: true  # Shows in / menu
---

---
name: internal-helper
user-invocable: false  # Hidden from / menu
---

​
Model Invocation

Skills with disable-model-invocation: true can only be invoked by users: 
---
name: dangerous-operation
disable-model-invocation: true  # Claude cannot auto-invoke
---

​
Verification

Check which skills are discovered: 
# Project skills
find .claude/skills -name 'SKILL.md' -exec dirname {} \; | xargs basename

# User skills
find ~/.claude/skills -name 'SKILL.md' -exec dirname {} \; | xargs basename

# Plugin skills
find ~/.claude/plugins -name 'SKILL.md' -exec dirname {} \; | xargs basename

​
Common Issues

Problem: /my-skill returns “Skill not found”Solutions:
  1. Check file is named SKILL.md (case-sensitive)
  2. Check directory structure: skills/my-skill/SKILL.md
  3. Verify frontmatter has name: my-skill
  4. Restart Claude Code to re-scan skills
# Verify structure
ls -la .claude/skills/my-skill/SKILL.md

# Check frontmatter
head -5 .claude/skills/my-skill/SKILL.md
Problem: Modified skill but old version still runsSolutions:
  1. Check precedence: project > user > plugin
  2. Find all instances: 
    find . ~/.claude ~/.claude/plugins -path '*/skills/my-skill/SKILL.md'
  3. Remove or rename conflicting skills
  4. Restart Claude Code
Problem: Skill exists but doesn’t appear in / menuSolutions:
  1. Check user-invocable: true in frontmatter
  2. Verify no YAML syntax errors
  3. Restart Claude Code
# Validate YAML
yq eval '.user-invocable' .claude/skills/my-skill/SKILL.md

​
Directory Structure

Best practices for organizing skills: 
.claude/skills/
├── wrap-up/
│   └── SKILL.md
├── search/
│   └── SKILL.md
└── develop/
    └── SKILL.md
Simple, works for <20 skills.

​
Plugin Skills

Plugins ship skills in their skills/ directory: 
~/.claude/plugins/marketplaces/pro-workflow/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── pro-workflow/
│   │   └── SKILL.md
│   ├── wrap-up/
│   │   └── SKILL.md
│   └── orchestrate/
│       └── SKILL.md
└── dist/
Plugin skills are automatically discovered when the plugin is installed.

​
Dynamic Discovery

Skills can be added at runtime: 
# Add new skill
mkdir -p .claude/skills/new-skill
cat > .claude/skills/new-skill/SKILL.md <<EOF
---
name: new-skill
description: Newly added skill
user-invocable: true
---

# New Skill

Instructions here.
EOF

# Restart Claude Code to discover
Skills are scanned at startup. Add new skills, then restart Claude Code.

​
Best Practices

Unique Names

Skill names must be unique across all locations. Use descriptive, specific names.

Follow Convention

Use skills/<name>/SKILL.md structure. Don’t deviate.

Test Discovery

After adding skills, verify they appear in / menu.

Document Location

In skill description, note if it’s project-specific or user-wide.

​
Next Steps

Skill Frontmatter

Configure skill metadata

Skill Preloading

Load skills into agents

Agent Skills

Preload skills into agent context

Creating Skills

Build custom skills

Build docs developers (and LLMs) love

Get started for freeTalk to us