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

.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "meta-ads-designer",
+  "description": "Design and generate posters, flyers, Meta/social ads and promo graphics that look art-directed instead of AI-generated.",
+  "version": "5.5.0",
+  "author": { "name": "AI Evolution Labs", "url": "https://github.com/aievolutionpl" },
+  "homepage": "https://github.com/aievolutionpl/meta-ads-designer",
+  "license": "MIT",
+  "keywords": ["design", "advertising", "meta-ads", "image-generation", "marketing"]
+}

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Docs — links, section pointers, rule IDs, frontmatter, version
+        run: python scripts/check_docs.py
+      - name: QA gate self-test
+        run: python scripts/test_qa.py

CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to Meta Ads Designer. Versions follow [SemVer](https://semve
 
 ---
 
+## [5.5.0] — 2026-08-19
+
+A structure pass over the skill itself. The rules were fine; the wrapper around them sent the agent to sections that don't exist, to a script path that doesn't resolve, and through ~730 lines of doctrine before it had heard the brief.
+
+### Fixed
+- **`SKILL.md` pointed at three sections that were never there.** `design-rules.md §10.5` (two production modes) and `§12` (the QA rule list) do not exist — that file stops at §9 — and the slop check was cited as `§9`, which is the platform-dimensions table. An agent following step 3.6 or the mandatory QA step in 5 found nothing. They now resolve to §4, §8 and §6, each quoted by title so a renumber is visible rather than silent.
+- **The QA step told the agent to run `python scripts/qa.py`.** Installed to `~/.claude/skills/meta-ads-designer`, that path resolves against the user's project, where it does not exist. The step now resolves the skill's own directory first and names the dependency install.
+- **`visual-advertising-engine.md §25` is a rule ID, not a section number** — cited as `R25` now, like everywhere else.
+
+### Changed
+- **`SKILL.md` no longer front-loads the doctrine.** "Load first (in order)" asked for the engine, the charter and the inject — about 730 lines — before the brief was even taken. It is now a load-when table: this file runs the brief, everything else opens at the step that needs it. `core.md` is marked as what it is, the paste-in for chat hosts with no skill loader, and taken off the agent's path.
+- **The load 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 inside 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; they moved under `metadata`. The description now leads with what the skill does and states its trigger, instead of opening on "Universal plugin that teaches agents…".
+- **The 17 quick rules carry their canonical IDs** (`R02`, `R03`, …). The summary and the standard can now be diffed instead of trusted.
+
+### Added
+- **`scripts/check_docs.py`** — dead relative links, `§`-pointers to sections that don't exist, rule IDs no rule defines, an invalid `SKILL.md` frontmatter, and version drift between the frontmatter, the README badges and this file. Run against the previous commit it reports 8 problems, including every pointer fixed above.
+- **`.github/workflows/ci.yml`** — `check_docs.py` and `test_qa.py` on every push and PR. `test_qa.py` has been in the repo since 5.4.0 with nothing running it.
+- **`requirements.txt`** — `pillow`, `numpy`. `INSTALL.md` asked for a bare `pip install pillow numpy` with no pinned floor.
+- **`.claude-plugin/plugin.json`** — installable through a Claude Code marketplace, not only by `cp -r`.
+
+---
+
 ## [5.4.0] — 2026-08-19
 
 An audit pass over the whole skill. The gate was making ship/no-ship calls it could not actually support, and the docs had drifted from the code and from each other.

CONTRIBUTING.md

@@ -28,8 +28,9 @@ A rule is useful if it would **prevent a real rejection**. Anchor it in a concre
 2. Edit the canonical file (`visual-advertising-engine.md`). Give a new rule the next free ID; never renumber an existing one — deprecate it and add a new ID.
 3. Update the summary in `core.md` / `design-rules.md` only if the rule is headline-grade.
 4. Keep README (PL + EN) in sync if it lists rules.
-5. If you touched `scripts/`, run `python scripts/test_qa.py` and add a case for the behaviour you changed.
-6. Open a PR with a one-line "why": the real rejection this rule would have caught.
+5. Run `python scripts/check_docs.py` — it fails on dead links, `§`-pointers to sections that don't exist, cited rule IDs the engine never defines, an invalid `SKILL.md` frontmatter, and a version that drifted between the frontmatter, the README badges and this changelog.
+6. If you touched `scripts/`, run `python scripts/test_qa.py` and add a case for the behaviour you changed.
+7. Open a PR with a one-line "why": the real rejection this rule would have caught.
 
 ## Style
 - **English is canonical for the rules.** `visual-advertising-engine.md`, `design-rules.md`, `core.md` and `references/` are English; `README.md` is the Polish manual and `README.en.md` the English one. There is no EN mirror of the engine — the duplicate was removed in 5.0.0 because the two copies had drifted.

INSTALL.md

@@ -71,13 +71,16 @@ Inject **`core.md`** into your system prompt (fully self-contained), or load `SK
 The QA gate's deterministic layer and the wordmark extractor need two common packages:
 
 ```bash
-pip install pillow numpy
+pip install -r requirements.txt
 
 python scripts/qa.py out/*.png --format 4:5 --text-box 86,900,994,1264
 python scripts/extract_wordmark.py refs/logo.png build/logo_white.png
 python scripts/test_qa.py        # verifies the gate itself, 13 synthetic cases
+python scripts/check_docs.py     # verifies the docs: links, section pointers, rule IDs, versions
 ```
 
+Run these from the skill's own directory (`~/.claude/skills/meta-ads-designer`, or wherever you cloned it) — the paths above are relative to it, not to the project you are designing for.
+
 Always pass `--text-box` on a creative that carries copy (and `--logo-box` when you place a logo). Without them the safe-area, contrast, thumbnail and scrim checks have nothing to measure, report `n/a`, and the PASS is only partial — the script warns you when this happens.
 
 `qa.py` exits non-zero when any image fails, so it drops into CI or a pre-delivery hook. Everything else in the repo is plain Markdown with no dependencies.
@@ -108,5 +111,5 @@ Ask the agent: *"What is the specificity test, and what's the default margin on
 | `references/niche-playbooks.md` | 15 per-industry playbooks (What works / Avoid / Headline / CTA) |
 | `references/prompt-library.md` | Prompt skeletons |
 | `references/anti-slop-registry.md` | Full banned-pattern list + grep gate |
-| `scripts/` | `qa.py` (QA gate), `test_qa.py` (its self-test), `extract_wordmark.py` |
+| `scripts/` | `qa.py` (QA gate), `test_qa.py` (its self-test), `check_docs.py` (doc integrity), `extract_wordmark.py` |
 | `CONTRIBUTING.md` | How to add a rule without forking the doctrine |

README.en.md

@@ -8,7 +8,7 @@
 
 [🇵🇱 Polski](README.md) · [🇬🇧 English](README.en.md)
 
-![Version](https://img.shields.io/badge/version-5.4.0-6a5acd)
+![Version](https://img.shields.io/badge/version-5.5.0-6a5acd)
 ![License](https://img.shields.io/badge/license-MIT-brightgreen)
 ![Format](https://img.shields.io/badge/default_format-4:5%20(1080×1350)-informational)
 ![Hosts](https://img.shields.io/badge/runs_on-ChatGPT%20%7C%20Codex%20%7C%20Hermes%20%7C%20Claude%20%7C%20Cursor-blue)
@@ -206,9 +206,13 @@ meta-ads-designer/
 ├── README.en.md                    # This manual (EN, extra)
 ├── CHANGELOG.md                    # Version history
 ├── LICENSE                         # MIT
+├── CONTRIBUTING.md                 # How to add a rule (rule-ID policy, no-duplication rule)
+├── requirements.txt                # pillow + numpy — dependencies for scripts/
+├── .claude-plugin/plugin.json      # Plugin manifest (install via a Claude Code marketplace)
+├── .github/workflows/ci.yml        # CI: check_docs.py + test_qa.py on every push
 ├── assets/meta-ads-designer-banner.png
 ├── examples/                       # Worked ad examples (anti, restaurant, hotel, services, retail)
-├── scripts/                        # qa.py, test_qa.py, extract_wordmark.py
+├── scripts/                        # qa.py, test_qa.py, check_docs.py, extract_wordmark.py
 └── references/
     ├── hospitality-food-services-playbook.md  # Depth: food / hotel / services
     ├── layout-system.md            # Layout + panel heights + gradient values

README.md

@@ -8,7 +8,7 @@
 
 [🇬🇧 English](README.en.md) · [🇵🇱 Polski](README.md)
 
-![Version](https://img.shields.io/badge/version-5.4.0-6a5acd)
+![Version](https://img.shields.io/badge/version-5.5.0-6a5acd)
 ![License](https://img.shields.io/badge/license-MIT-brightgreen)
 ![Format](https://img.shields.io/badge/default_format-4:5%20(1080×1350)-informational)
 ![Hosts](https://img.shields.io/badge/runs_on-ChatGPT%20%7C%20Codex%20%7C%20Hermes%20%7C%20Claude%20%7C%20Cursor-blue)
@@ -206,9 +206,13 @@ meta-ads-designer/
 ├── README.en.md                    # Ten manual (EN, extra)
 ├── CHANGELOG.md                    # Historia wersji
 ├── LICENSE                         # MIT
+├── CONTRIBUTING.md                 # Jak dodać zasadę (polityka ID, zasada braku duplikacji)
+├── requirements.txt                # pillow + numpy — zależności scripts/
+├── .claude-plugin/plugin.json      # Manifest pluginu (instalacja przez marketplace Claude Code)
+├── .github/workflows/ci.yml        # CI: check_docs.py + test_qa.py przy każdym pushu
 ├── assets/meta-ads-designer-banner.png
 ├── examples/                       # Gotowe przykłady adów (anti, restauracja, hotel, serwisy, retail)
-├── scripts/                        # qa.py, test_qa.py, extract_wordmark.py
+├── scripts/                        # qa.py, test_qa.py, check_docs.py, extract_wordmark.py
 └── references/
     ├── hospitality-food-services-playbook.md  # Głębia: food / hotel / serwisy
     ├── layout-system.md            # Layout + panel-heights + gradient values