Skill Types & Anatomy

The Three Skill Types

Not every Skill is built the same way. Depending on what you want to automate, you need a different type. Claude Code has three skill types that build on each other:

1. Knowledge Skills -- Pure Instructions

The simplest type: A SKILL.md file with instructions, nothing else. Claude gets rules and knowledge but doesn't need external files or scripts.

Typical use cases:

• Creative workflows ("Write blog posts in my style")
• Research processes ("Analyze libraries using these criteria")
• Code review checklists ("Always check these 5 points")

---
name: blog-post
description: Write a blog post following our editorial guidelines
argument-hint: [topic]
---

# Blog Post Skill

Write blog posts following these rules:
- Maximum 800 words
- Formulate title as a question
- Three subheadings
- Summary at the end

2. Reference Skills -- Instructions + Reference Files

Knowledge Skills plus reference material. The SKILL.md references files in the same directory -- templates, style guides, example files.

Typical use cases:

• Template-based generation ("Create components based on this template")
• Style-specific tasks ("Format code according to our style guide")
• Documentation workflows ("Use our documentation template")

---
name: react-component
description: Create React components following our project template
argument-hint: [component-name]
---

# React Component Skill

Create a new React component based on the template
in `template.tsx` in the same directory.

Follow the naming conventions in `conventions.md`.

3. Script Skills -- Instructions + Scripts

The most powerful variant: The SKILL.md orchestrates Python or Bash scripts located in the same directory. Claude executes the scripts and processes the results.

Typical use cases:

• Data processing ("Parse this CSV and create a report")
• Automated analysis ("Run performance tests")
• Build and deploy workflows ("Build and deploy the project")

---
name: perf-report
description: Run performance benchmarks and generate a report
---

# Performance Report Skill

1. Run `benchmark.sh`
2. Parse the results
3. Create a Markdown report comparing to the last run

SKILL.md Anatomy -- The Frontmatter

Every SKILL.md begins with a YAML frontmatter block between ---. Here you define how the Skill behaves. The instructions that follow determine what the Skill does.

1---
2name: deploy-preview●
3description: Deploy a preview environment for the current branch●
4argument-hint: "[environment]"●
5model: sonnet●
6context: fork●
7agent: Explore●
8allowed-tools: Read, Bash, Grep●
9hooks:●
10  PostToolUse:
11    - matcher: "Bash"
12      hooks:
13        - type: command
14          command: "echo 'Deployed!'"
15---
16
17# Deploy Preview
18
191. Check current branch and changes
202. Run tests: `npm test`
213. Build: `npm run build`
224. Deploy to preview URL

The Most Important Frontmatter Fields

Identity and invocation:

• name -- The slash command name. Becomes /name. Must be unique, use kebab-case.
• description -- Controls auto-discovery. Claude reads this field to decide whether the Skill matches a task. The more precise, the fewer false matches.
• argument-hint -- Autocomplete hint in the terminal, e.g., [branch] [--force]. Purely cosmetic.

Execution control:

• model -- Which model should the Skill use? sonnet for fast tasks, opus for complex reasoning tasks, haiku for simple transformations. Saves cost and time.
• context: fork -- The Skill runs in its own subagent context. Perfect for tasks that shouldn't burden the main context.
• allowed-tools -- Restricts the available tools. An analysis Skill might only need read access: allowed-tools: [read, glob, grep].

Trigger control:

• disable-model-invocation -- The Skill is only triggered via /command, never automatically. Use this for destructive operations like deployments.
• user-invocable: false -- Only Claude itself can invoke the Skill, not the user. For internal helper Skills.

Context filters:

• paths -- The Skill is only active when you're working in specific file paths. Example: paths: ["src/components/**"] activates the Skill only for component files.

Lifecycle:

• hooks -- Lifecycle hooks in the Skill, e.g., pre-/post-execution commands.

Storage Locations

Skills can reside in three locations:

The order determines priority: Project Skills override global Skills with the same name.

String Substitutions

In SKILL.md files, you can use placeholders that are replaced at runtime:

• $ARGUMENTS -- Everything that comes after the /command
• $0 -- The first argument
• ${CLAUDE_SESSION_ID} -- Unique session ID
• ${CLAUDE_SKILL_DIR} -- Absolute path to the Skill directory (useful for Script Skills)

---
name: deploy
description: Deploy to a specific environment
argument-hint: [environment]
---

Deploy branch to $0 environment.
Use scripts in ${CLAUDE_SKILL_DIR}/scripts/ for the deployment.