create-yss-spec 2.1.10 → 2.1.13

package/template/.cursor/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,22 @@
+# Skill mechanics
+
+The skill-specific branch of [`writing-for-agents`](SKILL.md): what changes when the document is a skill — frontmatter, the invocation choice, and router skills. Everything else about writing it is the universal reference in `SKILL.md`.
+
+## Invocation
+
+Two choices, trading the two loads:
+
+- A **model-invoked** skill keeps a `description`, so the agent can fire it autonomously — and other skills can reach it. You can still type its name: model-invocation always _includes_ user reach; a description only ever adds agent discovery, never removes the human's. The description is the skill's top-level context pointer, forced to stay loaded at all times — permanent context load in exchange for discoverability. A model-invoked skill whose content is all reference is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Mechanics: omit `disable-model-invocation`, and write a model-facing description carrying the trigger branches (the pointer-writing rules in `SKILL.md` apply in full).
+- A **user-invoked** skill strips the description from the agent's reach: only the human typing its name can invoke it, and no other skill can. Zero context load, but it spends cognitive load — you are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped.
+
+Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
+
+Shared reference that two user-invoked skills both need can live in neither — with no descriptions, neither can fire the other. Push it to a plain file outside the skill system: external reference any skill can point at.
+
+## Splitting by invocation
+
+The invocation cut of splitting (the sequence cut lives in `SKILL.md`): split off a model-invoked skill when you have a distinct leading word that should trigger it on its own — a trigger word you actually use in your prompts — or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
+
+## Router skills
+
+When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each, so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them.

package/template/.cursor/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: writing-for-agents
+description: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
+---
+
+Reference for writing any document an agent consumes — a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable — the agent taking the same _process_ every run, not producing the same output.
+
+When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.
+
+## Context pointers
+
+A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material — and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs — state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
+
+- **Front-load the leading word** — the pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
+- **Cut identity the body already carries.**
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** — the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires.
+- **Cognitive load** — the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise — it is the price of human agency; spend it where human judgement matters, remove it where it does not.
+
+Material reached only through a pointer escapes context load at the price of the pointer's own line; material with no pointer at all rides entirely on cognitive load.
+
+## Information hierarchy
+
+A document is built from two content types — **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand) — that mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-file step** — the primary tier: what the agent does, in order.
+2. **In-file reference** — consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell.
+3. **Disclosed reference** — pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder — out of the main file and behind a pointer — so the top stays legible. Not primarily a token optimisation: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. When a document has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one.
+
+**Co-location** is the within-file companion: where the ladder decides _how far down_ a piece sits, co-location decides _what sits beside it_ once there. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. The test: the document should read like documentation written for the agent — grouped material reads that way; scattered material does not. (Distinct from duplication: that repeats one meaning in two places; scattering fragments one meaning across many.)
+
+**Sprawl** is the failure mode here: a document simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion** — the condition that tells the agent the work is done. Two properties make it a lever:
+
+- **Clarity** — can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: ending the step before it is genuinely done, attention slipping to _being done_. The visible steps still ahead — the **post-completion steps** — supply the pull; the criterion's clarity is the resistance. Defend in order: **sharpen the bound first** (local and cheap); only if it is irreducibly fuzzy _and_ you observe the rush, hide the later steps by splitting the sequence — and hiding only works across a real context boundary (a hand-off or a subagent dispatch; an inline call leaves the later steps in context and clears nothing).
+- **Demand** — how much it requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives **legwork** — the digging the agent does within the work, latent in the wording rather than written as its own step — and it is not step-bound: "every rule applied" binds a body of flat reference just as "every step done" binds a sequence, which is how an all-reference document still carries an exhaustiveness bar.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By sequence** — split a run of steps where the post-completion steps tempt the agent to rush the one in front of it. Keeping them out of view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's later steps to what follows, inviting premature completion.
+- **By invocation** — skill-specific: see [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md).
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the document (_lesson_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free; reach for an existing word first.
+
+It anchors twice. In the body, _execution_: the agent reaches for the same behaviour every time the word appears, and inside flat reference it focuses attention on a class of thing to look for. In a pointer, _invocation_: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the material and reaches it more reliably.
+
+Hunt for opportunities to refactor with leading words. A triad spelled out at three sites, a pointer spending a sentence to gesture at one idea — each is a passage begging to collapse into a single token:
+
+- "fast, deterministic, low-overhead" → _tight_ (a _tight_ loop).
+- "a loop you believe in" → _red_ — a fuzzy gate becomes a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every document is carrying restatements that leading words retire — go find them.
+
+**Negation** is the failure mode beside this lever: steering by prohibition drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Prompt the **positive** — state the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** — the same meaning in more than one place — costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.)
+- The **environment** is a source of truth too — `package.json` scripts, config files, the directory layout, `--help` output — and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
+- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live.
+- Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test — does it change behaviour versus the default? — is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The test also grades leading words: a word too weak to beat the default (_be thorough_ when the agent is already thorough-ish) is a no-op, and the fix is a stronger word (_relentless_), not a different technique.

