SKILL.md Specification

The Agent Skills standard defines an open format for packaging knowledge and instructions into files that AI coding agents can consume. Smidge generates spec-compliant SKILL.md files that work across all major platforms.

Overview

A SKILL.md file is a Markdown document with YAML frontmatter. It contains structured sections that teach an AI agent how to perform a specific task, follow certain patterns, or apply domain expertise.

The format is intentionally simple — it's just Markdown. Any text editor can create and modify skills. The structure and conventions exist to ensure consistency and machine-readability across different agent platforms.

File Structure

Every valid SKILL.md file has this structure:

SKILL.md

---
name: skill-name
description: A brief description of what the skill teaches
---

# Skill Name

## Overview

Brief description of the skill's purpose and scope.

## Instructions

Imperative instructions the agent should follow.

## Examples

### Example 1: Title

**Input:**
Description or code showing the starting state.

**Output:**
Description or code showing the expected result.

## Guidelines

Additional rules, constraints, and best practices.

Compatibility

The SKILL.md format is supported by:

●Claude Code — ~/.claude/skills/
●Cursor — ~/.cursor/skills/
●OpenAI Codex CLI — ~/.codex/skills/
●GitHub Copilot — .github/skills/
●Gemini CLI — ~/.gemini/skills/
●Windsurf, Zed, Continue, Cline, Roo Code, Goose, Amp — filesystem or tool-based discovery
●ChatGPT, Claude.ai — upload as file attachment or paste into system prompt

The spec is designed to be agent-agnostic and is supported by 30+ AI agents. Any AI system that reads Markdown files can benefit from the structured format.

Smidge-Specific Additions

Skills generated by Smidge include additional frontmatter fields for attribution:

Smidge frontmatter additions

---
name: css-layout-expert
description: Expert CSS layout patterns using flexbox and grid
generated_by: smidge
generator_url: https://smdg.app
version: "1.0"
---

●generated_by — always set to smidge for Smidge-generated skills
●generator_url — link back to https://smdg.app
●version — skill version string, starting at "1.0"

Smidge also appends a small footer to the end of generated skills:

Footer

---
*Generated by [Smidge](https://smdg.app) — SKILL.md generator for AI coding agents.*

Note

These additions are fully compatible with the Agent Skills spec. The extra frontmatter fields are ignored by platforms that don't recognize them, and the footer is treated as regular Markdown content.

Previous← Commands Reference NextFrontmatter →

Overview

File Structure

Every valid SKILL.md file has this structure:

SKILL.md

---
name: skill-name
description: A brief description of what the skill teaches
---

# Skill Name

## Overview

Brief description of the skill's purpose and scope.

## Instructions

Imperative instructions the agent should follow.

## Examples

### Example 1: Title

**Input:**
Description or code showing the starting state.

**Output:**
Description or code showing the expected result.

## Guidelines

Additional rules, constraints, and best practices.

Compatibility

The SKILL.md format is supported by:

●Claude Code — ~/.claude/skills/

●Cursor — ~/.cursor/skills/

●OpenAI Codex CLI — ~/.codex/skills/

●GitHub Copilot — .github/skills/

●Gemini CLI — ~/.gemini/skills/

●Windsurf, Zed, Continue, Cline, Roo Code, Goose, Amp — filesystem or tool-based discovery

●ChatGPT, Claude.ai — upload as file attachment or paste into system prompt