Structure

A well-structured SKILL.md follows a consistent section pattern that AI agents are optimized to parse and apply. This page covers the required and optional sections, and how large skills are split into directories.

Required Sections

Overview

A brief introduction explaining what the skill covers and when it applies. This section helps agents determine whether to activate the skill for a given task. Keep it to 2-4 sentences.

Instructions

The core of the skill. Instructions must use imperative voice — direct commands that tell the agent what to do. Avoid hedging language like “you should consider” or “it's recommended to.”

## Instructions

- Use CSS Grid for two-dimensional layouts
- Apply flexbox for single-axis alignment
- Set explicit grid areas for complex page structures
- Prefer gap over margin for spacing between grid items
- Use min() and clamp() for responsive sizing without media queries

## Instructions

- You should consider using CSS Grid for layouts
- It's recommended to apply flexbox for alignment
- You might want to set explicit grid areas
- Consider using gap instead of margin

Examples

Concrete input/output pairs that demonstrate the skill in action. Each example should have a title, an input (the starting state or prompt), and an output (the expected result).

## Examples

### Example 1: Responsive Card Grid

**Input:**
Create a responsive card grid that shows 1 column on mobile,
2 on tablet, and 3 on desktop.

**Output:**
```css
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 1.5rem;
}
```

Guidelines

Additional rules, constraints, edge cases, and best practices that supplement the instructions. Guidelines provide nuance that the instructions section may not cover.

Optional Sections

Beyond the four required sections, you can add any additional H2 sections relevant to your skill:

• ●Anti-Patterns — common mistakes to avoid
• ●Troubleshooting — solutions for common issues
• ●References — links to external documentation or resources
• ●Glossary — definitions of domain-specific terms

Full Structure Template

---
name: skill-name
description: Brief description
---

# Skill Name

## Overview

2-4 sentences explaining the skill's purpose and scope.

## Instructions

- Imperative instruction 1
- Imperative instruction 2
- Imperative instruction 3

## Examples

### Example 1: Title

**Input:**
Starting state or prompt.

**Output:**
Expected result or code.

### Example 2: Title

**Input:**
...

**Output:**
...

## Guidelines

- Additional rule or best practice
- Edge case to be aware of
- Constraint or limitation

Directory Structure for Large Skills

When a skill's content exceeds the 5,000-word limit, Smidge automatically splits it into a directory structure with a main file and reference documents:

skill-name/
├── SKILL.md              # Main skill file (under 5,000 words)
└── references/
    ├── api-reference.md  # Detailed API documentation
    ├── examples.md       # Extended examples
    └── patterns.md       # Additional patterns

The main SKILL.md contains the core instructions and summary examples. The references/ directory holds supplementary material that the agent can reference when needed.