@hegemonart/get-design-done 1.45.0 → 1.46.0

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.45.0"
+    "version": "1.46.0"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.45.0",
+      "version": "1.46.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.46.0] - 2026-06-03
+
+### Phase 46 - Skill UX Polish
+
+70+ skills under one `/gdd:` namespace had three friction points at one surface (skill frontmatter): no
+shortcut for power users, 83 frontmatter blocks as 83 places to edit a description, and a description budget
+that was enforced but not gated explicitly. Phase 46 ships a metadata single source of truth, an
+order-preserving frontmatter generator, three pin shortcut skills, and an explicit budget gate. Planned and
+executed via the GSD pipeline (parallel research + three parallel executor subagents). No new runtime dependency,
+no new egress.
+
+### Breaking changes
+
+- **A new CI drift gate guards skill frontmatter.** `npm run generate:skill-frontmatter:check` fails if any
+  `source/skills/<id>/SKILL.md` frontmatter no longer matches `scripts/lib/manifest/skills.json`. Edit the
+  description, argument hint, or tools allow-list in `skills.json`, then run `npm run generate:skill-frontmatter`
+  and `npm run build:skills` to regenerate. Hand-editing the managed frontmatter keys directly now fails CI.
+- **The skill description budget is now an explicit blocking gate.** `npm run lint:agentskills` runs in CI and
+  fails (R4) on any description over 1024 characters. The cap existed since Phase 28.5; it is now a first-class
+  gate rather than an in-process check.
+
+### Added
+
+- **`scripts/lib/manifest/skills.json` as the skill-metadata single source of truth.** All 86 skills carry
+  `{description, argument_hint?, tools?, user_invocable?, disable_model_invocation?, ...}`; the JSON Schema
+  (`scripts/lib/manifest/schemas/skills.schema.json`) documents the enriched fields and is validated by
+  `npm run validate:manifest`.
+- **`scripts/generate-skill-frontmatter.cjs`** (maintainer-only): forward mode regenerates each skill's
+  frontmatter from `skills.json`; `--extract` reseeds the manifest from current frontmatter; `--check` is the CI
+  drift gate. It is **order-preserving** (each skill keeps its own frontmatter key order; only `name` leads and
+  non-managed lines like `quality-gate`'s `writes:` block are carried verbatim), so the committed tree is a
+  byte-for-byte fixed point and existing frontmatter-snapshot baselines never churn.
+- **`/gdd:pin <skill>`, `/gdd:unpin <skill>`, `/gdd:list-pins`** power-user shortcut skills. `pin` writes
+  standalone alias stubs across every installed harness skills dir (so `/audit` resolves alongside
+  `/gdd:audit`), each carrying a `<!-- gdd-pinned-skill source=<id> -->` marker; descriptions and tools come
+  from the `skills.json` catalogue, never a live frontmatter scrape. `unpin` removes only marked stubs.
+  `list-pins` shows pinned aliases per harness with source and timestamp. Backed by `scripts/lib/pin/`
+  (harness discovery via `scripts/lib/manifest/harnesses.cjs`, atomic `.tmp`+rename writes, cross-platform).
+- **`reference/skill-metadata.md`** documents the SoT, the generator, the build chain, and the budget.
+
+### Notes
+
+- 6-manifest lockstep at **v1.46.0**, `OFF_CADENCE_VERSIONS.add('1.46.0')`, 37 `manifests-version.txt`
+  baselines, tarball golden 874 -> 884 (the 3 pin skills land in `skills/` and `dist/claude-code/`, plus 3
+  `scripts/lib/pin/*.cjs` and `reference/skill-metadata.md`). The maintainer-only generator is correctly not shipped.
+- Description budget (SC#5): already enforced since Phase 28.5 (`validate-skill-length.cjs` + `lint-agentskills-spec.cjs`,
+  both cap at 1024); Phase 46 hardens it into an explicit CI gate and a SoT-layer regression test. No skill needed trimming.
+
+---
+
 ## [1.45.0] - 2026-06-02
 
 ### Phase 45 - Canonical Domain Reference Index

package/README.md

@@ -251,6 +251,8 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Domain reference index (v1.45.0).** The 38+ reference docs are now navigated through 7 canonical entry-points - `reference/{typography,color,spatial,motion,interaction,responsive,ux-writing}.md` - each indexing its subordinate fragments with a "use this when" pointer plus a handful of rules-of-thumb. Design skills load the relevant domain index first and drill into a fragment only when needed (motion-mapper dropped roughly 89% of its up-front reference tokens this way). The indexes link, never copy: `check:domain-links` fails CI on a broken cross-link and `check:no-duplication` fails on large copy-paste. The detailed fragments stay in place as the drill-in targets. **No new runtime dependency.**
 
+**Skill UX polish (v1.46.0).** Skill frontmatter now has a single source of truth at `scripts/lib/manifest/skills.json` (description, argument hint, tools allow-list per skill); `scripts/generate-skill-frontmatter.cjs` regenerates each `source/skills/<id>/SKILL.md` from it, and `generate:skill-frontmatter:check` drift-gates the two in CI. The generator is order-preserving, so the committed tree stays a byte-for-byte fixed point and existing snapshots never churn. Power users get `/gdd:pin <skill>`, which writes standalone shortcut aliases (for example `/audit` alongside `/gdd:audit`) across every installed harness dir, each carrying a `gdd-pinned-skill` marker, plus `/gdd:unpin` and `/gdd:list-pins`. The 1024-character description budget (in place since the skill-authoring contract) is now an explicit `lint:agentskills` CI gate. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -89,6 +89,9 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `analyze-dependencies [--slice <name>]` | `get-design-done:analyze-dependencies` | Query the `.design/intel/` store - dependency slices, graph queries, phase-scoped reads |
 | `extract-learnings [--cycle <slug>]` | `get-design-done:extract-learnings` | Extract decisions, lessons, patterns, and surprises from a completed cycle → `.design/cycles/<slug>/LEARNINGS.md` |
 | `skill-manifest [--refresh]` | `get-design-done:skill-manifest` | List or refresh the local skill manifest used by the router for discovery |
+| `pin <skill>` | `get-design-done:gdd-pin` | Phase 46 - write standalone shortcut aliases for a gdd skill across every installed harness dir (so `/audit` resolves alongside `/gdd:audit`); metadata comes from the skills.json catalogue |
+| `unpin <skill>` | `get-design-done:gdd-unpin` | Phase 46 - remove pinned aliases for a skill (only files carrying the gdd-pinned-skill marker) |
+| `list-pins` | `get-design-done:gdd-list-pins` | Phase 46 - show pinned aliases per harness with their source skill and last-pinned timestamp |
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 - parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 - Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
 | `bandit-status` | `get-design-done:bandit-status` | Phase 27.5 - read-only diagnostic surface for the bandit posterior; per-(agent, bin, delegate, tier) snapshots (alpha, beta, mean, stddev, count, last-used). Use `/gdd:bandit-reset` to mutate. |

package/dist/claude-code/.claude/skills/figma-extract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-figma-extract
-description: Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context.
+description: "Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context."
 ---
 
 # gdd-figma-extract

package/dist/claude-code/.claude/skills/graphify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-graphify
-description: Manage the Graphify knowledge graph for the current project. Build, query, status, diff. When available, design-planner and design-integration-checker use the graph for pre-search consultation.
+description: "Manage the Graphify knowledge graph for the current project. Build, query, status, diff. When available, design-planner and design-integration-checker use the graph for pre-search consultation."
 ---
 
 # gdd-graphify

package/dist/claude-code/.claude/skills/list-pins/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: gdd-list-pins
+description: "Lists pinned skill aliases per harness with their source skill and pin timestamp. Use when you want to see which gdd skills have been pinned as standalone shortcuts and where."
+tools: Read, Bash
+---
+
+# /gdd:list-pins
+
+**Role:** Show every pinned skill alias across the installed harness `skills/` directories. For each one, report the harness it lives in, the on-disk alias directory name, the source skill it points at (from the `<!-- gdd-pinned-skill source=<skill> -->` marker), and when it was pinned (the file modification time).
+
+## Steps
+
+1. **Run the list CLI.** Invoke the shipped script (it takes no arguments). The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" list
+    ```
+
+    The CLI scans each harness `skills/` directory under the current project, finds the stubs carrying the gdd pin marker, and prints one line per pinned alias in the form `[<config-dir>] <alias> -> source=<skill> (pinned <timestamp>)`.
+
+2. **Report the result.** Relay the CLI output verbatim. Exit codes: 0 means one or more pinned aliases were found, 1 means none were found (nothing has been pinned yet), 2 means an error.
+
+## Do Not
+
+- Do not scan the harness directories by hand. The CLI already enforces the marker check, so only genuine gdd pins are listed.
+
+## LIST-PINS COMPLETE

package/dist/claude-code/.claude/skills/pin/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gdd-pin
+description: "Writes standalone shortcut aliases for a gdd skill across installed harness skill dirs. Use when you want a skill directly discoverable as its own command in every installed runtime."
+argument-hint: "<skill-name>"
+tools: Read, Bash
+---
+
+# /gdd:pin
+
+**Role:** Write a standalone shortcut alias (a small SKILL.md stub) for one gdd skill into every installed harness `skills/` directory, so that skill is directly discoverable as its own command in each runtime (Claude Code, Codex, Cursor, Gemini, and the rest).
+
+Each pinned stub starts with the marker line `<!-- gdd-pinned-skill source=<skill> -->`, then carries frontmatter (name, description, argument-hint, tools) pulled from the manifest source of truth, then a one-line body pointing back at the canonical skill. Stubs are written atomically (temp file plus rename), so a failed write never leaves a half-written file.
+
+## Steps
+
+1. **Read the argument.** The skill name to pin comes from `$ARGUMENTS` (for example `darkmode`). If it is empty, ask the user which skill to pin and stop.
+
+2. **Run the pin CLI.** Invoke the shipped script, passing the skill name. The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" pin "<skill-name>"
+    ```
+
+    The CLI detects every harness `skills/` directory that exists under the current project (`.claude/skills`, `.cursor/skills`, and so on) and writes the stub into each. Pass `--user` to also create the harness directories that do not exist yet:
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" pin "<skill-name>" --user
+    ```
+
+3. **Report the result.** The CLI prints one line per harness it wrote to, plus any skips. Relay that summary verbatim. Exit codes: 0 means at least one stub was written, 1 means nothing was written (no harness dirs found, suggest `--user`), 2 means an error (for example an unknown skill name).
+
+## Do Not
+
+- Do not hand-write the stub files. Always go through the CLI so the marker, the manifest-sourced frontmatter, and the atomic write stay consistent.
+- Do not pin a skill that is not in the manifest. The CLI rejects unknown skill names with exit code 2; surface that error rather than inventing a stub.
+
+## PIN COMPLETE

package/dist/claude-code/.claude/skills/unpin/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: gdd-unpin
+description: "Removes pinned skill aliases across harness dirs, deleting only stubs that carry the gdd pin marker. Use when you no longer want a pinned shortcut and want hand-written skills left untouched."
+argument-hint: "<skill-name>"
+tools: Read, Bash
+---
+
+# /gdd:unpin
+
+**Role:** Remove the pinned shortcut aliases for one gdd skill from every installed harness `skills/` directory. Only stubs that carry the marker line `<!-- gdd-pinned-skill source=<skill> -->` as their first non-empty line are deleted, so a hand-authored or unrelated SKILL.md is never touched.
+
+## Steps
+
+1. **Read the argument.** The skill name to unpin comes from `$ARGUMENTS` (for example `darkmode`). If it is empty, ask the user which skill to unpin and stop.
+
+2. **Run the unpin CLI.** Invoke the shipped script, passing the skill name. The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" unpin "<skill-name>"
+    ```
+
+    The CLI scans every harness `skills/` directory under the current project, checks each candidate stub for the gdd pin marker, deletes the ones that carry it, and refuses (skips with a warning) any file that does not.
+
+3. **Report the result.** The CLI prints one line per harness it removed a stub from, plus a warning for any file it refused to delete. Relay that summary verbatim. Exit codes: 0 means at least one stub was removed, 1 means nothing was removed (no matching pinned stubs found), 2 means an error.
+
+## Do Not
+
+- Do not delete skill files by hand. Always go through the CLI so the marker check protects hand-written skills.
+- Do not force-remove a file the CLI refused. A refusal means the file lacks the gdd pin marker and is not a pinned alias; leave it in place.
+
+## UNPIN COMPLETE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -50,6 +50,8 @@
     "build:bundles": "node scripts/build-distribution-bundles.cjs",
     "build:skills": "node scripts/build-skills.cjs",
     "build:skills:check": "node scripts/build-skills.cjs --check",
+    "generate:skill-frontmatter": "node scripts/generate-skill-frontmatter.cjs",
+    "generate:skill-frontmatter:check": "node scripts/generate-skill-frontmatter.cjs --check",
     "build:sdk": "node scripts/build-sdk-bins.cjs",
     "prepack": "npm run build:sdk",
     "postpack": "node scripts/build-sdk-bins.cjs --clean",

package/reference/registry.json

@@ -849,6 +849,13 @@
       "phase": 28.5,
       "description": "Phase 28.5 skill-authoring contract — adapted from mattpocock/skills (MIT). SKILL.md <=100-line cap (warn >=100, block >=250 in CI), 1024-char description cap, <what>. Use when <triggers>. form (lax-mode default per Phase 33 A/B pending), frontmatter required fields, progressive-disclosure one-level-deep rule. Validator at scripts/validate-skill-length.cjs."
     },