package/template/.cursor/skills/writing-for-agents/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Writing for Agents"
+  short_description: "Write documents agents consume"

package/template/.cursor/skills/writing-fragments/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: writing-fragments
+description: Writing, explore — mine raw fragments, no structure yet.
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+This is pure **explore**: widen the space of what could be written without committing to structure — committing is _exploit_, a separate skill's job. Run a grilling session that produces fragments, interviewing the user relentlessly about whatever they want to write about. Imposing phases, outlines, or article structure is out of scope here.
+
+As fragments emerge from either side of the conversation, append them to a single markdown file.
+
+If the user did not pass a path, ask once where to save the document, then remember it for the rest of the session.
+
+Capture fragments from the very first thing the user says, including the initial prompt.
+
+On first write, put a single H1 at the top with a working title (it can change later) and nothing else — no metadata, no TOC, no date.
+
+</what-to-do>
+
+<supporting-info>
+
+## What is a fragment
+
+A fragment is any piece of text that might survive into the final article. It must be _readable by the author_ — the author can tell what it means — but it does not need to define its terms or be comprehensible to a cold reader. The bar is "is this a piece of good writing?", not "is this a self-contained argument?"
+
+Fragments are deliberately heterogeneous. Examples of what could be a fragment:
+
+- A sharp sentence you'd want to deploy somewhere but don't yet know where.
+- A claim with a one-line justification.
+- A vignette: a thing that happened, a code snippet, a scenario, an analogy.
+- A half-thought: "something about how X feels like Y, work this out later."
+- A quote, a piece of dialogue, an overheard line.
+- A list of related observations that hang together by feel.
+- A complaint, a confession, a punchline.
+- A **leading word** — a compact metaphor or coinage the whole piece can hang on (one term that names the idea, the way _tracer bullets_ or _fog of war_ names a whole pattern).
+
+Of these, the leading word is the most valuable fragment to land. It is load-bearing: name the right one in explore and it shapes the structure, the transitions, and the title later — paying dividends through the entire exploit phase. When the conversation circles a recurring idea, push to coin a word for it.
+
+The novelist's diary is the model: years of unstructured noticings that later get mined for raw material. Fragments are noticings.
+
+## File format
+
+```markdown
+# Working title
+
+A first fragment lives here.
+
+It can be multiple paragraphs. It can include lists, code, quotes — whatever
+shape the fragment naturally takes.
+
+---
+
+A second fragment.
+
+---
+
+> A quoted line that the user wants to keep around.
+
+A reaction to it.
+
+---
+
+- A cluster of related observations
+- That hang together by feel
+- And want to be near each other
+```
+
+Fragments are separated by a horizontal rule (`\n---\n`). No headings inside the body. No tags. No order beyond the order they were added.
+
+## Writing rhythm
+
+Append silently. Don't ask permission for each fragment. Mention what you added in passing ("adding that"), but don't interrupt the conversation with save dialogs.
+
+Before every write: re-read the file from disk. The user may have edited, reordered, or deleted fragments between turns — preserve their changes. Never overwrite the file; only append (or, if the user asks, edit a specific fragment in place).
+
+The user can say "cut the last one", "rewrite that one sharper", "merge those two" at any time. Treat those as first-class instructions.
+
+</supporting-info>

package/template/.cursor/skills/writing-fragments/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Writing Fragments"
+  short_description: "Mine raw writing fragments"
+policy:
+  allow_implicit_invocation: false

