Back to Details

design-schema

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design a Prepr content model

设计 Prepr 内容模型

Interview the user, then write a content model plan they have agreed to. This skill makes no changes in Prepr; building is create-schema's job. Its output is an agreed plan plus a confirmed decision list.
The failure this skill exists to prevent: building forty models from a one-line brief, then discovering the model does not match how the site is actually edited. Questions are cheap now and expensive after content exists.
Scope check before starting. If the model is already agreed and written down, skip to create-schema.
This skill is for designing a model, not for changing one. Adding a field to an existing model, or one small model to a schema that already exists, does not need an interview, a stakeholder round, or a plan document — go straight to create-schema, which has a path for extending a live schema. Run this skill for an existing project only when the change is structural: a new content type with its own relationships, a page-builder vocabulary, a taxonomy, or a reshaping that will migrate existing content.
Read the live schema first. Run the check. If Prepr tools are present, page through 
list_schema
before asking anything: reuse existing models and components, and avoid name clashes. This skill also works without MCP; then read the files in 
prepr/schema/
if the project has them, or ask the user what already exists.
与用户访谈，然后编写一份双方已达成一致的内容模型计划。此 skill 不会对 Prepr 做出任何更改；构建是 create-schema 的职责。其输出为一份达成一致的计划和一份已确认的决策清单。
此 skill 的存在是为了防止以下问题：根据一行简述构建出四十个 model，随后才发现该 model 与网站实际的编辑方式不符。现在提问成本很低，而内容已经存在之后再调整成本很高。
开始前检查范围。 如果 model 已经达成一致并记录在案，请直接跳到 create-schema。
此 skill 用于设计 model，而非修改 model。 向现有 model 添加字段，或向已有 schema 添加一个小型 model，无需访谈、利益相关者评审或计划文档——请直接转到 create-schema，该 skill 提供了扩展线上 schema 的路径。仅当变更具有结构性时，才对现有项目运行此 skill：新增具有独立关系的 content type、页面构建器词汇、taxonomy，或会迁移现有内容的结构重塑。
先读取线上 schema。 运行检查。如果存在 Prepr 工具，请在询问任何问题之前逐页查看 
list_schema
：复用现有 model 和 component，并避免名称冲突。如果项目没有 MCP，此 skill 仍然可用；此时读取项目 
prepr/schema/
下的文件（如果存在），或询问用户当前已有哪些内容。

The route to an agreed model

达成一致 model 的路径

The steps below are one conversation, but the model they produce passes through phases with different people in them:
  1. Frame — the design source, editors, locales, and personalization posture are known. Step 1.
  2. Inventory — what the site actually publishes, worked out from what exists rather than from the industry. Steps 2–3.
  3. Stakeholder round — the people whose absence is visible in a finished schema see the model before it is agreed, and are asked about its shape rather than its field names. Who they are, and what each one's absence looks like afterwards: schema-design-principles.md.
  4. Plan — the plan is the thing everyone reviews and agrees. It stays in chat; save it to 
    docs/prepr/schema-plan.md
    only if the user asks (useful when others need to review it). Step 5.
  5. Validate — the agreed plan is built in a Scratch environment and an editor builds a real page in it, before any front-end work. Step 6.
  6. Build — create-schema, then review-schema. Step 8 hands off.
The gate that matters is between 5 and 6. Once content exists or the front end is built on the schema, findings stop being free — see schema-design-principles.md.
以下步骤属于同一场对话，但其产出的 model 会经历由不同人员参与的各个阶段：
  1. 界定框架——明确设计来源、编辑者、语言区域和个性化策略。进入步骤 1。
  2. 盘点——从实际存在和发布的内容出发，而非依据行业惯例推断。进入步骤 2–3。
  3. 利益相关者评审——在最终 schema 确定前，让那些若缺席就会在成品 schema 中留下明显缺失的人审阅 model，并就其结构而非字段名称征求意见。应有哪些人参与，以及每个人缺席后会在成品中留下哪些缺失：schema-design-principles.md。
  4. 计划——这份计划是所有人审阅并达成一致的对象。它保留在聊天中；仅当用户提出要求时，才保存到 
    docs/prepr/schema-plan.md
    （当他人也需要审阅时，这会很有用）。进入步骤 5。
  5. 验证——将达成一致的计划构建到 Scratch 环境中，并让一名编辑人员用其构建一个真实页面，然后才进行任何前端工作。进入步骤 6。
  6. 构建——先执行 create-schema，再执行 review-schema。最后由步骤 8 移交。
