authoring-recipes

编写 Recipes

编写 fullstackrecipes 内容的指南。此技能面向负责构建 fullstackrecipes 项目本身的维护者，而非使用该技术栈的开发者（请参阅 use-fullstackrecipes）。

fullstackrecipes 是一个网站，通过提供一套有明确主张的技术栈、设置说明、最佳实践和可直接克隆的起步项目，帮助开发者和 Agent 构建更出色的全栈应用。它提供四种资源：设置 recipes、技能、cookbook 和 模板。

两个技能目录——不要混淆

此仓库包含两个独立的 skills/ 树，服务于截然不同的受众：

• ./skills/ — 此仓库向使用者提供和发布的技能。这些是面向日常使用、供 Agent 参考的工作流指南（drizzle-queries、authentication-best-practices、workflow-best-practices 等），网站会读取这些指南（并通过 .md 端点以 Markdown 格式提供），使用者也会通过 bunx skills add 安装它们。本技能中提到的“技能”指的就是其中一种。
• ./.agents/skills/ — 此工作区内部用于构建 fullstackrecipes 项目的技能。当前这个 authoring-recipes 技能就位于此处。这些技能不会提供给使用者，也不属于资源目录。

编写或编辑对外提供的技能时，请在 ./skills/<slug>/SKILL.md 中进行编辑。切勿将面向使用者的技能内容放入 .agents/skills/。

Recipe 层级

目录中的每个条目都属于三个层级之一，此外还可以为 cookbook 附加可选模板。层级决定了条目会安装什么，以及其文案可以基于哪些前提。目录的唯一事实来源（slug、标题、描述、标签、requires 和模板链接）是 src/lib/recipes/data.tsx。

第 1 层 — 设置 recipes（type: "setup"）

一次性设置，用于安装某项功能所需的文件、依赖项和配置（例如 neon-drizzle-setup、better-auth-setup）。

• 安装范围应保持原子化。 设置 recipe 只安装自身对应的部分，以确保依赖关系图保持可组合，并且各个 recipe 都可以独立采用。
• 在 requires 中声明前置条件，并在开头说明。 引用前置条件即可；不要重复讲解。对于一两个缺失的前置条件，可以提供精简的备用方案。是否能够独立使用，应由此层级来保证。

Tier 2 — 技能（type: "skill"）

面向日常使用、供 Agent 参考的工作流指南，适用于已配置好的工具（例如 drizzle-queries、authentication-best-practices）。这些是本仓库提供的技能，存放在 ./skills/ 下（而非 .agents/skills/——见上文）。