package/template/.cursor/skills/writing-shape/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: writing-shape
+description: Writing, exploit — shape raw material into an article, paragraph by paragraph.
+disable-model-invocation: true
+---
+
+<what-to-do>
+
+The user has passed (or will pass) a markdown file of raw material. Treat it as the input pile — anything from a tidy list of fragments to a wall of unstructured prose to a transcript. The format does not matter. Read it end-to-end before doing anything else.
+
+Then run a shaping session that produces a separate article document. This is **exploit**: the exploring is done, the pile is fixed — commit to a structure and mine the pile to fill it. Do not edit the raw material file — it is read-only to this skill.
+
+If the user did not say where to save the article, ask once and remember the path.
+
+</what-to-do>
+
+<supporting-info>
+
+## The loop
+
+1. **Read the pile.** Read the input file in full. Form a sense of what's in it.
+2. **Establish the prerequisites.** Settle with the user what the reader knows walking in — the concepts that are **grounded** from the start. Everything else must be grounded by a block before a later block can lean on it. See [Grounding](#grounding).
+3. **Draft 2–3 candidate openings.** Each opening should imply a different thesis or angle for the article. Show all of them. Force the user to pick or compose a hybrid. The chosen opening defines what the rest of the article must do.
+4. **Grow paragraph by paragraph.** After the opening lands, ask "given this opening, what does the reader need to hear next?" Pull material from the pile to answer. The next block may only lean on grounded concepts, and grounds new ones as it lands. Argue about the form the next block takes — a paragraph, a list, a table, a callout, a quote, a code block. Each format choice should be deliberate and defensible.
+5. **Append to the article file as you go.** Don't batch. Write each agreed paragraph or block immediately so the user can see the article taking shape.
+6. **Loop step 4 until the article is done.** The user decides when it's done.
+
+## Grounding
+
+Every **concept** has to be **grounded** before a block can lean on it: the reader either walked in knowing it or met it in an earlier block. A block that reaches for an ungrounded concept loses the reader. The unit is the concept, not the word for it — a block can lean on an idea the reader lacks even with no jargon in sight. Where a concept has a name — a **term** — grounding it means landing the idea and the term together.
+
+A concept gets grounded one of two ways:
+
+- **Prerequisite** — grounded before the opening. The reader brings it. Fixed at the start.
+- **Introduced** — a block establishes it, and from then on it's grounded for the rest of the article.
+
+Keep a running list of what's grounded. When you ask "what does the reader need to hear next?", an ungrounded concept the next move needs is itself the answer: ground it first — here or in an earlier block — or you can't make the move. This is the gap-naming of [Pulling from the pile](#pulling-from-the-pile) one level up: there the pile is missing material; here the article is missing a foundation.
+
+The lever is what you make a prerequisite versus what you ground inside the article. Demand too much up front and you shut readers out; ground too much inside and the opening drowns in definitions. Settle it with the user when you establish prerequisites.
+
+## Conversational feel
+
+This is a grilling session inverted. In ideation, the question was "what are you actually noticing?" Here it's "what is this article actually arguing, and in what order does the reader need to hear it?" Push back. Refuse to let weak transitions slide. If a paragraph doesn't earn its place, cut it.
+
+Specific moves to keep using:
+
+- "What does this paragraph do for the reader that the previous one didn't?"
+- "If I cut this, what breaks?"
+- "Is this prose, or should it be a list? Why prose?"
+- "This sentence is doing two jobs — split it or pick one."
+- "The opening promised X. We've drifted to Y. Either re-thread it or change the opening."
+
+## Pulling from the pile
+
+Treat the raw material as a quarry, not a script. Pull a fragment, rework it to fit the surrounding paragraph, and place it. A fragment may be split across multiple paragraphs, merged with another, or paraphrased. The pile's job is to be mined; the article's job is to read as one voice.
+
+If the pile lacks something the article needs, name the gap explicitly: "We need an example here and the pile doesn't have one — give me one now or we cut this section."
+
+## Format arguments to actually have
+
+When choosing how to render a block, weigh these tradeoffs out loud with the user, not silently:
+
+- **Prose vs. list.** Prose carries argument; lists carry parallel items. If items aren't truly parallel, prose is better. If they are, a list is faster to scan.
+- **Inline vs. callout.** Tips, warnings, and asides go in callouts (`> [!TIP]`, `> [!NOTE]`) — but only if they'd genuinely derail the main argument inline. Otherwise leave them inline.
+- **Table vs. repeated structure.** If the same shape repeats 3+ times with the same fields, a table. Otherwise prose with bold leads.
+- **Quote vs. paraphrase.** Quote when the original wording is the point. Paraphrase when only the idea matters.
+- **Code block vs. inline code.** Multi-line, runnable, or illustrative → block. Single token or identifier → inline.
+
+## Writing rhythm
+
+Append to the article file as each block is agreed. Re-read the file from disk before every write — the user may have edited between turns. Never overwrite blindly. If the user wants a paragraph rewritten, edit that specific paragraph in place; leave the rest alone.
+
+## Out of scope
+
+- Mining for new fragments that aren't in the pile (handle gaps as in "Pulling from the pile").
+- Editing the raw material file.
+- Publishing, formatting for a specific platform, or adding frontmatter the user didn't ask for.
+
+</supporting-info>

package/template/.cursor/skills/writing-shape/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Writing Shape"
+  short_description: "Shape raw material into an article"
+policy:
+  allow_implicit_invocation: false

package/template/.cursor/skills/yss-antd-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: yss-antd-design
+description: Use when 原型设计或高保真构建需要查询 Ant Design v6 设计语言、组件 API/demo/token/semantic，或落盘 AntD CLI 证据。不用于前端代码落地（改用 yss-ui）、Vue 生产 API、生命周期批准、安装官方 antd skill，或替代 yss-prototype-stage。
+---
+
+# YSS Ant Design 事实
+
+只服务原型设计与高保真构建。把官方 `@ant-design/cli`、`design.md`、MCP 与 LLMs.txt 收成可追溯的事实引擎。阶段合同仍是 `yss-prototype-stage`。前端代码落地一律改用 `yss-ui`，不要继续调用本技能。
+
+## 何时使用
+
+- 已进入 `yss-prototype-stage` 的高保真产出前后，需要 Ant Design v6 组件 / token / demo / semantic / 上游 `design.md` 事实。
+- 需要写入 `prototype-evidence.yaml` 的 AntD 段。
+
+不要用本技能：前端实现、Vue / Ant Design Vue 生产代码、批准门禁、生成页面流、安装官方 `antd` skill，或运行 `antd setup`。进入实现切片后停用本技能，改走 `yss-ui`。
+
+## 步骤
+
+1. 检测 CLI：优先已安装的 `antd`，否则用 `npx -y @ant-design/cli`。记录实际 CLI 版本。不要在模板源执行 `npm install -g`。
+2. 读项目 `docs/design/design.md` 与 `docs/design/tokens/*`。
+3. 选定 `<target_antd_version>`（项目已选的 v6；未选则先查再记录，不得依赖空仓库自动检测）。此后每次知识查询都传同一版本。
+4. 设置 `ANTD_NO_AUTO_REPORT=1`。一律 `--format json`，对外说明用 `--lang zh`。
+5. 查询官方 `design.md`，再按选用组件跑 `info` / `demo` / `token` / `semantic`。命令矩阵见 `references/cli-matrix.md`。
+6. 把 JSON 路径写入证据清单。字段与 lint 适用范围见 `references/evidence.md`。
+7. 上游默认与项目 token 冲突时，以项目覆盖为准，并标记 `project_override_reviewed`。
+
+## 硬规则
+
+- 禁止凭记忆写 Ant Design v6 API。
+- 禁止 `antd setup`、`npx skills add ant-design/ant-design-cli`，以及把官方 `skills/antd` 拷进 `.agents/skills`。
+- 禁止把官方 `design.md` 的默认色、圆角、间距写回项目实现或覆盖项目 token。
+- 禁止在前端代码落地、垂直切片实现或 `yss-ui` 任务中调用本技能。
+- 禁止把 React props / demo / hook 当作 `yss-ui` 或 Ant Design Vue API。
+- MCP 与 `llms-full.txt` 不是门禁证据。边界见 `references/boundaries.md`。

package/template/.cursor/skills/yss-antd-design/references/boundaries.md

@@ -0,0 +1,30 @@
+# 边界与官方资料
+
+官方文档只提供 React `antd` 事实，不提供 YSS 阶段合同。入口对照：
+
+| 官方资料 | 本技能用法 |
+|---|---|
+| https://ant.design/docs/react/for-agents-cn | 了解 CLI / skill / MCP / LLMs 分层。不要把其中的 “安装 skill” prompt 写进 `AGENTS.md` |
+| https://ant.design/docs/react/cli-cn | 命令与参数的权威说明 |
+| https://ant.design/docs/react/design-md-cn | 上游 `design.md` 定位。项目覆盖是 `docs/design/design.md` |
+| https://ant.design/docs/react/mcp-cn | MCP 是 IDE 加速，8 个知识工具不含 `lint` |
+| https://ant.design/docs/react/llms-cn | CLI 不可用时的降级目录。不要默认注入 `llms-full.txt` |
+| https://ant.design/design.md | 与 `antd design.md` 同一份 v6 上游默认 |
+
+## 与其他技能
+
+- `yss-prototype-stage`：阶段顺序、评审、浏览器验证、用户确认。本技能只回写 AntD 事实段。
+- `yss-design-system`：项目风格与 token 规范。本技能查询上游事实，不得改项目 token。
+- `product-design:index`：Codex 视觉产出。本技能不替代它，也不使用 `antd-page-generator`。
+- `yss-ui`：前端代码落地的唯一 UI 入口。进入实现后不得再查本技能或 `@ant-design/cli` 的 React API。
+- 官方 `antd` skill：不安装、不锁定、不投影。
+
+## MCP 与 LLMs.txt
+
+开发者本机可以运行 `npx -y @ant-design/cli mcp --version <target_antd_version> --lang zh`，但：
+
+- 不把 `.cursor/mcp.json` 提交为模板默认。
+- 不把 MCP 调用记录当成 `evidence.antd-cli-validation`。
+- `antd-page-generator` 不是原型阶段入口。
+
+CLI 不可用时，可用 `https://ant.design/llms.txt` 定位单组件 `.md`，并在证据里写明降级原因。恢复 CLI 后补 JSON 落盘。

package/template/.cursor/skills/yss-antd-design/references/cli-matrix.md

@@ -0,0 +1,38 @@
+# CLI 命令矩阵
+
+运行时入口：已安装的 `antd`，或 `npx -y @ant-design/cli`。记录实际 CLI 版本。知识查询必须带 `--format json`、`--lang zh` 和同一 `<target_antd_version>`。
+
+官方命令说明：https://ant.design/docs/react/cli-cn
+
+## 允许（原型 / 设计事实）
+
+| 命令 | 用途 |
+|---|---|
+| `antd design.md --version <target_antd_version> --lang zh --format json` | 上游默认 Light 主题。只对 antd v6 发布 |
+| `antd list --version <target_antd_version> --format json` | 组件选型 |
+| `antd info <Component> --version <target_antd_version> --format json` | props / 类型 / 默认值 |
+| `antd demo <Component> [name] --version <target_antd_version> --format json` | 可运行 demo 源码（React/TSX） |
+| `antd token <Component> --version <target_antd_version> --format json` | 组件或全局 token |
+| `antd semantic <Component> --version <target_antd_version> --format json` | `classNames` / `styles` 结构 |
+| `antd doc <Component> --version <target_antd_version> --lang zh --format json` | 需要完整文档时 |
+| `antd changelog <v1> <v2> [Component] --format json` | 仅当版本差异影响当前决策 |
+
+`design.md` 对 v5 返回 `UNSUPPORTED_VERSION_FEATURE`。空仓库不传 `--version` 时的回退版本不要假设；必须写进证据。
+
+## 条件允许
+
+| 命令 | 条件 |
+|---|---|
+| `antd lint <tsx-or-src> --format json` | 产物是 React/TSX 源码。HTML 原型不得当作通过 |
+| `antd doctor` / `antd usage` / `antd migrate` | 仅已登记的 React + `antd` 实现仓 |
+| `antd env --format json` | 排障需要环境快照时 |
+
+## 默认禁止
+
+| 命令 | 原因 |
+|---|---|
+| `antd setup` | 会写入 `.agents/skills/antd` 和 `AGENTS.md`，绕过 `skills-lock.json` |
+| `npx skills add ant-design/ant-design-cli` | 同上，安装官方 skill |
+| `antd bug` / `antd bug-cli` | 与 YSS Ticket 无关。保持 `ANTD_NO_AUTO_REPORT=1` |
+| `antd upgrade` | 不得在模板源或未授权时改动全局 CLI |
+| `antd mcp` 作为证据采集 | MCP 调用默认不落盘，见 `boundaries.md` |

package/template/.cursor/skills/yss-antd-design/references/evidence.md

@@ -0,0 +1,26 @@
+# AntD 事实证据
+
+目标文件：`docs/.scratch/<feature>/verification/prototype-evidence.yaml`，字段以 `docs/design/templates/prototype-evidence-template.yaml` 为准。本文件只说明如何填 AntD 段。
+
+## 必填
+
+- `antd.cli_command`：实际调用的可执行文件，`antd` 或 `npx -y @ant-design/cli`。
+- `antd.cli_version`：本轮 `antd -V` 或等价输出，禁止写死模板默认值。
+- `antd.target_antd_version`：本轮全部知识查询使用的同一 v6 版本。
+- `antd.queries.design_md`：`antd design.md ... --format json` 的落盘路径。
+- `antd.queries.components[]`：每个选用组件的 `info_ref` / `demo_ref` / `token_ref` / `semantic_ref`。
+- `design_baseline.project_design_ref`：`docs/design/design.md`。
+- `design_baseline.project_override_reviewed`：上游默认与项目 token 已对照。
+
+JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `llms-full.txt` 或 MCP 对话贴进清单。
+
+## lint
+
+`antd lint` 只对可解析的 React/TSX 源码有规则命中。HTML 原型会出现空 issues（假绿）或 `skippedFiles` / `parse-error` / `partial: true`。
+
+| 产物 | `lint_applicable` | 做法 |
+|---|---|---|
+| `docs/.scratch/<feature>/design/prototypes/index.html` | `not-applicable` | 写 `lint_reason: html-prototype`；`lint_ref` 可空；`lint_passed` 保持 `false`，不得改成 `true` |
+| React/TSX 原型源 | `true` | 对变更文件跑 `antd lint --format json`，保存输出；无 issue 才把 `lint_passed` 设为 `true` |
+
+浏览器验证仍由 `yss-prototype-stage` 采集，不在本技能宣布 `gate.prototype-verified` 通过。

package/template/.cursor/skills/yss-antd-design/scripts/validate-frontmatter.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function validateFrontmatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) throw new Error("Invalid SKILL.md frontmatter block");
+  const fields = new Map();
+  for (const line of match[1].split("\n")) {
+    if (!line.trim()) continue;
+    const index = line.indexOf(":");
+    if (index < 0) throw new Error(`Invalid frontmatter line: ${line}`);
+    fields.set(line.slice(0, index).trim(), line.slice(index + 1).trim());
+  }
+  const keys = [...fields.keys()].sort();
+  if (keys.join(",") !== "description,name") throw new Error(`Expected keys ['description', 'name'], got ${JSON.stringify(keys)}`);
+  const name = fields.get("name");
+  const description = fields.get("description");
+  if (name !== "yss-antd-design") throw new Error("Invalid skill name: " + name);
+  if (!description || description.length > 1024) throw new Error("Description must be present and <= 1024 chars");
+  if (!/yss-ui|官方 antd skill|yss-prototype-stage/.test(description)) {
+    throw new Error("Description must exclude frontend landing via yss-ui, official antd skill, and stage-contract takeover");
+  }
+  return name;
+}
+
+export function validateSetupBan(text) {
+  if (!/禁止 `antd setup`/.test(text)) throw new Error("SKILL.md must forbid antd setup");
+  if (!/npx skills add ant-design\/ant-design-cli/.test(text)) throw new Error("SKILL.md must forbid official skill installer");
+}
+
+async function main() {
+  const skill = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md");
+  try {
+    const text = await readFile(skill, "utf8");
+    const name = validateFrontmatter(text);
+    validateSetupBan(text);
+    console.log(`${name} frontmatter ok`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.cursor/skills/yss-antd-design/scripts/validate-frontmatter.test.mjs

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { validateFrontmatter, validateSetupBan } from "./validate-frontmatter.mjs";
+
+const valid = `---
+name: yss-antd-design
+description: Use when 原型设计。不用于前端代码落地（改用 yss-ui）、安装官方 antd skill，或替代 yss-prototype-stage。
+---
+
+# body
+- 禁止 \`antd setup\`、\`npx skills add ant-design/ant-design-cli\`
+`;
+
+test("accepts the required skill frontmatter", () => {
+  assert.equal(validateFrontmatter(valid), "yss-antd-design");
+});
+
+test("rejects missing exclusion branches in description", () => {
+  assert.throws(
+    () => validateFrontmatter("---\nname: yss-antd-design\ndescription: Use when querying antd.\n---\n"),
+    /exclude frontend landing/
+  );
+});
+
+test("rejects a skill that does not forbid official setup", () => {
+  assert.throws(() => validateSetupBan("# no setup ban"), /forbid antd setup/);
+});