# Agent Skills Standard Compatibility Requirements and SKILL.md Frontmatter Explained

> Learn Agent Skills standard compatibility requirements including mandatory YAML frontmatter name and description keys section ordering token budgets and host agnostic tooling in SKILL.md.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: api-reference
- Published: 2026-08-25

---

**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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md#L1-L4):

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

```yaml
---
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](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md#L70):

```markdown
<!-- 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md#L75-L87):

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](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md#L59-L62):

| Component | Maximum Tokens |
|-----------|---------------|
| Main [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md#L11-L14) 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](https://github.com/virgiliojr94/book-to-skill/blob/master/SKILL.md#L65-L78) include:

- `~/.copilot/skills/`
- `.github/skills/`
- `~/.agents/skills/`

The host discovers skills by scanning these directories and parsing each [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) frontmatter.

## Validation Pipeline

After generation, the repository runs **automated compliance checks** via [`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

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

```

## Minimal Compatible SKILL.md Example

```yaml
---
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)) — creates temporary work directory with [`full_text.txt`](https://github.com/virgiliojr94/book-to-skill/blob/main/full_text.txt) and [`metadata.json`](https://github.com/virgiliojr94/book-to-skill/blob/main/metadata.json)
2. **Analysis & generation** — produces `chapters/`, [`glossary.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/glossary.md), [`patterns.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/patterns.md), [`cheatsheet.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/cheatsheet.md)
3. **Master SKILL.md assembly** — injects mandatory frontmatter and ordered sections
4. **Security scan** ([`tools/scan_generated_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/tools/scan_generated_skill.py)) — checks for malicious content
5. **Validation** ([`tools/validate_skill.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```bash

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.