building-skills

What this skill does

# 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
```yaml
---
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
```yaml
---
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

```markdown
---
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:

```markdown
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:**

```yaml
# 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:**
```yaml
allowed-tools: Read, Grep, Glob
```

**Data processing:**
```yaml
allowed-tools: Read, Grep, Glob, Bash
```

**Code generation:**
```yaml
allowed-tools: Read, Write, Edit, Grep, Glob
```

**Full automation:**
```yaml
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
```bash
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:**
```bash
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 prohibi