---
topic: agentskills-examples
source_keys:
  - agentskills-quickstart
  - agentskills-spec
  - agentskills-best-practices
  - agentskills-optimizing-descriptions
---

## Minimal skill (quickstart)

```
.agents/skills/roll-dice/SKILL.md
```

```markdown
---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).
```

This is a complete, working skill: one file, under 20 lines. The `name` matches the directory name; the description is specific and imperative.

## Extended frontmatter

```yaml
---
name: pdf-processing
description: >
  Extract text and tables from PDF files, fill PDF forms, and merge multiple
  PDFs. Use when the user mentions PDFs, forms, document extraction, or needs
  to work with PDF files — even if they don't use the word "PDF."
license: Apache-2.0
compatibility: Requires python3, uv, and pdfplumber
metadata:
  author: example-org
  version: "1.0"
  category: document
---
```

## Description before and after

```yaml
# Before — too vague, won't trigger reliably
description: Process CSV files.

# After — specific about capabilities, broad about when to apply
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to explore,
  transform, or visualize the data, even if they don't explicitly mention
  "CSV" or "analysis."
```

## Gotchas section

```markdown
## Gotchas

- The `users` table uses soft deletes. Always include `WHERE deleted_at IS NULL`.
- User ID is `user_id` in the database, `uid` in the auth service, and
  `accountId` in the billing API — they all refer to the same entity.
- `/health` returns 200 even when the database is down. Use `/ready` instead.
```

## Output format template inline

```markdown
## Report structure

Use this template:

\`\`\`markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data

## Recommendations
1. Specific actionable recommendation
\`\`\`
```

## Multi-step checklist

```markdown
## Form processing workflow

Progress:
- [ ] Step 1: Analyze the form (`scripts/analyze_form.py`)
- [ ] Step 2: Create field mapping (`fields.json`)
- [ ] Step 3: Validate mapping (`scripts/validate_fields.py`)
- [ ] Step 4: Fill the form (`scripts/fill_form.py`)
- [ ] Step 5: Verify output (`scripts/verify_output.py`)
```

## Plan-validate-execute pattern

```markdown
## Database migration

1. Run `python scripts/migrate.py --verify --backup`
2. Review the migration plan output
3. If plan looks correct, run `python scripts/migrate.py --execute`

Do not modify commands or add flags.
```

## Conditional reference loading

```markdown
## Error handling

If the API returns a non-200 status code, read `references/api-errors.md`
for the full error code table and retry guidance.
```

## Eval test case (evals.json)

```json
{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "I have a CSV of monthly sales data in data/sales_2025.csv. Find the top 3 months by revenue and make a bar chart.",
      "expected_output": "A bar chart image showing the top 3 months by revenue, with labeled axes.",
      "files": ["evals/files/sales_2025.csv"],
      "assertions": [
        "The output includes a bar chart image file",
        "The chart shows exactly 3 months",
        "Both axes are labeled",
        "The chart title or caption mentions revenue"
      ]
    }
  ]
}
```