Skill Markdown Schema & Directory Bundle
A Skill is an on-demand procedural workflow that packages multi-file procedures, normative contracts, templates, and executable validation scripts.
Unlike instructions or agents, a skill is always a directory bundle, never a standalone file.
Directory Structure
text
skills/<skill-name>/
├── SKILL.md # Entry point and procedural workflow (Required)
├── references/ # Normative specifications, contracts, and architecture guides
├── scripts/ # Executable validation, generation, or linting scripts
├── fixtures/ # Test inputs and expected outputs proving script correctness
└── templates/ # Copy-and-customize scaffolds (when not generated by scripts)Examples in Coding Pal:
skills/scope-guard/(Guard & churn limiter)skills/dependency-guard/(Guard & dependency sentinel)skills/secret-guard/(Guard & credential sentinel)skills/task-gate/(Gate & verification runner)skills/contract-validator/(Declarative schema contract)skills/test-probe/(Behavioral anti-tautology probe)skills/rollback-probe/(Migration roundtrip probe)skills/audit-reporting/(Finding protocol & validator)skills/think-plan/(Specification protocol & validator)skills/vitepress-docs-examples/(Scaffolding bundle)skills/node-express-examples/(Scaffolding bundle)
SKILL.md Frontmatter Schema
Every SKILL.md file must begin with a YAML frontmatter block enclosed by triple dashes (---).
yaml
---
name: string
description: string
license: string
---Fields
| Field | Type | Required | Description | Constraints & Best Practices |
|---|---|---|---|---|
name | string | Yes | Lowercase kebab-case identifier. | Must match the directory name (e.g., audit-reporting, vitepress-docs-examples). |
description | string | Yes | Semantic discovery description. | Crucial for activation. AI harnesses match user prompts against this field. Include specific trigger phrases and nouns. |
license | string | Yes | License identifier. | Set to MIT. |
Example Frontmatter
yaml
---
name: vitepress-docs-examples
description: 'Scaffold or match a VitePress product docs site (package.json, config.mjs, home/guide pages, mermaid, dev dockerfile, Pages workflow). Use when adding or updating documentation under a user-supplied docs root.'
license: MIT
---SKILL.md Document Body Schema
markdown
# <Skill Title>
<Summary statement defining scope and relationship to paired domain instructions.>
## When to Use This Skill
- <Trigger scenario 1>
- <Trigger scenario 2>
## Path resolution
Resolve `references/` relative to **this skill's install directory** (the folder that contains this `SKILL.md`).
Substitute `<variable>` wherever parameter placeholders appear.
## Workflow
1. <Step 1: Consult contract or instructions>
2. <Step 2: Scaffolding / Code Generation>
3. <Step 3: Deterministic Validation Script>
## Done When
- <Falsifiable Criterion 1>
- <Falsifiable Criterion 2>Directory Roles & Guidelines
| Subdirectory | Role | Authoring Guideline |
|---|---|---|
references/ | Human-readable normative specifications | Authoritative source of truth for schemas, tables, and contracts. Agents consult this file on-demand. |
scripts/ | Deterministic machine verification | Node.js or Python scripts that validate, normalize, or generate output. Prevents reliance on LLM self-checking alone. |
fixtures/ | Script test cases | Contains valid and invalid sample files to prove that scripts in scripts/ accurately pass or reject artifacts. |
templates/ | Copyable starter code | Only include starter files if consumers need to copy and customize them manually. Prefer script-driven generation when possible. |
Annotated Reference Example
markdown
---
name: vitepress-docs-examples
description: 'Scaffold or match a VitePress product docs site (package.json, config.mjs, home/guide pages, mermaid, dev dockerfile, Pages workflow). Use when adding or updating documentation under a user-supplied docs root.'
license: MIT
---
# VitePress Docs Examples
On-demand templates for the VitePress docs instruction. Normative rules stay in the installed `vitepress-docs` instruction; this skill owns scaffolding templates only.
## When to Use This Skill
- Creating a docs site from scratch.
- Adding a guide page, sidebar group, Compose docs service, or GitHub Pages workflow in that pattern.
## Path resolution
Resolve `references/` relative to **this skill's install directory** (the folder that contains this `SKILL.md`).
Templates write `<docs-root>` wherever the site root appears. Substitute the resolved root before copying.
## Workflow
1. Follow the installed VitePress docs instruction for layout, stack, and sidebar rules.
2. **Read `references/examples.md` now** before scaffolding.
3. Copy templates into the docs root.
## Done When
- Copied files match these templates, with `<docs-root>` substituted everywhere.