SKILL.md Format

A SKILL.md file defines a Copilot skill. It uses YAML frontmatter for metadata and Markdown for documentation.

Structure

SKILL.md

---
name: my-skill-name
description: A concise description of what this skill does.
---

## Usage

Explain when and how to use this skill.

## Examples

- "Example prompt 1"
- "Example prompt 2"

## References

- [Guide](references/guide.md)
- [API docs](references/api.md)

Frontmatter fields

Field	Type	Required	Constraints	Description
name	string	Yes	Kebab-case, ≤ 64 characters. Only lowercase letters, digits, and hyphens.	Unique identifier for the skill
description	string	Yes	≤ 1,024 characters	What the skill does
other fields	any	No	—	Any additional YAML fields are preserved in frontmatter

Name rules

Valid names:

• my-skill ✔
• code-reviewer-v2 ✔
• a ✔

Invalid names:

• My_Skill ✘ (uppercase, underscores)
• my skill ✘ (spaces)
• MY-SKILL ✘ (uppercase)
• “ (empty) ✘

File references

Markdown links in the body are parsed as file references:

[Guide](references/guide.md)
[API docs](references/api.md#section)
[External](https://example.com) <!-- ignored: external URL -->

Rules:

• Relative paths are resolved from the SKILL.md’s directory
• Fragment anchors (#section) are stripped for file existence checks
• External URLs (starting with http:// or https://) are ignored
• Links inside code fences are ignored
• The valid-refs grader checks that every referenced file exists
• The orphan-files grader checks that every file in references/ is reachable

Directory structure

A typical skill directory:

my-skill/
├── SKILL.md              # Required: skill definition
├── references/           # Optional: supporting files
│   ├── guide.md
│   ├── api-reference.md
│   └── examples/
│       └── usage.py
└── eval.yaml             # Optional: evaluation stimuli

Discovery

The discoverSkills() function (and vally lint) finds skills by recursively searching for SKILL.md files. It excludes:

• node_modules/ directories
• Hidden directories (starting with .)
• Symlinks

Parsed skill object

When parsed, a SKILL.md becomes a Skill object:

interface Skill {
  name: string; // From frontmatter
  description: string; // From frontmatter
  path?: string; // Filesystem path to SKILL.md
  rawContent: string; // Full file content
  frontmatter: Record<string, unknown>; // All YAML fields
  frontmatterParseError?: string; // Set if YAML was invalid
  fileReferences: FileReference[]; // Extracted from markdown links
}

interface FileReference {
  raw: string; // Original text from markdown
  normalized: string; // After stripping ./ and fragments
  segments: string[]; // Path segments
  line?: number; // Line number in the file
}

Validation rules

The lint command checks these rules via the spec-compliance grader:

Rule	Check
Name present	name field exists in frontmatter
Name format	Matches /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
Name length	≤ 64 characters
Description present	description field exists in frontmatter
Description length	≤ 1,024 characters