Agent Skills Standard Compatibility Requirements and SKILL.md Frontmatter Explained

Agent Skills standard compatibility requires a mandatory YAML frontmatter block with name and description keys, a strict section ordering, token budgets under 4,000 tokens, and host-agnostic tooling declarations in the SKILL.md file.

The book-to-skill repository generates skills that work across AI hosts like GitHub Copilot CLI, Amp, and Claude Code by implementing the open Agent Skills standard. This article breaks down the exact requirements from the source code, including the critical frontmatter structure, validation rules, and architectural patterns that ensure cross-host compatibility.

SKILL.md Frontmatter Requirements

Every generated skill must begin with a YAML frontmatter block as the very first element of the file. The block is delimited by triple dashes and contains exactly two mandatory keys according to the SKILL.md template:

• name — the skill slug used for directory naming and host loading
• description — a short, quoted sentence displayed in host UIs

---
name: my-skill
description: "A concise skill description"
---

The frontmatter must be pure YAML. Any stray characters or malformed syntax break compatibility with generic skill loaders like skills list in Copilot CLI. The name field becomes the directory name under $SKILLS_HOME/<skill-name>/, while description appears when users browse available skills.

Optional Argument Hint

Immediately following the frontmatter, you may include an argument hint comment that tells the host what parameters the skill accepts. This appears at line 70 of SKILL.md:

<!-- argument-hint: [topic, framework name, or chapter number] -->

This optional annotation improves the user experience by suggesting valid invocation patterns without affecting parsing.

Mandatory Section Ordering

The body of SKILL.md must include six standardized sections in strict order. The order matters because hosts truncate content from the end when token limits are approached. The required sequence appears in lines 75-87 of SKILL.md:

1. How to Use This Skill
2. Core Frameworks & Mental Models
3. Chapter Index
4. Topic Index
5. Supporting Files (glossary, patterns, cheatsheet)
6. Scope & Limits

Any deviation from this order risks content loss during host truncation.

Token Budget Constraints

The Agent Skills standard enforces strict token limits to ensure predictable host performance. According to lines 59-62 of SKILL.md:

Component	Maximum Tokens
Main SKILL.md body	4,000
Glossary file	1,500
Patterns file	2,000
Cheatsheet file	1,200

These caps are enforced by tools/validate_skill.py, which fails the build if any limit is exceeded.

Host-Agnostic Tooling Declaration

The skill must not declare allowed-tools in its frontmatter. The repository explicitly omits this field at lines 11-14 of SKILL.md to remain host-agnostic. This allows any compatible host to provide its own appropriate toolset rather than restricting execution to specific capabilities.

File System Placement

Generated skills must reside in recognized discovery roots for hosts to locate them. The standard locations documented at lines 65-78 of SKILL.md include:

• ~/.copilot/skills/
• .github/skills/
• ~/.agents/skills/

The host discovers skills by scanning these directories and parsing each SKILL.md frontmatter.

Validation Pipeline

After generation, the repository runs automated compliance checks via tools/validate_skill.py. This script verifies:

• Presence and syntax of the --- frontmatter block
• That name and description are valid strings
• Total token count ≤ 4,000 for the main body
• Supporting files respect individual token caps

Invoke validation manually with:

python -m book_to_skill.tools.validate_skill path/to/skill_folder

Minimal Compatible SKILL.md Example

---
name: example-skill
description: "Extracted knowledge from Example Book for quick reference."
---
<!-- argument-hint: [topic, framework name, or chapter number] -->

# Example Book Title

**Author**: Jane Doe | **Pages**: ~300 | **Chapters**: 12 | **Generated**: 2026-08-25

## How to Use This Skill

- Without arguments – load core frameworks.
- With a topic – e.g. `example-skill pricing`.
- With chapter – e.g. `example-skill ch03`.

---

## Core Frameworks & Mental Models

- **Framework One** – concise description.
- **Mental Model A** – short actionable rule.

---

## Chapter Index

| # | Title | Key Frameworks |

|---|-------|----------------|
| [ch01](chapters/ch01-intro.md) | Introduction | Framework One |
| [ch02](chapters/ch02-deep.md) | Deep Dive | Framework Two |

---

## Topic Index

- **Term A** → ch01, ch04
- **Term B** → ch02

---

## Supporting Files

- [glossary.md](glossary.md) — key terms.
- [patterns.md](patterns.md) — reusable techniques.
- [cheatsheet.md](cheatsheet.md) — quick-reference decisions.

---

## Scope & Limits

This skill covers only the content of *Example Book*.

Architectural Flow for Compliance

The book-to-skill pipeline ensures Agent Skills compatibility through five deterministic stages:

1. Extraction (scripts/extract.py) — creates temporary work directory with full_text.txt and metadata.json
2. Analysis & generation — produces chapters/, glossary.md, patterns.md, cheatsheet.md
3. Master SKILL.md assembly — injects mandatory frontmatter and ordered sections
4. Security scan (tools/scan_generated_skill.py) — checks for malicious content
5. Validation (tools/validate_skill.py) — enforces token budgets and structural rules

All stages respect the constraints required by the Agent Skills specification.

Adding a Validated Skill to Hosts

Because the skill follows the standard contract, it installs identically across hosts:

# GitHub Copilot CLI

skills reload
skills list | grep example-skill

# Amp

amp skill add ~/.agents/skills/example-skill

# Claude Code

npx skills add https://github.com/yourname/example-skill

Summary

• Frontmatter is mandatory: name and description keys in pure YAML at the very top of SKILL.md
• Section order is load-bearing: How to Use → Core Frameworks → Chapter Index → Topic Index → Supporting Files → Scope & Limits
• Token budgets are strict: 4,000 for main body, with separate caps for supporting files
• Avoid allowed-tools: Keep skills host-agnostic by omitting tool declarations
• Validate before distribution: Run tools/validate_skill.py to catch compliance issues early

Frequently Asked Questions

What happens if the frontmatter is malformed?

Hosts will fail to load the skill. The generic skill loader parses the --- block as strict YAML—any syntax error causes the skill to be invisible in skills list or similar discovery commands. The validate_skill.py script catches these errors before distribution.

Can I add custom keys to the frontmatter?

The Agent Skills standard reserves name and description as required keys. Additional keys may be ignored by hosts or cause parsing failures. The book-to-skill repository follows a minimal approach: only the two mandatory keys plus optional HTML comments for hints.

Why does section order matter if all content is present?

Hosts truncate from the end when approaching context limits. By placing Scope & Limits last and How to Use This Skill first, critical invocation guidance survives truncation while less urgent disclaimers may be dropped.

How do I check my skill's token count before validation?

The validation script automatically computes tokens, but you can estimate manually. In Python, use tiktoken or similar encoders. The book-to-skill pipeline uses the same encoding as the target hosts to ensure consistent measurements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}