Skill

Skill Structure

How to organize SKILL.md, references, scripts, and assets so agents can load expertise on demand.

Minimum directory

A Skill is a directory with one required file: SKILL.md. The folder name should be stable and readable because users and tools often surface it in catalogs.

data-cleanup/
└── SKILL.md

SKILL.md format

The file starts with YAML frontmatter, followed by Markdown instructions. At minimum, provide a short name and a trigger-focused description.

---
name: data-cleanup
description: Clean messy CSV or spreadsheet data, normalize columns, and produce a validation report.
---

# Data Cleanup

Use this skill when the user asks to clean, normalize, validate, or prepare tabular data.

## Workflow
1. Inspect the source file and identify schema issues.
2. Normalize column names and data types.
3. Produce a concise report with assumptions and unresolved rows.

Optional directories

Keep the main instructions compact. Move supporting material into predictable folders and tell the agent exactly when to load each file.

references/

Background docs, policies, schemas, examples, and detailed domain explanations.

scripts/

Reusable helpers for parsing, validation, conversion, scoring, or repetitive mechanical work.

assets/

Templates, sample files, report formats, snippets, prompt fragments, and other reusable resources.

Referencing resources

Do not ask the agent to load a whole directory. Put clear conditional instructions in SKILL.md so context is spent only when useful.

Better instruction Read references/validation-rules.md only when the input file has invalid rows, then map each issue to the cleanup checklist.

Validation checklist

NameThe frontmatter name is short, stable, and matches the folder intent.

DescriptionThe description says when to use the Skill and when not to use it.

BodyThe body gives procedure, defaults, gotchas, and success criteria.

ResourcesReferences and scripts are named clearly and loaded conditionally.