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 쓰기를 차단하고 안전한 재개 조건을 설명한다.

FileKindSize
SKILL.mdskill md5.0 KB
batch-instructions.mdmarkdown453 B
---
name: omd:add-reference
description: "Reference catalog authoring compatibility gate. Core v2 cutover가 끝나기 전에는 신규 legacy DESIGN.md 쓰기를 차단하고 안전한 재개 조건을 설명한다."
argument-hint: "<url|id>"
user-invocable: true
---

**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:

| Operation | Produces a Core package? | Status |
|---|---|---|
| Create a **new** legacy reference, or a new Core catalog package | yes / adds migration debt | **still refused** |
| Refresh **evidence on an existing** reference — `verification_v2`, `.verification.md`, `tokens.components` state values, `## Proof` | no; the file stays legacy and stays in the same migration queue | **allowed** |

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: 323kUpdated 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