A skill is a SKILL.md with YAML frontmatter (name, description) and a procedural body. Skills teach procedures. For new capabilities (code that does something), write a tool instead — load the self skill for tool authoring.

Write a skill only when the task recurs, the procedure is non-obvious, and a description can match unseen phrasings. For one-off work, just do it. skill() first — never duplicate an existing skill.

Where it goes

Write to ~/.agents/skills/<name>/SKILL.md. <name> is kebab-case, ideally one short word, and unique against the existing list (skill()).

Anatomy

---
name: <kebab-case>
description: <one line — pack with the user phrasings that should trigger this skill>
---

<terse procedural body: trigger condition, then steps, concrete commands>

new-skill

Where it goes

Anatomy