Repository navigation
Metadata Markup Conventions
This guide defines recommended metadata and markdown structure conventions for skills and documentation in this repository.
Two rules come first, because the Agent Skills specification and this repository's validator enforce them:
-
metadatais a map of string keys to string values. Lists must be written as one comma-separated string, not as YAML arrays. - Every skill needs the
metadatakeystier,domain,outputandeffort;scripts/validate-skills.mjsfails a skill without them. The other keys below are optional conventions that no tool reads yet.
These conventions improve:
- Tool-driven routing and filtering
- Release and audit reproducibility
- Contract validation across orchestrators and specialists
- Long-term consistency across Copilot, Claude Code, and Gemini surfaces
Use metadata for machine-readable properties that should remain stable across wording changes.
Example:
---
name: accessibility-lead
description: Accessibility team lead and orchestrator
metadata:
tier: router
domain: web
output: findings
effort: medium
owner: web-a11y
maturity: stable
release-phase: ga
capability-tags: "wcag-2.2, aria, keyboard, forms"
dispatch-contract: required
---Recommended fields:
| Field | Type | Purpose |
|---|---|---|
owner |
string | Team or maintainer group |
domain |
string |
web, document, github, developer, cross-cutting
|
maturity |
string |
stable, beta, experimental
|
release-phase |
string |
ga, preview, internal
|
capability-tags |
string (comma-separated) | Discovery and filtering tags |
dispatch-contract |
string |
required for orchestrators that must follow specialist dispatch |
Example:
---
name: kb-web-severity-scoring
description: Compute web accessibility scores and grades
metadata:
tier: reference
domain: web
output: guidance
effort: low
spec-version: "2026-05"
model-compatibility: "copilot, claude, gemini"
compliance-profiles: "wcag-2.2-aa, en-301-549"
---Recommended fields:
| Field | Type | Purpose |
|---|---|---|
spec-version |
string | Internal schema/contract version |
model-compatibility |
string (comma-separated) | Supported model hosts |
compliance-profiles |
string (comma-separated) | Regulatory or standards mapping |
Use predictable heading and checklist structure so scanners and maintainers can parse files consistently.
Required section headings for larger instruction files:
## Decision Matrix## Non-Negotiable Standards## Acceptance Criteria
Markdown structure rules:
- One H1 per file
- Explicit language tags on all fenced code blocks
- Lists surrounded by blank lines
- Avoid ambiguous links in policy docs
When writing release notes, include an explicit metadata block to support reproducibility, for example:
metadata:
release: "7.1.0"
generated-at: "2026-10-28T00:00:00Z"Audit reports need no hand-written block: render-report.mjs writes a Metadata
section (date, scope, skills run, tooling versions, scan configuration, checks
counted) and embeds the merged findings. There is one scoring model, the one in
skills/a11y-core/scripts/merge-findings.mjs; it has no profiles or
calibration versions to record.
Conventions are designed to be compatible with existing validation tooling:
-
npm run verify:specchecks thatmetadatais a string map, as the Agent Skills specification requires -
npm run verify:skills(scripts/validate-skills.mjs) checkstier,domain,outputandeffort, and the pointer-dispatch contract of every router -
node scripts/build-dispatch-matrices.mjs --checkchecks that every router's dispatch matrix matches the skills that exist - All three run in CI through
.github/workflows/verify.yml
- Add metadata to orchestrators first (
dispatch-contract: required). - Add metadata to high-traffic skills (scoring, scanning, compliance).
- Expand metadata coverage incrementally during normal edits to avoid large refactor risk.
- Keep metadata values stable and update only on semantic changes.
- Agents Overview
- Accessibility Lead
- Web Accessibility Wizard
- Document Accessibility Wizard
- Markdown Assistant
- Developer Hub
- GitHub Hub