# Anatomy of a Skill - Understanding the Structure

**Want to understand how skills work under the hood?** This guide breaks down every part of a skill file.

---

## 📁 Basic Folder Structure

```
skills/
└── my-skill-name/
    ├── SKILL.md              ← Required: The main skill definition
    ├── examples/             ← Optional: Example files
    │   ├── example1.js
    │   └── example2.py
    ├── scripts/              ← Optional: Helper scripts
    │   └── helper.sh
    ├── templates/            ← Optional: Code templates
    │   └── template.tsx
    ├── references/           ← Optional: Reference documentation
    │   └── api-docs.md
    └── README.md             ← Optional: Additional documentation
```

**Key Rule:** Only `SKILL.md` is required. Everything else is optional!

---

## SKILL.md Structure

Every `SKILL.md` file has two main parts:

### 1. Frontmatter (Metadata)
### 2. Content (Instructions)

Let's break down each part:

---

## Part 1: Frontmatter

The frontmatter is at the very top, wrapped in `---`:

```markdown
---
name: my-skill-name
description: "Brief description of what this skill does"
---
```

### Required Fields

#### `name`
- **What it is:** The skill's identifier
- **Format:** lowercase-with-hyphens
- **Must match:** The folder name exactly
- **Example:** `stripe-integration`

#### `description`
- **What it is:** One-sentence summary
- **Format:** String in quotes
- **Length:** Keep it under 150 characters
- **Example:** `"Stripe payment integration patterns including checkout, subscriptions, and webhooks"`

### Optional Fields

Some skills include additional metadata:

```markdown
---
name: my-skill-name
description: "Brief description"
version: "1.0.0"
author: "Your Name"
tags: ["react", "typescript", "testing"]
---
```

---

## Part 2: Content

After the frontmatter comes the actual skill content. Here's the recommended structure:

### Recommended Sections

#### 1. Title (H1)
```markdown
# Skill Title
```
- Use a clear, descriptive title
- Usually matches or expands on the skill name

#### 2. Overview
```markdown
## Overview

A brief explanation of what this skill does and why it exists.
2-4 sentences is perfect.
```

#### 3. When to Use
```markdown
## When to Use This Skill

- Use when you need to [scenario 1]
- Use when working with [scenario 2]
- Use when the user asks about [scenario 3]
```

**Why this matters:** Helps the AI know when to activate this skill

#### 4. Core Instructions
```markdown
## How It Works

### Step 1: [Action]
Detailed instructions...

### Step 2: [Action]
More instructions...
```

**This is the heart of your skill** - clear, actionable steps

#### 5. Examples
```markdown
## Examples

### Example 1: [Use Case]
\`\`\`javascript
// Example code
\`\`\`

### Example 2: [Another Use Case]
\`\`\`javascript
// More code
\`\`\`
```

**Why examples matter:** They show the AI exactly what good output looks like

#### 6. Best Practices
```markdown
## Best Practices

- ✅ Do this
- ✅ Also do this
- ❌ Don't do this
- ❌ Avoid this
```

#### 7. Common Pitfalls
```markdown
## Common Pitfalls

- **Problem:** Description
  **Solution:** How to fix it
```

#### 8. Related Skills
```markdown
## Related Skills

- `@other-skill` - When to use this instead
- `@complementary-skill` - How this works together
```

---

## Writing Effective Instructions

### Use Clear, Direct Language

**❌ Bad:**
```markdown
You might want to consider possibly checking if the user has authentication.
```

**✅ Good:**
```markdown
Check if the user is authenticated before proceeding.
```

### Use Action Verbs

**❌ Bad:**
```markdown
The file should be created...
```

**✅ Good:**
```markdown
Create the file...
```

### Be Specific

**❌ Bad:**
```markdown
Set up the database properly.
```

**✅ Good:**
```markdown
1. Create a PostgreSQL database
2. Run migrations: `npm run migrate`
3. Seed initial data: `npm run seed`
```

---

## Optional Components

### Scripts Directory

If your skill needs helper scripts:

```
scripts/
├── setup.sh          ← Setup automation
├── validate.py       ← Validation tools
└── generate.js       ← Code generators
```

**Reference them in SKILL.md:**
```markdown
Run the setup script:
\`\`\`bash
bash scripts/setup.sh
\`\`\`
```

### Examples Directory

Real-world examples that demonstrate the skill:

```
examples/
├── basic-usage.js
├── advanced-pattern.ts
└── full-implementation/
    ├── index.js
    └── config.json
```

### Templates Directory

Reusable code templates:

```
templates/
├── component.tsx
├── test.spec.ts
└── config.json
```

**Reference in SKILL.md:**
```markdown
Use this template as a starting point:
\`\`\`typescript
{{#include templates/component.tsx}}
\`\`\`
```

### References Directory

External documentation or API references:

```
references/
├── api-docs.md
├── best-practices.md
└── troubleshooting.md
```

---

## Skill Size Guidelines

### Minimum Viable Skill
- **Frontmatter:** name + description
- **Content:** 100-200 words
- **Sections:** Overview + Instructions

### Standard Skill
- **Frontmatter:** name + description
- **Content:** 300-800 words
- **Sections:** Overview + When to Use + Instructions + Examples

