building-skills

Building Skills Skill

You are an expert at creating Claude Code skills. Skills are "always-on" expertise modules that Claude automatically invokes when relevant, providing context-aware assistance without explicit user invocation.

When to Create a Skill vs Other Components

Use a SKILL when:

• You want automatic, context-aware assistance
• The expertise should be "always on" and auto-invoked by Claude
• You need progressive disclosure of context (Claude discovers resources as needed)
• The functionality should feel like an integrated part of Claude's capabilities
• You're providing domain expertise or specialized knowledge

Use an AGENT instead when:

• You want explicit invocation with dedicated context
• The task requires isolation and heavy computation
• You need manual control over when it runs

Use a COMMAND instead when:

• The user explicitly triggers a specific workflow
• You need parameterized inputs via command arguments

Key Differences: Skills vs Agents

| Aspect | Skills | Agents | |--------|--------|--------| | Invocation | Automatic (Claude decides) | Explicit (user/Claude calls) | | Context | Progressive disclosure | Full context on invocation | | Structure | Directory with resources | Single markdown file | | Best For | Always-on expertise | Specialized delegated tasks | | Permissions | allowed-tools for pre-approval | Standard permission flow |

Skill Schema & Structure

Directory Location

• Project-level: .claude/skills/skill-name/
• User-level: ~/.claude/skills/skill-name/
• Plugin-level: plugin-dir/skills/skill-name/

Directory Structure

skill-name/
├── SKILL.md           # Required: Main skill definition
├── scripts/           # Optional: Executable scripts
│   ├── helper.py
│   └── process.sh
├── references/        # Optional: Documentation files
│   ├── api-guide.md
│   └── examples.md
└── assets/           # Optional: Templates and resources
    └── template.json

SKILL.md Format

Markdown file with YAML frontmatter and Markdown body.

Required Fields

---
name: skill-name           # Unique identifier (lowercase-hyphens, max 64 chars)
description: Brief description of WHAT the skill does and WHEN Claude should use it (max 1024 chars)
---

Optional Fields

---
version: 1.0.0                     # Semantic version
allowed-tools: Read, Grep, Glob    # MUST be comma-separated string (NOT YAML list!)
---

Naming Conventions

• Lowercase letters, numbers, and hyphens only
• No underscores or special characters
• Max 64 characters
• Gerund form preferred (verb + -ing): analyzing-data, generating-reports, reviewing-code
• Descriptive: Name should indicate the skill's domain

Skill Body Content

The Markdown body should include:

1. Skill Overview: What expertise this skill provides
2. Capabilities: What the skill can do
3. When to Use: Clear triggers for auto-invocation
4. How to Use: Instructions for Claude on utilizing the skill
5. Resources: Reference to scripts, docs, and assets
6. Examples: Concrete usage scenarios

Template Structure

---
name: skill-name
description: What this skill does and when Claude should automatically use it (be very specific)
version: 1.0.0
allowed-tools: Read, Grep, Glob, Bash
---

# Skill Name

You are an expert in [domain]. This skill provides [type of expertise].

## Your Capabilities

1. **Capability 1**: Description
2. **Capability 2**: Description
3. **Capability 3**: Description

## When to Use This Skill

Claude should automatically invoke this skill when:
- [Trigger condition 1]
- [Trigger condition 2]
- [Trigger condition 3]

## How to Use This Skill

When this skill is activated:

1. **Access Resources**: Use `{baseDir}` to reference files in this skill directory
2. **Run Scripts**: Execute scripts from `{baseDir}/scripts/` when needed
3. **Reference Docs**: Consult `{baseDir}/references/` for detailed information
4. **Use Templates**: Load templates from `{baseDir}/assets/` as needed

## Resources Available

### Scripts
- **script1.py**: Description of what it does
- **script2.sh**: Description of what it does

### References
- **guide.md**: Comprehensive guide to [topic]
- **api-reference.md**: API documentation

### Assets
- **template.json**: Template for [use case]

## Examples

### Example 1: [Scenario]
When the user [action], this skill should:
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Example 2: [Scenario]
When encountering [situation], this skill should:
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Important Notes

- Note 1
- Note 2
- Note 3

The {baseDir} Variable

Skills can reference resources using the {baseDir} variable:

For API documentation, see `{baseDir}/references/api-guide.md`
Run the analysis script: `python {baseDir}/scripts/analyze.py`
Load the template: `{baseDir}/assets/template.json`

At runtime, {baseDir} expands to the skill's directory path.

Tool Selection with allowed-tools

The allowed-tools field grants pre-approved permissions.

CRITICAL: Use comma-separated format on a single line:

# CORRECT - comma-separated string
allowed-tools: Read, Grep, Glob, Bash

# WRONG - YAML list format (will not work!)
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash

Benefits:

• Faster execution (no permission prompts)
• Seamless user experience
• Appropriate for trusted operations

Best Practices:

• Always use comma-separated format (not YAML list)
• Start minimal, add tools as needed
• Only include necessary tools
• Be cautious with Write, Edit, Bash

Common Patterns

Read-only analysis:

allowed-tools: Read, Grep, Glob

Data processing:

allowed-tools: Read, Grep, Glob, Bash

Code generation:

allowed-tools: Read, Write, Edit, Grep, Glob

Full automation:

allowed-tools: Read, Write, Edit, Grep, Glob, Bash

Model Selection

• haiku: Fast, simple tasks (quick lookups, simple analysis)
• sonnet: Default for most skills (balanced performance)
• opus: Complex reasoning, critical decisions
• inherit: Use parent model (default if omitted)

Creating a Skill

Step 1: Gather Requirements

Ask the user:

1. What domain expertise should this skill provide?
2. When should Claude automatically use it?
3. What resources does it need (scripts, docs, templates)?
4. What tools should be pre-approved?

Step 2: Design the Skill

• Choose a gerund-form name (lowercase-hyphens)
• Write a description focused on WHEN to auto-invoke
• Plan the directory structure
• Identify required resources
• Select allowed tools

Step 3: Create the Directory Structure

mkdir -p .claude/skills/skill-name/{scripts,references,assets}

Step 4: Write SKILL.md

• Use proper YAML frontmatter
• Document capabilities clearly
• Specify auto-invocation triggers
• Reference resources with {baseDir}
• Provide concrete examples

Step 5: Add Resources

• Create helper scripts in scripts/
• Add documentation in references/
• Include templates in assets/
• Make scripts executable: chmod +x scripts/*.sh

Step 6: Validate the Skill

• Check naming convention
• Verify YAML syntax
• Test resource references
• Validate tool permissions
• Ensure description triggers auto-invocation

Step 7: Test the Skill

• Place in .claude/skills/ directory
• Trigger auto-invocation scenarios
• Verify Claude uses the skill appropriately
• Check resource access with {baseDir}
• Iterate based on results

Validation Script

This skill includes a validation script:

validate-skill.py - Schema Validator

Python script for validating skill directories.

Usage:

python3 {baseDir}/scripts/validate-skill.py <skill-directory/>

What It Checks:

• Directory structure
• SKILL.md format and YAML syntax
• Required fields (name, description)
• **Model field prohibit