+    {
+      "name": "skill-metadata",
+      "path": "reference/skill-metadata.md",
+      "type": "meta-rules",
+      "phase": 46,
+      "description": "Phase 46 skill-metadata single source of truth: scripts/lib/manifest/skills.json record shape, the generate-skill-frontmatter.cjs forward/extract/check modes, the skills.json to generator to build:skills to skills/+dist build chain, the six managed frontmatter keys (canonical order, always-quoted strings) vs extra_frontmatter passthrough, the 20..1024 description budget (validate-skill-length.cjs + lint-agentskills-spec.cjs R4, lint:agentskills CI gate), and the pin metadata catalogue consumer."
+    },
     {
       "name": "capability-gap-stage-gate",
       "path": "reference/capability-gap-stage-gate.md",

package/reference/skill-metadata.md

@@ -0,0 +1,117 @@
+---
+name: skill-metadata
+type: meta-rules
+version: 1.0.0
+phase: 46
+tags: [skill, metadata, frontmatter, single-source-of-truth, generator, description-budget]
+last_updated: 2026-06-02
+---
+
+# Skill Metadata Single Source of Truth
+
+`scripts/lib/manifest/skills.json` is the one place skill frontmatter is authored. A
+generator projects it onto every `source/skills/<id>/SKILL.md`, the build step compiles
+those into the shipped trees, and CI gates keep the three copies identical. This doc
+explains the file, the generator, and the description budget. For the structural rules a
+SKILL.md body must follow (line cap, progressive disclosure, frontmatter required fields),
+see `./skill-authoring-contract.md`.
+
+## What skills.json is
+
+The file is a JSON object: a `schema_version` integer and a `skills` array. Each array
+element is one skill record. Only `name` is required (it must equal the
+`source/skills/<id>/` directory name); every other field is optional and omitted when it
+has no value.
+
+```json
+{
+  "schema_version": 1,
+  "skills": [
+    {
+      "name": "health",
+      "description": "Reports .design/ artifact health - staleness, missing files, token drift, broken state transitions.",
+      "tools": "Read, Bash, Glob, Grep, mcp__gdd_state__get",
+      "disable_model_invocation": true
+    }
+  ]
+}
+```
+
+Recognized record fields: `name`, `description`, `argument_hint`, `tools`,
+`user_invocable`, `disable_model_invocation`, `frontmatter_name` (the `name:` value when it
+is not the default `gdd-<id>`), `extra_frontmatter` (see below), plus `registered_in_phase`
+and `aliases`, which live only in the manifest and never round-trip to frontmatter. The
+schema at `scripts/lib/manifest/schemas/skills.schema.json` validates the shape.
+
+## The build chain
+
+Metadata flows in one direction, and a `*:check` gate guards each hop:
+
+```text
+skills.json
+  -> generate-skill-frontmatter      (npm run generate:skill-frontmatter)
+  -> source/skills/<id>/SKILL.md
+  -> build:skills                     (npm run build:skills)
+  -> skills/  +  dist/claude-code/
+```
+
+`scripts/generate-skill-frontmatter.cjs` rewrites only the frontmatter block of each
+`SKILL.md`, never the markdown body. It has three modes:
+
+- forward (no flag): manifest to frontmatter. The default.
+- `--extract`: the reverse direction, reading current frontmatter back into `skills.json`
+  to seed or refresh the source of truth. Idempotent with forward.
+- `--check`: the CI drift gate. It writes nothing and exits non-zero when any committed
+  frontmatter differs from what the manifest would generate.
+
+`scripts/build-skills.cjs` then propagates `source/skills/` into the committed `skills/`
+tree and `dist/claude-code/`; its own check mode asserts that the built output equals the
+committed output. So the contract is: edit `skills.json`, regenerate, build. Never
+hand-edit a managed frontmatter line in `SKILL.md`, because the drift gate will fail.
+
+## Managed vs preserved fields
+
+The generator owns six frontmatter keys and emits them in this canonical order whenever the
+record carries a value:
+
+1. `name`
+2. `description`
+3. `argument-hint`
+4. `tools`
+5. `user-invocable`
+6. `disable-model-invocation`
+
+String values for `description` and `argument-hint` are always double-quoted on emit, so
+quoting stays uniform across every skill. Anything outside these six keys is not managed.
+The generator carries it verbatim in the record's `extra_frontmatter` array and re-emits it
+after the managed block. The `quality-gate` skill is the working example: its `color`,
+`model`, `default-tier`, `size_budget`, `parallel-safe`, `typical-duration-seconds`,
+`reads-only`, and multi-line `writes:` block all live in `extra_frontmatter` and survive
+every regeneration untouched.
+
+## Description budget
+
+Every `description` must be at least 20 and at most 1024 characters. Two validators enforce
+the ceiling in CI:
+
+- `scripts/validate-skill-length.cjs` treats `DESC_MAX = 1024` as a blocker (it also blocks
+  under 20 characters as under-specification) and is the Phase 28.5 authoring-contract gate.
+- `scripts/lint-agentskills-spec.cjs` rule R4 applies the same 1024-character hard cap from
+  the agentskills.io spec angle, and warns past 200 characters.
+
+Phase 46 keeps that contract intact and wires `npm run lint:agentskills` in as its own
+explicit CI gate, so the spec lint runs on every change rather than only in-process via the
+doctor aggregator.
+
+## How pin consumes it
+
+The `pin`, `unpin`, and `list-pins` skills shipping in this phase read `description`,
+`argument_hint`, and `tools` straight from `skills.json`. That manifest is the pin metadata
+catalogue: the pin surface never live-scrapes a `SKILL.md` or re-derives a description at
+runtime. Reading one structured file keeps pin output consistent with what the generator
+emits, and the `aliases` array is reserved for the pin shortcuts those skills honor.
+
+## See also
+
+- `./skill-authoring-contract.md` for the SKILL.md line cap, description-format guidance,
+  required frontmatter fields, and progressive-disclosure rule.

package/scripts/lib/manifest/schemas/skills.schema.json

@@ -24,7 +24,48 @@
         "properties": {
           "name": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "Skill id = source/skills/<name>/ directory name."
+          },
+          "frontmatter_name": {
+            "type": "string",
+            "description": "Frontmatter name: value when it is not the default gdd-<name>."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 20,
+            "maxLength": 1024,
+            "description": "Skill description (Phase 28.5 budget: 20..1024 chars)."
+          },
+          "argument_hint": {
+            "type": "string"
+          },
+          "tools": {
+            "type": "string",
+            "description": "Comma-separated allow-list emitted as the frontmatter tools: line."
+          },
+          "user_invocable": {
+            "type": "boolean"
+          },
+          "disable_model_invocation": {
+            "type": "boolean"
+          },
+          "registered_in_phase": {
+            "type": "string"
+          },
+          "aliases": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Reserved for pin shortcuts; honored by the pin metadata catalogue."
+          },
+          "extra_frontmatter": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Non-managed frontmatter lines preserved verbatim (color, model, writes:, ...)."
           }
         }
       }