最关键的关卡位于步骤 5 与步骤 6 之间。一旦内容已经存在，或前端已基于该 schema 构建，届时再发现问题就会产生高昂代价——参见 schema-design-principles.md。

Ground rules for the conversation

对话的基本规则

  1. Ask, do not assume. Never invent a model list from the project's industry. "A marketing site" tells you almost nothing about what they publish.
  2. One topic at a time. Ask 1–3 related questions per turn, wait for the answer, then move on. Do not send a 20-question survey.
  3. Offer concrete options over open prompts. "Do articles have one author, several, or none?" beats "tell me about authors." Where a default is clearly right, state it and ask only for a correction.
  4. Show, then check. Reflect each answer back as a concrete modeling consequence ("so 
    Article.authors
    is a reference to 
    Person
    , max 3") so the user can catch a misread immediately.
  5. Cite reality, not patterns. Ground every model in something the user said they publish or edit. If you cannot point to a stated need for a model, drop it.
  6. Stop when it is enough. The goal is a plan good enough to build and easy to extend — not a complete model of every future page. Fields are easy to add later.
  1. 询问，不要臆测。 绝不能根据项目所属行业自行编造 model 清单。“一个营销网站”几乎无法说明他们实际发布什么内容。
  2. 一次只讨论一个主题。 每轮询问 1–3 个相关问题，等待回答后再继续。不要发送一份有 20 个问题的调查问卷。
  3. 提供具体选项，而不是开放式提问。 “文章有一名作者、几名作者，还是没有作者？”优于“请介绍一下作者”。如果某个默认值明显合理，先说明默认值，只请用户确认或更正。
  4. 先展示，再确认。 将每个回答具体映射为建模结果（“因此 
    Article.authors
    是指向 
    Person
    的引用，最多 3 个”），以便用户立即发现理解偏差。
  5. 依据实际情况，而非惯用模式。 每个 model 都应建立在用户明确表示会发布或编辑的内容之上。如果无法指出某个 model 的明确需求，就将其删除。
  6. 足够时即停止。 目标是制定一份足以开始构建且易于扩展的计划——而不是穷尽所有未来页面。字段以后很容易添加。

Step 1: Understand the project

步骤 1：了解项目

Before modeling anything, establish:
  • What is being built. A marketing site, a documentation site, an app's content backend, a webshop, an intranet? What already exists — is this a rebuild of a live site (get the URL and look at it), a migration from another CMS (which one), or greenfield?
  • Who edits it. A single technical owner, a marketing team, dozens of contributors across departments? Editor skill level and volume change how much structure versus freedom the model should have.
  • What the front end is. Framework, and whether it exists yet.
  • What the design source is. A design system, Figma file, component library, or the existing site — get the link. The section vocabulary and the display-freedom decisions in Steps 3 and 4 are read from it; without one, those answers must come from the user question by question.
  • Languages and locales, if any. Multilingual is far cheaper to plan for now than to retrofit.
  • Personalization, A/B testing, or recommendations — planned, maybe later, or not at all. This decides which stacks need 
    personalization
    and 
    a_b_testing
    enabled at design time, and it drives front-end caching decisions later.
If the user is rebuilding an existing site, offer to inventory it: list the page types and repeated section patterns you can see, and use that as the starting point for Step 2 rather than asking them to describe it from memory.
在建模前，需要明确：
  • 正在构建什么。 是营销网站、文档站点、应用的内容后端、网店还是企业内网？目前已有哪些内容——这是对线上站点的重建（获取 URL 并查看）、从另一个 CMS 迁移（是哪一个），还是全新项目？
  • 由谁编辑。 是单一技术负责人、营销团队，还是跨部门的众多贡献者？编辑人员的技能熟练度和内容量会决定 model 应提供多少结构性与自由度。
  • 前端是什么。 使用什么框架，以及是否已经存在。
  • 设计来源是什么。 是设计系统、Figma 文件、component 库，还是现有站点——获取链接。section 词汇以及步骤 3 和步骤 4 中的展示自由度决策都应从中读取；如果没有设计来源，这些答案必须逐项向用户询问。
  • 语言和语言区域（如有）。现在规划多语言远比之后改造便宜。
  • 个性化、A/B 测试或推荐——是计划中功能、以后可能添加，还是完全没有。这决定设计时哪些 stack 需要启用 
    personalization
    和 
    a_b_testing
    ，也会影响后续的前端缓存决策。
如果用户正在重建现有站点，可主动提出为其盘点：列出你能看到的页面类型和重复的 section 模式，并以该结果作为步骤 2 的起点，而不是让用户凭记忆描述。

Step 2: Inventory the content

步骤 2：盘点内容

Work outward from what the site actually publishes.
  1. Routable things — what has its own URL? Pages, articles, products, events, profiles, case studies. For each: roughly how many, who writes them, and what the URL looks like (this becomes the slug template, and any 
    /parent/child/
    structure means a self-reference).
  2. Repeated entities — things that appear in several places and should exist once: authors, testimonials, logos, locations, FAQ items, pricing plans, taxonomy terms. Ask directly: "if this appears on three pages and someone edits it, should all three change?" Yes → its own Model.
  3. Site-wide singletons — navigation, footer, global banner, site settings.
  4. External data — anything mastered in another system (a product catalog, an events API). That should not be copied into a Prepr model; note it under "Deliberately not modeled" and say that connecting it as a remote source is outside these skills.
For each candidate, capture the fields the front end will actually render. Resist fields nobody named.
从网站实际发布的内容向外梳理。
  1. 可独立路由的内容——哪些内容拥有自己的 URL？页面、文章、产品、活动、个人资料、案例研究等。对每一种：大致数量、谁编写、URL 形式（这会成为 slug 模板；任何 
    /parent/child/
    结构都意味着需要自引用）。
  2. 重复实体——在多个位置出现且应只维护一份的内容：作者、用户评价、logo、地点、FAQ 条目、定价方案、taxonomy 术语。直接询问：“如果某项内容出现在三个页面上，而有人编辑了它，是否三个页面都应随之改变？”是 → 应建立独立的 Model。
  3. 全站单例——导航、页脚、全局横幅、站点设置。
  4. 外部数据——由其他系统维护的内容（产品目录、活动 API）。这类数据不应复制到 Prepr model 中；应将其记录在“刻意不建模”部分，并说明将其作为 remote source 接入超出了这些 skill 的范围。
对于每个候选项，记录前端实际会渲染的字段。不要添加无人提及的字段。

Step 3: Decide the composition shape per model

步骤 3：决定每个 model 的组合结构

This is the decision users most often get handed to them as a house style rather than a choice. There is no default shape. For each routable model, pick deliberately:
  • A flexible stack of components — for pages whose layout editors need to vary and reorder. Ask: "does marketing need to build new page layouts without a developer?"
  • A fixed field list — for strongly-structured content where every item has the same parts: pricing plans, team profiles, product specs, event details. A page builder here just gives editors a way to break the design.
  • Rich text with embeddable components — for article and documentation bodies, where the content is prose with occasional embeds.
  • A mix — very common: fixed fields for the structured part plus one stack for flexible extra content below it.
If a stack is right, decide the nesting just as deliberately:
  • Flat — the block types sit directly in the page's stack. Right when the block library is small or each block is self-contained. Fewer clicks for editors, one less level in every query and mapper.
  • Nested — sections that each hold a stack of blocks. Right when display settings (background, width, spacing, column count) belong on a shared wrapper, or when a large block library is reused across several section types.
Nesting everything inside a generic content section is one pattern among several, not a requirement — do not adopt it unless one of those two reasons applies. State which you picked and why in the plan.
When the plan names field types, use the editor names (Text, Rich text, Content reference, Stack, Component, Enum, …). create-schema maps them to tool parameters and has the per-type "use when / don't use when" guide.
Then confirm each Model vs Component vs Enum call, per https://docs.prepr.io/content-modeling/fundamentals: identity and reuse or its own URL → Model; structure that only exists inside an item → Component; a fixed choice list → Enum, never free text.
这通常是用户最常被当作既定 house style 直接接受的决策，而不是真正由他们做出的选择。不存在默认结构。对每个可路由 model，都应有意识地选择：
  • 由 component 构成的灵活 stack——适用于需要由页面编辑人员改变和重排布局的页面。询问：“营销团队是否需要在没有开发人员的情况下构建新的页面布局？”
  • 固定字段列表——适用于高度结构化的内容，其中每个条目都由相同部分构成：定价方案、团队简介、产品规格、活动详情。在此使用页面构建器只会让编辑人员有机会破坏设计。
  • 支持嵌入 component 的 Rich text——适用于文章和文档正文，其内容以叙述为主，偶尔包含嵌入内容。
  • 混合方式——很常见：结构化部分使用固定字段，同时在其下方添加一个 stack，用于灵活扩展内容。
如果 stack 合适，还应有意识地决定嵌套方式：
  • 扁平——block 类型直接位于页面的 stack 中。适用于 block 库较小或每个 block 都自成一体的情况。这样可减少编辑人员的点击次数，并让每次 query 和 mapper 少一层嵌套。
  • 嵌套——每个 section 内部包含一个 block stack。适用于展示设置（背景、宽度、间距、列数）应作用于共享 wrapper，或大型 block 库需要在多个 section 类型中复用的情况。
把所有内容都嵌套在通用 content section 里只是多种模式之一，并非硬性要求——除非符合上述两个原因之一，否则不要采用。请在计划中说明所选方式及原因。
当计划中指明字段类型时，使用编辑器中的名称（Text、Rich text、Content reference、Stack、Component、Enum 等）。create-schema 会将其映射为工具参数，并提供按类型划分的“何时使用/何时不要使用”指南。
然后根据 https://docs.prepr.io/content-modeling/fundamentals 逐一确认每个 Model vs Component vs Enum 决策：具有独立身份和复用需求或拥有自己的 URL → Model；只存在于某个条目内部的结构 → Component；固定的选项列表 → Enum，绝不能使用自由文本。

Step 4: Probe the decisions that are painful to reverse

步骤 4：探查难以逆转的决策

Ask about these explicitly, because retrofitting them means migrating content:
  • Multilingual — which fields are translated, which (URLs, codes, names) are not. Also whether Prepr's AI translation is acceptable: it sends field content through OpenAI, which privacy-sensitive projects may decline — ask, do not default it on.
  • Personalization and A/B testing — which stacks need it enabled.
  • Taxonomy — default to modelling terms yourself as small Models (
    Topic
    , 
    Industry
    ): most freedom, since a term can then carry fields, a landing page and slug, hierarchy, and its own curation workflow. Prepr's built-in tags (
    Tags
    field, plus tag groups to restrict entry — see https://docs.prepr.io/mutation-api/tags) are the lightweight option for terms that really are just labels. Ask what each term has to do: "does a topic need its own page, a description, or an image?" and "who is allowed to invent a new term?" Any yes on the first, or a curated vocabulary on the second, means a Model. Say which you chose and why — swapping tags for a model later means migrating every item that used them.
  • Editor display freedom — default to the least: the design system owns spacing, backgrounds, and layout, and a section ships with no display fields. Ask which sections genuinely need per-instance variation, or read it off the design source from Step 1 (where the design shows the same section on light and dark backgrounds, that variation is real), and expose only those — as shared enums with defaults, per schema-design-principles. Every exposed knob is a permanent front-end promise, so this is decided per section, never as a blanket style.
  • Relationships and cardinality — one or many, and which side owns the reference. Also which fields need 
    filterable
    because a listing page will filter on them.
  • URL structure — flat or hierarchical, and whether URLs will change (which means a redirect model — Prepr has no built-in redirect feature).
  • Publishing workflow — scheduled publishing, drafts, review states, who approves.
  • Growth — what content types are likely next quarter. Not to build them, but to check the shape does not block them.
由于事后改造意味着迁移内容，因此要明确询问以下事项：
  • 多语言——哪些字段需要翻译，哪些（URL、代码、名称）不翻译。此外还要确认 Prepr 的 AI translation 是否可接受：它会通过 OpenAI 发送字段内容，隐私敏感项目可能拒绝使用——应询问用户，不要默认启用。
  • 个性化和 A/B 测试——哪些 stack 需要启用这些功能。
  • Taxonomy——默认自行将术语建模为小型 Model（如 
    Topic
    、
    Industry
    ）：灵活性最高，因为术语可以包含字段、落地页和 slug、层级关系及自己的策划工作流。Prepr 内置的 tags（
    Tags
    字段，以及用于限制可选内容的 tag group——参见 https://docs.prepr.io/mutation-api/tags）是轻量方案，适用于确实只作为标签使用的术语。询问每个术语需要承担什么职责：“topic 是否需要自己的页面、描述或图片？”以及“谁可以创建新术语？”第一个问题只要回答“是”，或第二个问题表明术语集需要被策划，就应使用 Model。说明选择了哪一种以及原因——以后将 tags 换成 model 意味着迁移所有使用它们的条目。
  • 编辑人员的展示自由度——默认取最小自由度：由设计系统掌控间距、背景和布局，section 不提供任何展示字段。询问哪些 section 确实需要逐实例变化，或从步骤 1 的设计来源中读取（如果设计显示同一 section 会出现浅色和深色背景，则这种变化是真实需求），并且只开放这些变化——按照 schema-design-principles，以带默认值的共享 enum 实现。每个开放的调节项都是对前端的永久承诺，因此应逐 section 决策，绝不能一刀切地应用某种样式。
  • 关系与基数——是一个还是多个，以及由哪一侧持有引用。还要确定哪些字段需要 
    filterable
    ，因为列表页会按这些字段筛选。
  • URL 结构——扁平还是层级式，以及 URL 是否会变化（若会变化，则需要 redirect model——Prepr 没有内置 redirect 功能）。
  • 发布工作流——定时发布、草稿、审核状态，以及由谁批准。
  • 增长——下个季度可能新增哪些 content type。此处不构建它们，只检查当前结构不会阻碍扩展。

Step 5: Write the plan and get agreement

步骤 5：编写计划并达成一致

Write the plan in chat using this structure. Save it to 
docs/prepr/schema-plan.md
only if the user asks.
markdown
undefined
使用以下结构在聊天中编写计划。仅当用户提出要求时，才保存到 
docs/prepr/schema-plan.md
。
markdown
undefined

Content model plan: <project>

Content model plan: <project>

Context

Context

Front end, editors, locales, personalization posture, migration source.
Front end, editors, locales, personalization posture, migration source.

Models

Models

<Name> (Model | Component | Enum)

<Name> (Model | Component | Enum)

  • Why it exists: <the stated need>
  • Shape: <fixed fields | stack (flat/nested) | rich text | mix> — <why>
  • Fields: name — type — notes (required, filterable, translated, default)
  • URL: <slug template, if routable>
  • Relationships: <references in and out, cardinality>
  • Why it exists: <the stated need>
  • Shape: <fixed fields | stack (flat/nested) | rich text | mix> — <why>
  • Fields: name — type — notes (required, filterable, translated, default)
  • URL: <slug template, if routable>
  • Relationships: <references in and out, cardinality>

Composition decisions

Composition decisions

Which models use which shape, and the reason for each — especially any nesting choice.
Which models use which shape, and the reason for each — especially any nesting choice.

Deliberately not modeled

Deliberately not modeled

Things discussed and excluded, with the reason. Prevents re-litigating.
Things discussed and excluded, with the reason. Prevents re-litigating.

Open questions

Open questions

Anything still unresolved, and what unblocks it.

Then present a short summary in chat — the model list, the composition
decision per model, and any open question — and ask for explicit
confirmation or corrections. Iterate on the plan until the user agrees.
Do not build anything in Prepr inside this skill.

Agreement means the stakeholder round, not only the person in the chat. Ask
who has seen the plan, and name who is missing rather than treating silence
as approval — an absent stakeholder is a decision worth recording in the
plan, not a gap to discover later.
Anything still unresolved, and what unblocks it.

然后在聊天中给出简短摘要——model 列表、每个 model 的组合决策，以及所有待解决问题——并请求用户明确确认或提出更正。持续迭代计划，直到用户达成一致。此 skill 内不要在 Prepr 中构建任何内容。

达成一致意味着利益相关者评审已经完成，而不只是聊天中的用户同意。询问谁看过该计划，并指出谁尚未参与；不要把沉默视为批准——缺席的利益相关者本身就是一项应记录在计划中的决策，而不是日后再发现的缺口。

Step 6: Validate the model before building on it

步骤 6：构建前验证 model

A plan that reads well can still fail in use, and the only way to find out is to have someone build with it. Offer this explicitly — teams skip it because the plan looks finished:
  • Build it in a Scratch environment with create-schema and have an editor try one real page in it. No front-end work yet.
  • Use the three hardest existing pages, not the easiest.
  • Have the front-end developer write one real query against it at the same time.
What to watch for while they work, and why the timing is the whole point: schema-design-principles.md.
Feed what it turns up back into the plan and re-agree it before handing off. If the user declines the round — no environment yet, no editor available — say what they are trading: a finding that is free today costs a content migration once items exist.
一份读起来合理的计划仍可能在实际使用中失败，而唯一的发现方式就是让有人实际使用它。明确提出这一点——团队常因计划看起来已经完成而跳过验证：
  • 使用 create-schema 在 Scratch 环境中构建它，并让编辑人员尝试用其构建一个真实页面。此时还不进行任何前端工作。
  • 使用现有三个最难的页面，而不是最简单的页面。
  • 同时让前端开发人员针对它编写一个真实 query。
验证期间应关注什么，以及为何时机至关重要：schema-design-principles.md。
将验证发现反馈到计划中，并在移交前重新达成一致。如果用户拒绝进行本轮验证——尚无环境、没有可用编辑人员——要明确说明他们将舍弃什么：今天零成本发现的某个问题，会在条目存在后变成一次内容迁移。

Step 7: Environment AI context

步骤 7：环境 AI 上下文

Steps 1 to 4 tell you most of what the environment's AI context needs: organisation, audience, purpose, tone, languages and content types. Draft it in the shape from ai-context.md, show it with the plan, and ask the user to paste it under Settings → General → AI context.
步骤 1 至步骤 4 已涵盖环境 AI 上下文所需的大部分信息：组织、受众、用途、语气、语言和 content type。按照 ai-context.md 中的格式起草，与计划一并展示，并请用户将其粘贴到 Settings → General → AI context 下方。

Step 8: Hand off

步骤 8：移交

Once the plan is agreed, say that the next step is create-schema, which shows the exact changes and builds them after a yes. create-schema picks the route: live through MCP, or schema files in 
prepr/schema/
when the project syncs its schema with Git. Do not start building without telling the user.
计划达成一致后，说明下一步是 create-schema；该 skill 会展示具体变更，并在获得确认后进行构建。
create-schema 会选择执行路径：通过 MCP 操作线上环境，或在项目通过 Git 同步 schema 时使用 
prepr/schema/
下的 schema 文件。不要在告知用户之前开始构建。

Related skills

相关 skill

Build the plan with create-schema. Audit an existing schema with review-schema. Patterns and anti-patterns: schema-design-principles.md.
使用 create-schema 构建计划。使用 review-schema 审计现有 schema。模式与反模式参见：schema-design-principles.md。