Authoring Guidelines for AI Agents

Skill files are read by AI, not humans

Skill files (SKILL.md, references/, etc.) are loaded as context for AI agents. Follow these rules when editing them, per the Agent Skills specification:

• Use Markdown links for every file and doc reference — write See [the reference guide](references/REFERENCE.md), not a bare path or URL. This is the syntax in the spec's File references example; standardize on it repo-wide for consistency. Keep the target a relative path from the skill root, one level deep (e.g. references/EXAMPLES.md), and avoid deeply nested reference chains. (Runnable commands and code stay literal — scripts/extract.py in a run instruction, go get …, code blocks — they are commands, not links.)
• Additional documentation goes in references/ — supplementary docs (e.g., ax-profiles.md, ax-setup.md, EXAMPLES.md) belong in the references/ subdirectory, per the Agent Skills specification.
• Keep SKILL.md focused — the full body loads on activation; the spec recommends staying under ~5000 tokens / 500 lines and moving detail into references/.

Quality checks

CI (.github/workflows/quality-checks.yml) runs these on every PR. Run the no-Node subset locally with bash scripts/check.sh before pushing:

• scripts/validate_skills.py — per-skill structure: frontmatter, name (kebab-case, 3–64 chars, matches the folder, unique), description length, declared assets exist and are ≤5 MB, Markdown links with relative targets resolve, SKILL.md ≤500 lines, and a warning for bare doc paths that should be Markdown links (the rule above).
• scripts/validate_manifests.py — version.txt matches every plugin manifest (release-please keeps them in sync; this proves they never drift) and metadata (name, description, keywords, license, repository) is consistent and within limits.
• codespell (.codespellrc) and line endings (scripts/check_line_endings.sh) — spelling and LF hygiene.
• Vally lint (eng/vally-lint.mjs) — @microsoft/vally's static skill lint (spec-compliance + valid references). Needs Node: npm install --no-save @microsoft/vally@0.10.0 && node eng/vally-lint.mjs.
• Plugin install smoke test — claude plugin validate . plus a marketplace add/install of the plugin.