v2.8.0 — the skill folder becomes a real skill

Superseded by v2.8.1. This release moved templates/ into the skill folder but left mcp-server/server.py reading the old path, so the gds://templates/frontend-tz and gds://templates/component-spec resources return a missing file. Take 2.8.1 instead.

The skill folder becomes a real skill

An audit of the installed copy against the repo found the two had diverged in both directions. ~/.claude/skills/global-design/SKILL.md was running a v2.1.4 body — no e-commerce row, no one-shot build, no rendered-verification step, Next.js 15 in the stack table — while carrying a hand-written resource index the repo never had. Three months of routing work shipped to the repo and never reached the thing that actually loads.

Pulling that thread found the cause underneath it: skills/global-design/ was never a self-contained skill. SKILL.md named 46 files that lived at the repo root and only arrived beside it at install time. This release closes that boundary, turns the reference graph back into a tree, and gives the skill two things it can run instead of describe.

	before	after
Broken references in the skill folder	46	0
Reference cycles	57	0
Depth violations	37	0
Executed evals	none	14 of 14 pass
Overall audit score	49	95
Release gate	15 of 19	19 of 19

---

Restructured

• references/, agents/, templates/ and evals/ moved into skills/global-design/. They now sit where Anthropic's layout puts them. The installer bundles nine repo-root directories instead of twelve, and copies agents into .claude/agents/ from the new path. Post-install the tree is identical to before, because everything still flattens into the skill folder.
• The resource index lives in SKILL.md. All 28 reference catalogs, 11 agents and 7 templates are direct links from the entry point, plus a directory map for the nine bundled dirs. Anthropic's guidance is one hop; a separate resource-index.md made it two, so that file is gone. The four sibling files — task-routing.md, quality-gates.md, operating-principles.md, output-formats.md — are linked for the first time. Until now nothing in SKILL.md pointed at them, so roughly 35KB of routing detail and gate criteria never loaded.
• The reference graph is a tree again. Catalogs linked up to the agents that read them, sibling catalogs linked both ways, and 103 files named themselves in their own version footer. Upward links to agents/* are dropped from eight data files, one direction is removed from twelve mutually-linked pairs, and the self-naming footers are gone. Nothing became unreachable: SKILL.md links every one of these files directly.
• Path convention stated. Every path resolves from the skill root, not from the file that mentions it. The convention was already universal in the library and nowhere written down.

Added

• scripts/verify-rendered.mjs — Decision Pipeline step 12 stops being prose. Step 12 demanded rendered proof and shipped no way to produce it; every mechanical check lived as a paste-into-DevTools snippet. The runner loads a URL in Playwright, light and dark, at 390px and 1280px, and reports horizontal overflow (Gate 5), text hidden by -webkit-text-fill-color (Gate 6), sub-44px touch targets (Gate 5), images without width/height (Gate 7), vh where dvh belongs (Gate 5), and hex/rgb/hsl where OKLCH belongs (Gate 3). Exits 1 on a hard failure, so it can gate a deploy; --json for machine use.

  node scripts/verify-rendered.mjs https://example.com

• evals/fixtures/ — a self-test for that runner. rendered-defects.html plants one instance of each check; rendered-clean.html plants none. Defects → 8 failures, 12 warnings, exit 1. Clean → 0 / 0, exit 0.

• evals/agent-cases/ — 14 behavioural evals that get executed, not described. Six categories: discovery, functional, edge-cases, negative, regression, adversarial. Graded on what the answer contains and avoids rather than on prose quality. The regression case pins the stack majors so a stale Next.js 15 cannot come back unnoticed; the adversarial case checks that a fake countdown and a fake stock counter get refused, not built. The one-shot build case needs a long leash — it produced a seven-page site and timed out twice before finishing inside fifty minutes.

  python run_evals.py run skills/global-design/evals/agent-cases \
    --runner "claude -p -" --stdin-query --results results.jsonl

• Nine more trigger evals (15 → 24). Five positives for capabilities added since v2.5.0 that had no coverage: one-shot build, e-commerce, rendered verification, reference extraction, GSAP scroll-pinning. Four hard negatives drawn from the scope boundaries: native mobile UI, HTML email, logo and brand identity, print. The three existing negatives — SQL, Redis, CSV parsing — sit nowhere near the decision boundary and prove nothing.

• An install-drift check. gds doctor gained a tenth item that byte-compares the six copied files against the source and names the ones that diverged. The resource dirs were already junctions and stayed current; only these six could drift silently. Run doctor after every pull.

• Tables of contents in 38 files. Every file over 100 lines in rules/, blueprints/, checklists/ and references/tech-standards.md now opens with a ## Contents list, matching the pass already done across references/. Past 100 lines a partial read hides the file's scope. Insertions only.

Fixed

• Stack re-verified against Tier-1 sources on 2026-09-08. Next.js 16.3.4 stable with Turbopack, the proxy file convention and Cache Components; React 19.2.7; Tailwind 4.3; GSAP's full plugin set free; WCAG 2.2 still the current W3C Recommendation. The runtime copy had been saying Next.js 15.
• Every time-sensitive statement ruled on. All 80 findings from the staleness scan carry a claim and a verdict: 75 dismissed with a written reason per class — WCAG success-criterion identifiers such as 1.4.3 label clauses in a published Recommendation, per-file edit stamps are not release surfaces, Baseline years are facts about the past — and 5 real framework versions verified against the source fetched that day. 91 claims, 0 unresolved.
• Frontmatter name aligned to the directory, as the spec requires. The package name in manifest.yaml stays global-design-skill.
• Description rewritten. Keeps every trigger phrase, drops the internal mechanics, and states the scope boundaries — native mobile UI, email templates, print, brand identity — so the negative cases have something to match. 852 of the 1024 allowed characters.
• Two genuinely broken links. scripts/tokens-to-css.js in the Figma integration docs is a script the reader's project owns, not one this package ships. The rendered-verification runner ships inside the skill folder instead of being named from a path that is not bundled.
• gds install no longer copies dot-directories out of skills/global-design/. Local working state was being copied into installs, which could plant a second SKILL.md inside the installed skill folder.
• Portability. A machine-specific /var/www/... path in a live-audit snippet became a placeholder, and three grep examples moved from the GNU-only \s to the POSIX [[:space:]].

---

Upgrading

Re-run the installer — the layout changed, and an install made before this release still has references/, agents/ and templates/ copied from the old locations:

git pull
python scripts/gds install --tool=claude-code /path/to/your-project
python scripts/gds doctor /path/to/your-project

doctor should report ten passes. The drift check is the new one; if it names a file, re-run the install.

Full detail: CHANGELOG.md.