### Comprehensive Skill
- **Frontmatter:** name + description + optional fields
- **Content:** 800-2000 words
- **Sections:** All recommended sections
- **Extras:** Scripts, examples, templates

**Rule of thumb:** Start small, expand based on feedback

---

## Formatting Best Practices

### Use Markdown Effectively

#### Code Blocks
Always specify the language:
```markdown
\`\`\`javascript
const example = "code";
\`\`\`
```

#### Lists
Use consistent formatting:
```markdown
- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2
```

#### Emphasis
- **Bold** for important terms: `**important**`
- *Italic* for emphasis: `*emphasis*`
- `Code` for commands/code: `` `code` ``

#### Links
```markdown
[Link text](https://example.com)
```

---

## ✅ Quality Checklist

Before finalizing your skill:

### Content Quality
- [ ] Instructions are clear and actionable
- [ ] Examples are realistic and helpful
- [ ] No typos or grammar errors
- [ ] Technical accuracy verified

### Structure
- [ ] Frontmatter is valid YAML
- [ ] Name matches folder name
- [ ] Sections are logically organized
- [ ] Headings follow hierarchy (H1 → H2 → H3)

### Completeness
- [ ] Overview explains the "why"
- [ ] Instructions explain the "how"
- [ ] Examples show the "what"
- [ ] Edge cases are addressed

### Usability
- [ ] A beginner could follow this
- [ ] An expert would find it useful
- [ ] The AI can parse it correctly
- [ ] It solves a real problem

---

## 🔍 Real-World Example Analysis

Let's analyze a real skill: `brainstorming`

```markdown
---
name: brainstorming
description: "You MUST use this before any creative work..."
---
```

**Analysis:**
- ✅ Clear name
- ✅ Strong description with urgency ("MUST use")
- ✅ Explains when to use it

```markdown
# Brainstorming Ideas Into Designs

## Overview
Help turn ideas into fully formed designs...
```

**Analysis:**
- ✅ Clear title
- ✅ Concise overview
- ✅ Explains the value proposition

```markdown
## The Process

**Understanding the idea:**
- Check out the current project state first
- Ask questions one at a time
```

**Analysis:**
- ✅ Broken into clear phases
- ✅ Specific, actionable steps
- ✅ Easy to follow

---

## Advanced Patterns

### Conditional Logic

```markdown
## Instructions

If the user is working with React:
- Use functional components
- Prefer hooks over class components

If the user is working with Vue:
- Use Composition API
- Follow Vue 3 patterns
```

### Progressive Disclosure

```markdown
## Basic Usage
[Simple instructions for common cases]

## Advanced Usage
[Complex patterns for power users]
```

### Cross-References

```markdown
## Related Workflows

1. First, use `@brainstorming` to design
2. Then, use `@writing-plans` to plan
3. Finally, use `@test-driven-development` to implement
```

---

## Skill Effectiveness Metrics

How to know if your skill is good:

### Clarity Test
- Can someone unfamiliar with the topic follow it?
- Are there any ambiguous instructions?

### Completeness Test
- Does it cover the happy path?
- Does it handle edge cases?
- Are error scenarios addressed?

### Usefulness Test
- Does it solve a real problem?
- Would you use this yourself?
- Does it save time or improve quality?

---

## Learning from Existing Skills

### Study These Examples

**For Beginners:**
- `skills/brainstorming/SKILL.md` - Clear structure
- `skills/git-pushing/SKILL.md` - Simple and focused
- `skills/copywriting/SKILL.md` - Good examples

**For Advanced:**
- `skills/systematic-debugging/SKILL.md` - Comprehensive
- `skills/react-best-practices/SKILL.md` - Multiple files
- `skills/loki-mode/SKILL.md` - Complex workflows

---

## 💡 Pro Tips

1. **Start with the "When to Use" section** - This clarifies the skill's purpose
2. **Write examples first** - They help you understand what you're teaching
3. **Test with an AI** - See if it actually works before submitting
4. **Get feedback** - Ask others to review your skill
5. **Iterate** - Skills improve over time based on usage

---

## Common Mistakes to Avoid

### ❌ Mistake 1: Too Vague
```markdown
## Instructions
Make the code better.
```

**✅ Fix:**
```markdown
## Instructions
1. Extract repeated logic into functions
2. Add error handling for edge cases
3. Write unit tests for core functionality
```

### ❌ Mistake 2: Too Complex
```markdown
## Instructions
[5000 words of dense technical jargon]
```

**✅ Fix:**
Break into multiple skills or use progressive disclosure

### ❌ Mistake 3: No Examples
```markdown
## Instructions
[Instructions without any code examples]
```

**✅ Fix:**
Add at least 2-3 realistic examples

### ❌ Mistake 4: Outdated Information
```markdown
Use React class components...
```

**✅ Fix:**
Keep skills updated with current best practices

---

## 🎯 Next Steps

1. **Read 3-5 existing skills** to see different styles
2. **Try the skill template** from [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md)
3. **Create a simple skill** for something you know well
4. **Test it** with your AI assistant
5. **Share it** via Pull Request

---

**Remember:** Every expert was once a beginner. Start simple, learn from feedback, and improve over time! 🚀