write-a-skill

name	write-a-skill
version	1.0
last_updated	2026-08-06T00:00:00.000Z
id	write-a-skill
one_line_purpose	Author a new skill directory that satisfies this repository's front-matter contract.
entry_point	docs/skills/write-a-skill/SKILL.md
category	meta
mcp_compliance_level	partial
optimization_status	draft
status	active
dependencies	["skill-improvement"]
tags	["skills","authoring","documentation","front-matter","validation"]
description	Defines the required SKILL.md front-matter keys, size budget, index entry, and validation command for a new skill in this repository. Use when adding a new docs/skills directory or repairing front matter that fails validation.
metadata	{"type":"procedure","source-of-truth":[".github/scripts/validate-docs.py","docs/skills/index.md","AGENTS.md"]}

Write a skill

Use when

• Adding a new docs/skills/<name>/SKILL.md.
• Repairing front matter that validate-docs.py rejects.

Do not use when

• Updating an existing skill's body: use skill-improvement.

Required front matter

Every docs/skills/<name>/SKILL.md starts with exactly these keys:

---
name: <kebab-case-name>          # must equal the directory name
version: "1.0"                   # quoted semver string
last_updated: YYYY-MM-DD
id: <kebab-case-name>            # must equal name and the directory name
one_line_purpose: <=120 chars, imperative, no "Use when" clause
entry_point: docs/skills/<name>/SKILL.md
category: ci-ops | test-authoring | meta
mcp_compliance_level: partial
optimization_status: draft
status: active | deprecated | reserved
dependencies: []                 # ids of skills that must load first
tags: [tag1, , ]