structure

Anatomy of a skill

Most skills are a small directory. The markdown file is the contract; everything else is supporting material.

Example layout

demo-csv-cleanup/
  SKILL.md
  scripts/
    normalize.py
  references/
    column-map.example.json

Frontmatter

Frontmatter sits at the top of SKILL.md between --- lines. Agents and catalogs typically index name and description. Descriptions should say what the skill does and when to load it.

Example SKILL.md

The identity below is fictional and for illustration only.

---
name: demo-csv-cleanup
description: >
  Normalize messy CSV exports: trim headers, map aliases,
  and write a clean UTF-8 file. Use when the user asks to
  clean spreadsheet exports or fix column names.
---

# CSV cleanup

## When to use
- User provides a CSV (or path) with inconsistent headers.
- Goal is a cleaned file, not database migration.

## Steps
1. Confirm the input path and desired output path.
2. Read headers; show a proposed mapping before writing.
3. Run `scripts/normalize.py` with the approved mapping.
4. Report row counts and any dropped columns.

## Rules
- Do not upload the file anywhere.
- Do not invent columns that were not in the source.
- If the file is binary or encrypted, stop and ask.

Helpers

Optional scripts should be deterministic and documented in the skill body (arguments, expected cwd, side effects). Reference files hold examples or schemas the agent should open only when the steps say so.