Creating Skills

This guide explains how to create effective skill documents for Claude Code. Skills are domain-specific knowledge files that teach Claude how to perform specialized tasks consistently.

File Structure

Skills must be placed in the .claude/skills/ directory with the following structure:

.claude/
 skills/
     My Skill Name/
         SKILL.md          # Main skill document (required)
         reference-file.cs  # Supporting reference files (optional)

YAML Frontmatter (Required)

Every skill document must begin with YAML frontmatter between --- delimiters:

---
name: Skill Name
description: Brief description of what this skill enables (appears in skill list)
---

Frontmatter Fields:

Field	Required	Description
name	Yes	Display name for the skill (used in /skill command)
description	Yes	One-line summary shown when listing available skills
license	No	License information if applicable

Example:

---
name: Elasticsearch
description: Elasticsearch 5.2 operations using HTTP API - searching, indexing, bulk operations, scroll API, and alias management
---

Document Structure

A well-structured skill document follows this pattern:

1. Title and Overview

# Skill Name

Brief introduction explaining what this skill covers and when Claude should use it.

2. Instructions Section

Numbered guidelines for Claude to follow when applying this skill:

## Instructions

When helping users with [topic], follow these guidelines:

1. **Guideline One**: Explanation of the first principle
2. **Guideline Two**: Second important consideration
3. **Guideline Three**: Third rule to follow
...

3. Examples Section

Conversational examples showing how Claude should respond to common requests:

## Examples

### Example 1: Descriptive Title

User: Example user request

Claude: How Claude should approach this:

• Step 1 explanation
• Step 2 explanation
• Reference to implementation details below

[Provides implementation using the Pattern Name from reference material below]

### Example 2: Another Common Scenario

User: Different user request

Claude: Alternative approach explanation...

Example Pattern:

### Example 3: Search with Range Filters

User: Help me search Elasticsearch for pricing periods active today

Claude: I'll use the ServiceLib.Elasticsearch wrapper with a bool query and range filters:

• Current date for comparison
• Two range filters (start <= today AND end >= today)
• Access results via dynamic object properties

[Provides implementation using the Search pattern from reference material below]

4. Reference Implementation Section

Divider followed by detailed, production-proven code:

---

# Reference Implementation Details

The sections below contain proven working code from production systems that the examples above reference.

**Reference Files in This Folder**:
- `HelperClass.cs` - Description of what it contains
- `ExampleService.cs` - Another supporting file

## Pattern Name

**Location**: `Source/Path.cs`
**Purpose**: What this pattern accomplishes

### Code Example

```csharp
// Production-tested code with comments explaining key decisions
public class ExampleClass
{
    // Implementation details...
}

Key Points:

• Important observation about the pattern
• Critical requirement or constraint
• Common pitfall to avoid

## Best Practices

### 1. Be Specific and Prescriptive

**Good:**
```markdown
1. **Version Constraint**: Always use Elasticsearch 5.2 API patterns. This version will not change.

Avoid:

1. Use the appropriate Elasticsearch version for your project.

2. Include Exact Command Formats

When Claude needs to execute commands, provide exact syntax:

**ALWAYS use this exact command format:**

```bash
"Y:/CSharpDLLs/Tool/Tool.exe" <command> --solution "<path>" --format console

### 3. Document Parameter Styles and Patterns

For database or API work, clearly document parameter conventions:

```markdown
## Parameter Styles by Database

| Database | Parameter Style | Example |
|----------|----------------|---------|
| DuckDB | `?` placeholders | `WHERE id = ?` |
| PostgreSQL | `$1, $2, $3` | `WHERE id = $1` |
| MySQL | `@parameter` | `WHERE id = @id` |

4. Include Error Handling and Troubleshooting

## Troubleshooting

### "Connection Refused" Error

**Cause:** Server not running

**Solution:**
```bash
cd server-directory
dotnet run

### 5. Reference Supporting Files

If your skill folder contains additional files, reference them explicitly:

```markdown
**Reference Files in This Folder**:
- `Utf8LoggingExtensions.cs` - Complete UTF-8 logger implementation (copy to Services/)
- `ODBC.cs` - ServiceLib ODBC wrapper with ExecuteAndMap pattern

6. Use Tables for Quick Reference

## Quick Reference

| Action | Command | Notes |
|--------|---------|-------|
| Find unused | `unused --solution X` | High confidence = safe |
| Check impact | `impact --method Y` | Shows what would break |
| Find callers | `callers --method Z` | Direct dependencies |

7. Include Real-World Examples

## Real-World Examples

### PriceExtractor
```bash
dotnet run -- --pqdir "R:\Outputs\Parquets\poller" --log-dir "C:\Logs\PriceExtractor"

Creates: C:\Logs\PriceExtractor\PriceExtractor_2025_10_16.log

## Complete Skill Template

```markdown
---
name: My Skill Name
description: One-line description of skill capabilities and use cases
---

# My Skill Name

Brief introduction explaining the skill's purpose and when to use it.

## Instructions

When helping users with [topic], follow these guidelines:

1. **First Principle**: Explanation
2. **Second Principle**: Explanation
3. **Third Principle**: Explanation

## Examples

### Example 1: Common Task

User: Typical user request

Claude: How to approach this:

• Step explanation
• Another step

[Provides implementation using Pattern from reference material below]

### Example 2: Another Task

User: Different request

Claude: Alternative approach...

---

# Reference Implementation Details

The sections below contain proven working code that the examples above reference.

**Reference Files in This Folder**:
- `file1.cs` - Description
- `file2.cs` - Description

## Pattern Name

**Location**: `Path/To/Source.cs`
**Purpose**: What this accomplishes

```csharp
// Production code example
public class Example
{
    // Implementation
}

Key Points:

• Important note
• Critical requirement

Another Pattern

Additional implementation details...

Troubleshooting

Common Error

Cause: Why this happens

Solution: How to fix it

Best Practices Summary

1. First best practice
2. Second best practice
3. Third best practice

## Common Mistakes to Avoid

1. **Missing YAML frontmatter** - Skill won't be recognized without `---` delimiters and required fields

2. **Vague instructions** - "Use appropriate methods" vs "Use HttpClient with POST to /_bulk endpoint"

3. **No examples** - Abstract instructions without concrete user/Claude dialogues

4. **Untested code** - Reference implementations should be production-proven, not theoretical

5. **Missing context** - Not explaining why certain patterns are preferred

6. **No error handling** - Users will hit errors; document common issues and solutions

7. **Outdated references** - Keep file paths and version numbers current

## Testing Your Skill

After creating a skill:

1. Verify the skill appears in the available skills list
2. Test with a request that should trigger the skill
3. Confirm Claude follows the documented patterns
4. Check that example scenarios produce expected outputs
5. Validate reference code still works with current dependencies