DOCS · For Authors

SKILL.md Spec

How to structure a skill bundle, its frontmatter, and the files that make it score well on a SaferSkills scan.

A skill is a directory anchored by a SKILL.md manifest that declares what the skill does, plus the documentation and licensing files a reviewer needs to trust it. SaferSkills scores a skill on five axes; this page describes the structure of a well-formed skill bundle, the manifest fields, and the concrete file-presence and content signals that move your Transparency and Security sub-scores. Every signal below maps to a real, published rule.

What is the shape of a skill bundle?

A skill is a directory, not a single file. The directory is recognized as a skill by the presence of a SKILL.md manifest at its root. SaferSkills’ capability discovery walks a repository’s file tree and treats any directory containing SKILL.md as a skill capability; one repository can hold several capabilities (a skill, an MCP server, hooks), and each is discovered and scored independently. A minimal, scannable bundle looks like this:

my-skill/
├── SKILL.md          # the manifest — what makes this a skill
├── README.md         # human entry point: what it does, how to use it
├── LICENSE           # how the artifact may be used
├── CHANGELOG.md      # what changed between releases
├── SECURITY.md       # how to report a vulnerability
└── scripts/          # any supporting code, kept out of the docs

None of these files is invented for SaferSkills. SKILL.md is the canonical Claude Code skill manifest (Anthropic skills documentation); the surrounding files are standard open-source hygiene. SaferSkills scores their presence because each one is a transparency signal a reviewer relies on before letting an agent load your skill.

What goes in the SKILL.md manifest?

SKILL.md is Markdown with a YAML frontmatter block. The frontmatter declares the skill’s identity; the body explains its behavior. At minimum, declare a name and a description:

---
name: pdf-extract
description: Extracts text from PDF files in the working directory.
---

# pdf-extract

This skill reads PDF files in the current working directory and returns their
text content. It does not write files, make network calls, or run shell
commands.

The description is the field an agent reads to decide whether the skill is relevant to a task, so make it a precise statement of purpose, expected inputs, and behavior — the contract a reviewer can check the skill against. SaferSkills detects the manifest by filename (it accepts SKILL.md, skill.yaml, skill.yml, or skill.json), and at v1 it checks for presence, not content quality: a present-but-empty manifest satisfies the structural rule. Even so, an empty manifest defeats the purpose — the reason the manifest counts is that it lets a reviewer evaluate your skill without reading every file in the repo.

What makes a skill score well?

A skill scores well on two independent fronts: it is transparent (the documentation a reviewer needs is present) and it is clean (the source contains none of the injection or obfuscation patterns that trip the Security sub-score). The two are scored separately and both matter.

The transparency files

The Transparency sub-score is dominated by file-presence checks. Each missing file is a documented finding; the cumulative effect of missing several is a meaningful sub-score reduction, while adding each is a one-time, low-cost fix. The signals, with their real rules:

A note on what these rules do not check: at v1 they assess presence, not content. A LICENSE containing arbitrary text, a one-line README, or an empty CHANGELOG all satisfy the structural rule. Content validation (SPDX-identifier checks, manifest-content quality) is a deferred enhancement, not a present-tense claim. Documentation managed entirely outside the repo — a GitHub-Releases-only changelog, a GHSA-only disclosure policy with no file — is not detected and still fires the rule, so commit the file even if you also publish elsewhere.

Keeping the source clean

The Security sub-score carries 35% of the aggregate weight, and a single serious finding caps the whole score regardless of how good your docs are (an active critical caps the aggregate at ≤15; an active high at ≤45). The patterns that fire here are the ones that turn skill documentation into an executable payload, because an agent reads your SKILL.md as trusted instructions. The most consequential, with their real rules:

These are three of the security rules that apply to skills; SaferSkills also checks for prompt injection via imperative phrasing, role-play overrides, homoglyphs, bidirectional-text tricks, and zero-width characters. Browse the full, current list — every rule with its severity, trigger, and limitations — on the live methodology page.

How do I confirm my changes worked?

Re-submit the repo at /scan and read the updated report. Because scoring is deterministic, the same bytes against the same rubric_version always produce the same score, so you can iterate locally and verify each change lands. The report renders the per-finding penalty and the running sub-score, so you can see exactly which file or pattern moved the number. To install your scanner-clean skill into an agent, or to gate installs on a minimum score, see Install a skill.

Where do I go next?

Author: SaferSkills Team — methodology maintainers.