How To Write AI Skills

Overview

Write skills as compact, reusable guidance for a smart and capable model.

Default to a self-contained SKILL.md. Keep the skill portable, concise, and easy to trigger.

Default Approach

• Prefer one self-contained SKILL.md.
• Keep the skill high level by default. Give recommendations, decision rules, and good defaults rather than rigid scripts.
• Use strict rigid step-by-step instructions only when the user explicitly asks for them or the task is fragile enough that ambiguity is likely to cause failure.
• Avoid teaching basics the model already knows.
• If the skill is growing too large, first cut repetition and boilerplate. If it is still too large, move heavy reference material or reusable tools into separate files only when they are clearly justified. Split into multiple skills only when the responsibilities are genuinely different.

Frontmatter

Use portable frontmatter first.