SKILL.md is the mandatory file in an agent skill directory. YAML frontmatter supplies a short, stable name and a description that signals when the skill should activate; the Markdown body gives the agent procedures, standards, output schemas, validation rules, or examples. section 2.3.1
The description acts as a discovery filter, while the body provides specialized context when relevant. A harness may activate a skill automatically from the request or support explicit invocation; directory locations vary by platform. Optional scripts, references, assets, and tests can support the skill alongside SKILL.md. section 2.3.1 section 2.5.2
Listing 2.2 Content of the SKILL.md file for the git-conventional-commits skill
--- name: git-conventional-commits description: Generates standardized git commit messages following the conventional commits spec. Use this when the user asks to commit changes or "wraps up" a task. license: MIT metadata: version: "1.0.0" --- # Git Conventional Commits ## Instructions When the user asks to commit, follow these steps: 1. Identify the primary change in the code. 2. Categorize the change into one of these types: feat, fix, docs, style, refactor, perf, test, or chore. 3. Format the message as: `<type>(<scope>): <description>` ## Examples - feat(auth): add Google OAuth support - fix(ui): resolve alignment issue on mobile
A commit-message skill combines activation metadata with steps for classifying a code change and formatting the result. section 2.3.1
Listing 2.6 Content of the SKILL.md file for the project notetaker skill
--- name: project-notetaker description: Formats unstructured meeting notes into a structured project report. Use this when the user provides raw notes or requests a summary of a meeting. --- # Project Notetaker ## Instructions When the user provides meeting notes, follow this structure: 1. Title: A clear name for the meeting. 2. Attendees: List all participants. 3. Key decisions: A bulleted list of what was decided. 4. Action items: A table with columns for task, owner, and due date.
A meeting-notes skill specifies when to activate and a fixed report structure for attendees, decisions, and action items. section 2.5.2