• 技能是专门编写的，不是操作指南。 唯一可信来源是手工编写的 ./skills/<slug>/SKILL.md（YAML frontmatter + 正文）。网站直接读取该文件中的正文（并通过 .md 端点提供），因此更改一经提交便会生效——无需构建步骤。它们没有 docs/recipes/<slug>.md。
• 正文各节以 ### 开头。 加载器（src/lib/recipes/loader.ts）会去掉 YAML frontmatter 以及第一个 ### 标题之前的所有内容，然后根据 data.tsx 元数据重新生成 # Title、描述和 ## Prerequisites 列表。因此，为便于单独阅读，手工编写的文件以 # Title + 描述 + 前置条件开头，但发布后的正文从第一个 ### 小节开始。请使用 ### 作为正文的顶层小节标题。
• 根据技能所教的内容命名，而不是根据其包装的工具命名。 使用描述性的 slug 和标题（drizzle-queries、testing-best-practices、ralph-loop-workflow），不要使用 using-* 前缀。frontmatter 中的 name: 必须与 slug（文件夹名）一致，# Title 一级标题必须与 src/lib/recipes/data.tsx 中的 title 一致。重命名 slug 时，请将旧 slug 添加到 data.tsx 的 recipeRedirects 中。
• type 根据 Skills 标签推导。 当 data.tsx 中某个条目的 tags 包含 "Skills" 时，该条目就会成为技能（type: "skill"）；其他条目均为设置指南。无需设置单独的 type 字段。
• 面向 Agent 编写，而不是编写面向人的教程。 直接给出模式和代码；省略照顾新手的说明、“步骤 1/2/3”式操作流程，以及 Agent 已经理解的动机说明。使用祈使语气，简明扼要，以示例为先。
• 假定使用标准技术栈，不要模棱两可。 内容应针对设置指南所构建出的确切环境。使用真实路径导入（@/lib/db/client、@/lib/auth/server、@/lib/logging/logger、@/components/ui/* 等）。不要添加“如果你的设置有所不同”之类的注意事项——这种防御性表述会削弱技能的价值。
• 标准技术栈按能力定义，而非按示例指南名称定义：通过 Drizzle 使用 Postgres 数据库、Better Auth 会话、结构化日志、shadcn/ui 组件，以及测试框架。技能可以假定其 requires 链提供的任何能力。
• 切勿提及技术栈的设置过程。 技能只讲运行时 如何完成任务。不要提及设置指南（“由 X 指南设置”“在 Y 中配置”“来自 Z 设置”）——这对技能运行时毫无帮助。requires 元数据已记录设置过程，并会显示为“前置条件”小节，因此正文无需提及。
• 技能通过 skills CLI 安装，而不是作为内容粘贴。安装后，它们会作为 Agent 技能保留，供后续工作使用。

Tier 3 — 指南集（isCookbook: true）

标准的组合式参考：按顺序排列的两阶段设置产物（见下文）。

编写指南集

指南集是设置产物，而非阅读材料合集。运行指南集后，项目中会同时配置好技术栈并安装好技能。

两阶段模式

1. 设置链——按顺序运行设置指南，以安装文件、依赖和配置。
2. 安装技能——通过 bunx skills add 安装技能，让 Agent 在之后继续使用日常工作模式。

排序

将每项技能列在其设置指南之后，不要将所有技能都放在末尾。技能应紧跟其所教的工具。

渲染（自动处理）

组装食谱集时，加载器会根据 type 分流：

• 配置食谱会内联完整内容。
• 技能食谱会渲染为精简章节：## <title> + 动机（描述）+ bunx skills add ... -s <slug> 命令。其内容不会内联——食谱集会将它们安装为技能。

因此，无需将技能内容重复添加到食谱集中。只需在 recipes 中的适当位置加入技能 slug；安装部分会根据其元数据自动生成。

模板

模板是克隆即可使用的起点，包含食谱集组装完成后的完整输出，让使用者能够直接从可运行的代码开始，而不必手动执行每个配置步骤。模板不是独立的目录层级——模板通过 data.tsx 中的两个字段关联到食谱集：

• template — git 克隆路径，由 TEMPLATE_BASE 构建（例如 `${TEMPLATE_BASE}/base-app#main`）。
• githubUrl — 用于浏览模板源码的 GitHub URL，由 GITHUB_TEMPLATE_BASE 构建。

模板源码位于仓库根目录下的 templates/<name>/，是一个真实可运行的项目。提供可克隆起始模板的食谱集也带有 "Starter template" 标签（参见 getStarterTemplates）；目前包括 base-app、auth、stripe-sync 和 ai-workflow。

编写规则：

• 使模板与对应的食谱集保持同步。 模板必须准确反映按顺序运行该食谱集中的食谱后得到的输出。更改配置食谱时，也要更新对应的模板目录，否则克隆即用的模板就会与文档描述不一致。
• 模板是组装好的技术栈，不是文档。 不要在模板中添加教程文字或食谱 Markdown——模板作为可运行的应用发布（包含自己的 agents.md、.agents/skills/ 等），说明文字则放在食谱或食谱集中。
• 在食谱集中引用模板，不要重复添加。 仅在食谱集上设置 template / githubUrl；网站会根据这些元数据渲染克隆命令。

可安装工具

编写包含可安装工具的食谱时，请使用 {% registry %} 标签，同时提供 CLI 安装和源码查看功能。

Registry 标签

Registry 标签会渲染：

1. 通过 shadcn CLI 安装 — 可复制的工具安装命令
2. 源码查看器 — 可折叠的代码块，显示完整源码

用法示例：

{% registry items="assert" /%}

这会渲染 CLI 命令和 public/r/assert.json 中的源码。用户可以通过 CLI 安装，也可以直接复制代码。

避免重复代码

使用 registry 标签时，不要在食谱中重复添加代码。registry 标签会自动显示源码。

错误示例：

{% registry items="workflow-stream" /%}

Install via the registry above, or create manually:

\`\`\`typescript
// src/workflows/steps/stream.ts
// ... same code as registry item ...
\`\`\`

正确示例：

{% registry items="workflow-stream" /%}

Import and use the stream utilities in your workflow:

\`\`\`typescript
import { startStream, finishStream } from "@/workflows/steps/stream";
\`\`\`

registry 标签已经提供安装命令和源码。只需补充不属于可安装代码本身的用法示例或说明。

---

参考资料

• fullstackrecipes.com - 浏览所有食谱和食谱集
• 索引 - 包含每个食谱和食谱集及其 slug（在任意页面 URL 后添加 .md 即可获取 Markdown）