| 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
- First best practice
- Second best practice
- 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
