SKILL.md format

A skill is a single Markdown file with YAML front-matter at the top. The front-matter is what the registry indexes; the body is what the agent reads. The format is intentionally small: anything an agent cannot parse with two regexes does not belong in front-matter.

Required vs. optional fields

The author field is set automatically from the GitHub account that submits the skill. You cannot override it from the file, even if you include it in front-matter.

Body conventions

The body is plain Markdown. The registry does not enforce sections, but agents work best when they can find specific information quickly. The convention across most skills:

• ## Description — what the skill does, in 2-4 sentences
• ## Parameters — named inputs the agent passes, with types and short descriptions
• ## Returns — output shape, ideally as a TypeScript snippet for clarity
• ## Examples — optional, but agents pick the skill more reliably when example prompts are present

The body has a hard cap of 20,000 characters and cannot be empty. Beyond that, the only requirements come from the verifier: the body has to be coherent enough that Claude can score it.

What the server strips on submit

The body goes through a sanitiser before storage. The rules are defensive against future renderers (RSS, email, MCP responses) that may treat the stored text as HTML. The current detail page renders with react-markdown without rehype-raw, so none of this is exploitable at render time today — this is defence in depth.

• Stripped tags: <script>, <iframe>, <object>, <embed>, <style>, <link>, <meta>, <base>, <form>, <svg>
• Stripped attributes: any inline event handler matching on*= (e.g. onclick, onload)
• Rewritten: javascript: URLs become js-removed:

Regular angle brackets in code samples are preserved. Generics like Array<string> and <T extends Foo> stay intact, so TypeScript and Rust examples render the way you wrote them.

Title duplication on the detail page

The skill detail page already shows the skill name as a heading above the body. To avoid a doubled title, the renderer strips a leading YAML frontmatter block and a single leading # Heading from the body before rendering. You can leave a # skill-name at the top of your file if you want (some authors do, for GitHub preview), and the detail page will skip it.

Worked example

A realistic skill with all the conventions in place:

---
name: pdf-extract
description: Extract text, tables, and metadata from PDF documents
version: 1.2.0
tags: [documents, parsing, pdf]
---

## Description

Extracts structured text, tables, and metadata from PDF files using pdfjs.
Handles scanned PDFs by falling back to OCR when no text layer is present.

## Parameters

- `path` (string): file path or URL of the PDF
- `pages` (string, optional): page range, e.g. "1-5" or "1,3,5"
- `include_images` (boolean, optional): extract embedded images (default false)

## Returns

```ts
{
  text: string;
  tables: Array<{ page: number; rows: string[][] }>;
  metadata: { title?: string; author?: string; created?: string };
  images?: Array<{ page: number; data: Buffer; mime: string }>;
}
```

## Examples

User: extract the executive summary from quarterly-report.pdf

Agent: calls pdf-extract with { path: "quarterly-report.pdf", pages: "1-3" },
then summarises the returned text.

Minimal template

The smallest file the validator and server will accept:

---
name: my-skill
description: One-line description, max 500 chars
---

## Description

What the skill does.

Run skillibary validate ./SKILL.md as you iterate. The validator covers every rule the server applies, so a green local check means the submit endpoint will accept the file too.

Next steps: CLI reference for install, validate, and publish, or jump back to Install if you want to consume skills rather than write them.