creating-skills

name	Creating Skills
description	Guide for creating Claude Code skill documents with YAML frontmatter, instructions, examples, and reference implementations

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