swe-re-expert

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 ---:

---
name: my-skill-name
description: "Brief description of what this skill does"
category: development
risk: safe
source: community
source_type: community
date_added: "YYYY-MM-DD"
---

Required Fields

name

description

category

risk

source

source_repo

source_type

date_added

Optional Fields

Some skills include additional metadata:

---
name: my-skill-name
description: "Brief description"
category: development
risk: safe
source: community
source_type: community
date_added: "YYYY-MM-DD"
tags: ["react", "typescript", "testing"]
tools: [claude, cursor, gemini]
---

license (optional)

license_source (optional)

Source-credit contract

Part 2: Content

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

1. Title (H1)

# Skill Title

2. Overview

## Overview

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

3. When to Use

## 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

## 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

## 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

## Best Practices

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

7. Common Pitfalls

## Common Pitfalls

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

8. Security & Safety Notes (for command/network/offensive skills)

If your skill includes:

add a dedicated section before final wrap-up:

## Security & Safety Notes

- This is safe/unsafe scope
- Required confirmation or authorization
- Example allowlist notes (if needed):
  `<!-- security-allowlist: ... -->`

## Related Skills

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

Writing Effective Instructions

Use Clear, Direct Language

❌ Bad:

You might want to consider possibly checking if the user has authentication.

✅ Good:

Check if the user is authenticated before proceeding.

Use Action Verbs

❌ Bad:

The file should be created...

✅ Good:

Create the file...

Be Specific

❌ Bad:

Set up the database properly.

✅ Good:

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:

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:

Use this template as a starting point:
```typescript

```

References Directory

External documentation or API references:

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

Skill Size Guidelines

Minimum Viable Skill

Standard Skill

Comprehensive Skill

Rule of thumb: Start small, expand based on feedback

Formatting Best Practices

Use Markdown Effectively

Code Blocks

Always specify the language:

```javascript
const example = "code";
```

Lists

Use consistent formatting:

- Item 1
- Item 2
  - Sub-item 2.1
  - Sub-item 2.2

Emphasis

[Link text](https://example.com)

✅ Quality Checklist

Before finalizing your skill:

Content Quality

Structure

Completeness

Usability

🔍 Real-World Example Analysis

Let’s analyze a real skill: brainstorming

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

Analysis:

# Brainstorming Ideas Into Designs

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

Analysis:

## The Process

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

Analysis:

Advanced Patterns

Conditional Logic

## 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

## Basic Usage
[Simple instructions for common cases]

## Advanced Usage
[Complex patterns for power users]

Cross-References

## 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

Completeness Test

Usefulness Test

Learning from Existing Skills

Study These Examples

For Beginners:

For Advanced:

💡 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

## Instructions
Make the code better.

✅ Fix:

## 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

## Instructions
[5000 words of dense technical jargon]

✅ Fix: Break into multiple skills or use progressive disclosure

❌ Mistake 3: No Examples

## Instructions
[Instructions without any code examples]

✅ Fix: Add at least 2-3 realistic examples

❌ Mistake 4: Outdated Information

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
  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! 🚀

This site is open source. Improve this page.