SKILL.md format

A skill is one file. This page documents exactly what SkillMD reads from it, what it ignores, and what the linter checks before you publish.

File structure

A SKILL.md file is YAML frontmatter delimited by --- lines, followed by a markdown body. The frontmatter block must start at the very first byte of the file. No leading blank line, no BOM, nothing before the opening ---. The whole file must be 256KB or smaller, or it gets rejected outright.

Frontmatter fields

The parser reads exactly three fields. Anything else you add to the frontmatter is silently ignored.

The body

Everything after the closing --- is plain markdown. The agent loads it on demand when it decides to use the skill. It should contain at least one markdown heading, meaning a line starting with one to six # characters followed by a space, and it should run past a couple hundred characters. A body that's just a stub, or has no heading at all, still passes but gets flagged with a warning.

Minimal example

This is the smallest file that passes validation. It has no license field, so skillmd lint would flag SK011 as a warning, not an error.

---
name: my-skill
description: "One clear sentence describing exactly what this skill does and when to use it."
---

## What this does

This skill helps an agent complete a specific, narrow task. Explain the
task here in plain language, so the agent knows when to reach for it.

## Instructions

Write the actual steps the agent should follow. Be specific about inputs,
outputs, and any edge cases the agent needs to handle along the way.

Fuller example

Same three fields, this time with a license, a longer description, and a body organized into sections.

---
name: pdf-table-extract
description: "Extracts tabular data from PDF documents and returns it as clean CSV or JSON, handling multi-page tables and merged cells."
license: MIT
---

## Overview

This skill extracts tables from PDF files, including tables that span
multiple pages or contain merged header cells. Use it whenever a task
asks for structured data pulled out of a PDF report, invoice, or form.

## Steps

First, identify every page that contains a table. Then extract each
table's rows and columns, preserving column order and header labels.
Merge tables that continue across a page break into a single result.
Normalize whitespace and currency formatting before returning output.

## Error handling

If a page is scanned as an image with no extractable text layer, say so
explicitly instead of returning empty or guessed data. If a table's
structure is ambiguous, such as cells that visually merge but have no
clear delimiter, flag the ambiguity in the output rather than silently
picking one interpretation.

Real-world examples

The registry itself is the best example library. Every skill page shows the full SKILL.md, rendered and raw, and serves a markdown variant at /skills/<owner>/<name>.md. Start with the official skills from verified publishers, or the most-installed skills to see the patterns that get reused. New to the format? Read What is an Agent Skill? first.

Lint rules

Run skillmd lint against your file before publishing. Errors fail the check; warnings do not.

The rule numbers are intentionally sparse, leaving room to add more without renumbering. Run skillmd rules to list all of them, or skillmd rules SK010 to see one on its own.

Quality score

Every skill gets a quality score from 0 to 100, shown on its listing. It starts at 100 and loses points for problems: each lint error costs 30 points, each warning costs 10. On top of that, a lightweight textual scan of the body looks for patterns and subtracts further: reading secrets costs 25, executing scripts costs 15, making network calls costs 8, and a docs-only body costs nothing.

Because the scan is purely textual, it can't tell intent from content. A skill that simply documents an example shell command, or mentions the phrase "API key" in passing, can trip a flag meant for something riskier. If you want a clean score, keep example commands minimal and avoid pasting anything that looks like a credential, even as a placeholder.

Gotchas

• Frontmatter must start at byte 0 of the file. A leading blank line or BOM breaks parsing.
• Newlines inside description collapse to single spaces, so multi-line descriptions won't render the way they look in your editor.
• Extra frontmatter keys beyond name, description, and license are ignored, not rejected.
• An over-long description doesn't just get truncated. It rejects the entire file.
• Always run skillmd lint locally before publishing. It catches everything above before the registry sees it.
• Use skillmd init <skill-name> to scaffold a valid file instead of writing the frontmatter by hand.