fix(skill): repair the agent-facing structure of SKILL.md, add a doc gate + CI

[aievolutionpl]

A structure pass over the skill wrapper. The doctrine is untouched — visual-advertising-engine.md, design-rules.md, core.md and every references/ file are byte-identical. What changed is how an agent finds its way through them.

Fixed

• SKILL.md pointed at three sections that don't exist. design-rules.md §10.5 (two production modes) and §12 (the QA rule list) — that file stops at §9 — and the slop check was cited as §9, which is the platform-dimensions table. The mandatory QA step in the workflow sent the agent to nothing. Now §4, §8 and §6, each quoted by title so a renumber is visible instead of silent.
• The QA step ran python scripts/qa.py. Installed to ~/.claude/skills/meta-ads-designer, that resolves against the user's project, where it doesn't exist. The step now resolves the skill's own directory and names the dependency install.
• visual-advertising-engine.md §25 is a rule ID, cited as R25 now, like everywhere else.

Changed

• SKILL.md no longer front-loads the doctrine. "Load first (in order)" asked for the engine + charter + chat inject — ~730 lines — before the brief was even taken. Replaced with a load-when table: this file runs the brief end to end, everything else opens at the step that needs it.
• core.md is off the agent's path, marked as what it is: the paste-in for chat hosts with no skill loader.
• The table routes to all seven references. layout-system.md, headline-system.md, qa-gate.md, anti-slop-registry.md and niche-playbooks.md previously appeared only in the repo-structure tree, with no cue for when to open them.
• Frontmatter is a valid Agent Skills header. version, author and url are not spec keys and a strict loader rejects them — moved under metadata. The description now leads with what the skill does and states its trigger.
• The 17 quick rules carry their canonical IDs (R02, R03, …), so the summary and the standard can be diffed rather than trusted.

Added

• scripts/check_docs.py — dead relative links, §-pointers to missing sections, cited rule IDs no rule defines, invalid SKILL.md frontmatter, and version drift between the frontmatter, the README badges and the changelog. Run against main it reports 8 problems, including every pointer fixed here.
• .github/workflows/ci.yml — check_docs.py + test_qa.py on every push and PR. test_qa.py has shipped since 5.4.0 with nothing running it.
• requirements.txt (pillow, numpy) and .claude-plugin/plugin.json, so the skill installs through a marketplace and not only by cp -r.

Version bumped to 5.5.0 across frontmatter, both README badges and CHANGELOG.md.

Verification

$ python scripts/check_docs.py
PASS — 22 markdown files: links, §-pointers, rule IDs, frontmatter, version

$ python scripts/test_qa.py
13/13 cases passed

$ python scripts/check_docs.py --root <main @ 6228316>
FAIL — 8 problem(s)

Not in this PR

The doctrine still lives in four places — R01–R34 in the engine, the prose summary in design-rules.md, the full inject in core.md, and the 17 quick rules in SKILL.md — which is what CONTRIBUTING.md's "one fact, one home" exists to prevent, and what the 5.4.0 changelog is largely a record of (16:9 dimensions, headline budgets, the version itself). The R-IDs added here make the drift detectable; collapsing it is a separate, larger editorial call, since core.md is what people paste into ChatGPT.

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.