Full guide
Follow the sections in order, then adapt commands to your current environment.
Agent Skills Format Specification
This document defines the complete format specification for Agent Skills (SKILL.md files) across all AI coding platforms.
Directory Structure
A skill is a self-contained directory with a mandatory SKILL.md file:
Terminal
skill-name/
├── SKILL.md # Mandatory: Entry point & metadata
├── scripts/ # Optional: Executables (sh, py, js, etc.)
├── references/ # Optional: Static docs (md, txt, json)
└── assets/ # Optional: Non-executable assets (images, templates)SKILL.md Content
YAML Frontmatter (Required)
The file must begin with a YAML block:
yaml
---
name: unique-skill-name
description: Clear description used for discovery
metadata:
version: 1.0.0
author: Name
---Markdown Body (Required)
The rest of the file should contain instructions in Markdown format. Recommended sections include:
# Title## Overview## When to Use## Instructions## Available Tools(referencingscripts/)
Discovery Mechanism
Agents discover skills based on the description field in the frontmatter.
- Indexing: Agents read all frontmatter blocks in skill directories.
- Matching: User prompts are compared against descriptions using vector search or keyword matching.
- Activation: Full skill content is loaded only when a match is found.
Best Practices for Format
- Naming: Use lowercase hyphenated names (
git-expert). - Paths: Reference scripts using relative paths (
scripts/analyze.sh). - Portability: Use
#!/usr/bin/envfor script shebangs.