docs(skills): adopt the factory skill front-matter contract

[castrojo]

Brings this repository's skill docs up to projectbluefin/common's front-matter contract and enforces it locally.

What changed

• Every docs/skills/*/SKILL.md now carries the full 14-key front matter (name, version, last_updated, id, one_line_purpose, entry_point, category, mcp_compliance_level, optimization_status, status, dependencies, tags, description, metadata.type). Existing metadata.source-of-truth blocks are preserved verbatim.
• .github/scripts/validate-docs.py enforces the contract: required keys, id/entry_point agreement with the directory, category/status/metadata.type enums, and the 256/120 char caps. The parser is a dependency-free YAML subset reader (folded >- aware), so the validate job needs no extra packages.
• Fixed a latent bug: the Markdown link check excluded .worktrees by matching absolute path parts, so it skipped every file when the repo was checked out under .worktrees/. Now 0 Markdown files → 39 Markdown files.
• New docs/skills/write-a-skill/SKILL.md documenting the authoring contract and this repo's deliberate variances from common: per-skill directories only, hard 180-line cap per SKILL.md, hand-curated index (no generated index.json / index.schema.json / generate_skill_index.py).

Enforcement proof

Each violation was introduced temporarily and reverted; the validator failed with exit 1 in every case:

Injected defect	Result
category: bogus	invalid category 'bogus'
id: bulid	id does not match directory
entry_point: docs/skills/build.md	entry_point must be docs/skills/build/SKILL.md
status: retired	invalid status 'retired'
metadata.type: essay	invalid metadata.type 'essay'
removed version: / tags:	missing version metadata / missing tags metadata
130-char one_line_purpose	one_line_purpose exceeds 120 characters
380-char folded description	description exceeds 256 characters
name: builds	name does not match directory (exit 1)

Validation

just check, python3 .github/scripts/validate-docs.py (13 skills, 39 Markdown files), pre-commit run --all-files, bats tests/unit/ (148 tests) all pass. Line budgets: AGENTS.md 128/150, docs/skills/index.md 27/80, largest SKILL.md 118/180.