Skip to content

kwakseongjae/oh-my-design / .claude/skills/omd-add-reference

omd:add-reference

Verified

Reference catalog authoring compatibility gate. Core v2 cutover가 끝나기 전에는 신규 legacy DESIGN.md 쓰기를 차단하고 안전한 재개 조건을 설명한다.

Expiry. This gate is a waiting state, not a policy. It lifts when the catalog adoption path lands — the T2-2 writer gate. Status, updated 2026-09-16 (the earlier "today: 없다" note was written 2026-09-02 and went stale):

  • graph-backed Core v2 writer exists — met. --adoption-target reference-catalog shipped with a four-canary isolated adopt → rollback → readopt rehearsal (2026-09-08, .omd/execution/2026-09-08/sprint90/core/).
  • every catalog reader accepts its package — not met. The web readers still parse legacy frontmatter and numbered sections (extract-tokens.ts, generate-css.ts, font-registry.ts, logos.ts).

Scope, narrowed by owner decision 2026-09-16. The second condition governs Core v2 packages, so it cannot govern a write that produces none. Two different operations were being blocked by one rule:

OperationProduces a Core package?Status
Create a new legacy reference, or a new Core catalog packageyes / adds migration debtstill refused
Refresh evidence on an existing reference — verification_v2, .verification.md, tokens.components state values, ## Proofno; the file stays legacy and stays in the same migration queueallowed

An evidence refresh does not create another legacy file — it restores what an earlier pass discarded from a file already queued for migration. It therefore falls outside this gate's stated purpose.

Still refused, with no one-off exception and no plausible fallback: creating a new reference, adding a brand, restoring a legacy YAML marker, emitting 13/15/16-section output, placeholder sentinels, a second authoritative Markdown dialect, or mutating generated counts and mirrors by hand.

omd:add-reference — Core v2 catalog cutover gate

Status: CORE_V2_CATALOG_WRITE_BLOCKED.

The historical reference catalog remains a dual-read migration input. It is not permission to create another legacy file. Do not write or update web/references/<id>/DESIGN.md, frontmatter tokens, generated counts, or mirrors.

On invocation, return the blocker and the proposed reference id/source list without writing. Authoring may resume only after a graph-backed reference metadata/evidence schema, deterministic Core projection, migrated registry and quality readers, legacy dual-read/Core single-write tests, and a dropped-zero migration gate all pass together.

Never restore a legacy YAML marker, 13/15/16-section output, placeholder sentinels, or a second authoritative Markdown dialect as a shortcut.

When Phase 2 comes back, it needs a Step 0

The Tier 1 discovery this skill used to run had three moves — guess <brand>.design, search site:<domain>, search GitHub — and all three are name-guessing or search. None asks whether the host publishes its own documentation index.

That gap has now been measured four times. Toss publishes an llms.txt with 258 links on a developer portal no name-guess reaches, and our reference documented 2 of the 11 components it lists. Pega's design.pega.com was cited correctly from the first pass and its index was never opened: 42 published components, 0 documented. KRDS publishes 55 and we cite 21. Of ten hosts with an official design-system surface, five publish a machine-readable index and none had been read.

The rule and its two traps are written up in docs/SOURCE_INDEX_BLINDNESS_2026-09-17.md (2026-09-19 section). The short version, because it is the part that is easy to get wrong:

  • A file that passes a content check is not necessarily an index. Pega's llms.txt is real, well-formed, text/plain, correctly sized — and Yoast generated it from five SEO pages. It lists zero components out of the 66 its own sitemap publishes.
  • A large index is not a component index. Kakao's sitemap is real and has 316 URLs, all of them API documentation.

Fold Step 0 in before restoring the three name-guessing moves, not after.

Write path: DESIGN.md v3 (2026-10-14)

The catalog is DESIGN.md v3 (spec/design-md-v3.md): every web/references/<id>/ holds a Google-frontmatter DESIGN.md and a reference.json sidecar. Any write this gate permits (an evidence refresh on an existing reference) goes through one path: read readReferenceSource(dir).markdown (the legacy-shaped source), edit it, and write it with scripts/design-md-v3/writer.mjs writeReference(dir, text), which converts, checks spec §10 conformance with 0 Google lint errors, and writes the file, the sidecar and the design-md/ mirror. web/scripts/assemble-reference.mjs emits v3 the same way. The OmD 0.1 text-patching tools (apply-state-values, apply-measured-palette, apply-primary-tasks, migrate-frontmatters, retire-template-motion) refuse v3 files until they are ported. Creating a new reference stays refused until the owner lifts this gate.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall