create-skill

# Creating Skills

## SKILL.md Structure

```yaml
---
name: my-skill-name        # lowercase, hyphens, max 64 chars
description: Does X and Y. Use when Z happens.  # max 1024 chars, third person
---

# Skill Title

[Instructions go here]
```

## Core Principles

### Be Concise
Agents are smart. Only add context the agent doesn't already have. Challenge each sentence: "Does this justify its token cost?"

### Match Specificity to Risk
- **High freedom** (general guidance): Multiple valid approaches, context-dependent
- **Low freedom** (exact scripts): Fragile operations, specific sequences required

### Write Effective Descriptions
- Use third person ("Processes files" not "I process files")
- Include what it does AND when to use it
- Be specific with key terms for discovery

## Progressive Disclosure

Keep SKILL.md under 500 lines. Link to separate files for advanced content:

```markdown
## Quick start
[Essential instructions here]

## Advanced
- **Feature A**: See [FEATURE_A.md](FEATURE_A.md)
- **Reference**: See [reference.md](reference.md)
```

Keep references **one level deep** from SKILL.md.

## Workflows

For complex tasks, provide checklists:

```markdown
## Workflow

- [ ] Step 1: Analyze input
- [ ] Step 2: Validate results
- [ ] Step 3: Apply changes
- [ ] Step 4: Verify output
```

Include feedback loops: validate → fix errors → repeat.

## Common Patterns

**Templates**: Provide output format examples
**Examples**: Show input/output pairs
**Conditional workflows**: Guide through decision points

## Anti-Patterns

- Verbose explanations of concepts agents already know
- Time-sensitive information ("after August 2025...")
- Inconsistent terminology
- Deeply nested file references
- Windows-style paths (`\` instead of `/`)
- Multiple equivalent options without a default

## With Executable Scripts

Add scripts to skills when you need to abstract over complex operations.
Use .NET file-based apps to write the scripts. Use the "dotnet-file-based-apps"
skill to