SKILL.md Format Complete Guide: Specification and Best Practices

The SKILL.md format is the foundation of Gemini CLI's extensibility model. Understanding its structure and capabilities is essential for anyone building custom skills or evaluating existing ones. This guide serves as both a reference specification and a practical tutorial for mastering the format.

Every SKILL.md file begins with YAML frontmatter enclosed in triple dashes. Required fields include name (unique identifier), description (human-readable summary), version (semver string), and triggers (conditions that activate the skill). Optional but recommended fields include author, license, minGeminiVersion, dependencies (other skills required), and parameters (typed input definitions with defaults and validation rules). The frontmatter establishes the skill's identity and contract with the Gemini runtime.

The instruction body uses Markdown with embedded template syntax. Template variables are enclosed in double curly braces and reference input parameters, project context, or environment state. Conditional blocks use a familiar if-else syntax to handle different scenarios within a single skill definition. You can define output sections that specify the expected format of the skill's results, enabling downstream skills to parse and chain outputs reliably. Multi-step skills use numbered sections with explicit handoff points where Gemini can request user confirmation before proceeding.

Advanced features include skill composition through the import directive, which lets you reference other skills as sub-routines. Error handling blocks define fallback behavior when primary instructions cannot be completed. The testing section at the end of the file specifies example inputs and expected outputs used by the skill test command for validation. Following these format conventions strictly ensures your skills are compatible with the marketplace review process and render correctly in documentation generators.