企业官网建设流程全解析

claude-cookbooks 中的 /add-registry 斜杠命令：自动化维护 registry.yaml 元数据注册表

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks

在 claude-cookbooks 仓库中，上百个 Jupyter Notebook 通过根目录的 registry.yaml 统一登记，配合 authors.yaml 维护作者信息，共同构成 cookbook 网站的内容源。仓库内置的 Claude Code 斜杠命令/add-registry（定义于 .claude/commands/add-registry.md）就是为这一维护流程量身设计的：它指导 Agent 读取新 notebook、校验作者身份、生成符合 schema 的注册条目，并在人工确认后再落盘。读完本篇，你能完整复现“新增一个 notebook 并正确入库”的全流程，理解该命令每一步背后的字段约束与 CI 校验机制。

一、背景：registry.yaml 与 authors.yaml 的元数据体系

/add-registry命令的工作对象是两个位于仓库根目录的 YAML 文件：

• registry.yaml：cookbook 元数据注册表，每个条目记录一个 notebook 的标题、描述、路径、作者、日期与分类。文件首行通过 yaml-language-server 指令绑定 schema：

  # yaml-language-server: $schema=./.github/registry_schema.json - title: Build a data analyst agent with Claude Managed Agents description: Build an analyst that turns a CSV into a narrative HTML report with interactive charts, using a sandboxed environment and file mounting. path: managed_agents/data_analyst_agent.ipynb authors: - charmaine - jyan-anthropic date: '2026-04-08' categories: - Claude Managed Agents - Tools

• authors.yaml：作者映射表，把 registry 中使用的 GitHub 用户名映射到网站展示所需的完整信息。文件头部注释明确说明其用途：“This file maps author GitHub usernames (used in registry.yaml) to their full details for display on the website.” 真实条目形如：

  charmaine: name: Charmaine Lee website: https://github.com/charmaine avatar: https://avatars.githubusercontent.com/u/16736130?v=4

之所以值得用一条斜杠命令来维护，是因为这两个文件受到严格的双重约束：schema 校验 + CI 联网核验（详见第五节）。手工编写极易在字段拼写、分类枚举、日期格式、作者一致性上出错，而/add-registry把这些规则固化为 Agent 的操作性指令。

二、命令文件结构：frontmatter 与 allowed-tools

.claude/commands/add-registry.md 遵循 Claude Code 斜杠命令的标准格式：YAML frontmatter 声明命令元信息，正文是发给 Agent 的自然语言指令。

--- allowed-tools: Read,Glob,Grep,Edit description: Add a new notebook to registry.yaml ---

frontmatter 中两项声明都值得注意：

1. description：一句话说明命令用途（“Add a new notebook to registry.yaml”），它会在 Claude Code 的命令列表中作为提示文本展示。
2. allowed-tools：将该命令允许使用的工具收窄为Read, Glob, Grep, Edit四项——前三个只读工具用于“读 notebook、搜文件、匹配内容”，唯一的写权限交给Edit。这种最小权限设计意味着 Agent 不能执行任意 Bash 命令或全局重写文件，只能做精确的编辑操作。对比同目录下 .claude/commands/notebook-review.md 声明的allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),...，可以看到每个命令都按职责单独圈定工具范围。

CONTRIBUTING.md 也印证了这套机制的定位：“These commands are automatically available when you work in this repository with Claude Code”，并且命令定义存放在.claude/commands/目录，“for both local and CI use”——本地开发与 GitHub Actions CI 复用同一份命令定义。

三、核心流程：三步生成注册条目

命令正文以 “Add a new entry toregistry.yamlfor the notebook specified in the prompt above” 开头，随后给出编号指令。完整流程可拆为三步。

步骤 1：读取 notebook 理解其内容

Read the notebookat the specified path to understand its content

这是后续 title、description、categories 三个字段生成的信息源：标题从 notebook 首个 heading 提取，分类依据 notebook 的主体技术主题。Read、Glob、Grep三个只读工具正是为此配置。

步骤 2：校验作者是否存在于 authors.yaml

Check author existsinauthors.yaml

具体规则：

1. 向用户询问 notebook 作者的 GitHub username；
2. 读取 authors.yaml 检查该 username 是否已作为 key 存在；
3. 若不存在，向用户收集信息并新增作者条目，字段为：
   • name：完整展示名；
   • website：GitHub profile URL 或个人网站；
   • avatar：默认使用https://github.com/<username>.png。

这一步与 authors.yaml 头部注释呼应：registry 中的作者只是用户名，展示用的详细信息集中存放于 authors.yaml。注意 authors.yaml 的 key 需通过 scripts/validate_authors_sorted.py 的排序检查（见第五节），新增作者时要保持 case-insensitive 字母序。

步骤 3：生成 registry 条目

命令为条目字段给出了完整规格。

必需字段

关于 categories 有一个值得留意的细节：命令文档列出的 14 个分类比 .github/registry_schema.json 的enum少一项——schema 中还包含 “Claude Managed Agents”，且 registry.yaml 中有大量条目（如CMA_operate_in_production.ipynb、CMA_with_mongodb_atlas.ipynb）使用了该分类。可以推断命令文档的分类列表落后于 schema 更新，实际操作时以 schema 的枚举为准更安全。

样式规范（Style Guidelines）

• Title：简洁但有描述性，可参照既有条目风格；
• Description：约 15–20 词，聚焦“用户将学到/构建什么”；
• Categories：选择最贴合 notebook 主要聚类的分类。

命令文档还直接给出两种条目的标准格式：

authors.yaml（仅新作者时）：

github-username: name: Full Name website: https://github.com/github-username avatar: https://github.com/github-username.png

registry.yaml：

- title: Example Notebook Title description: Brief description of what this notebook covers and teaches users. path: category/notebook_name.ipynb authors: - github-username date: 'YYYY-MM-DD' categories: - Category Name

对照 registry.yaml 中的真实条目（如 “Programmatic tool calling (PTC)”、"Retrieval augmented generation"），可以看到描述均控制在两行内、聚焦学习成果，与样式规范一致。

四、输出阶段：先审后写与排序约定

命令的 Output 章节定义了一个明确的人工审核（human-in-the-loop）闸门：

1. 若作者为新作者，先展示拟定的authors.yaml条目供审阅，获批后追加；
2. 展示拟定的registry.yaml条目供审阅；
3. 用户批准后，才使用Edit工具把条目追加进registry.yaml；
4. 条目在文件内按path保持字母序；无法判断插入点时，追加到文件末尾。

“先展示、后 Edit”的流程设计解释了 frontmatter 为何只给一个Edit权限：Agent 的写入被限制在“追加一个条目”这一最小动作上，且前置人工确认，降低了元数据污染风险。需要说明的是，registry.yaml 现状并非严格按 path 字母序排列（如tool_use条目之后还追加了managed_agents/CMA_remember_user_preferences.ipynb等新条目），这与命令中“append to the end if unclear”的兜底规则相符——字母序是约定而非强制，排序强制只作用于 authors.yaml。

五、仓库侧的校验闭环：schema、verify 脚本与 CI

/add-registry生成的条目并非“写完即结束”，仓库内置了一套完整的校验体系为其兜底。

5.1 JSON Schema 约束

.github/registry_schema.json 定义了 registry 条目的机器可读约束，其中对/add-registry输出质量影响最大的是：

• required：["title", "path", "categories", "authors", "date"]——恰好覆盖命令文档列出的必需字段，description虽不在 required 中，但命令要求必写；
• additionalProperties: false：不允许出现 schema 未声明的字段。可选字段为slug（正则^[a-z0-9-]+$）、github_url、tags、difficulty（beginner/intermediate/advanced/空串）、use_case、thumbnail、archived；
• date正则：^\d{4}-\d{2}-\d{2}$，与命令中“YYYY-MM-DD”要求一致；
• categories枚举：15 个分类值、minItems: 1，即“1–2 个分类”的下限约束；
• authors：minItems: 1，注释明确 “GitHub username (must match keys in authors.yml)”。

.github/authors_schema.json 则约束 authors.yaml：key 必须匹配^[a-zA-Z0-9_-]+$（即合法 GitHub 用户名字符集），每个作者对象仅name必填，website与avatar为可选 URI，且additionalProperties: false——这也解释了为何 avatar 有https://github.com/<username>.png的默认约定：schema 描述中写明 “Avatar image URL (optional, defaults to https://github.com/username.png)”。

5.2 verify_registry.py：四类核验

.github/scripts/verify_registry.py 是这套元数据的完整性校验器，支持子命令all（默认）、authors、paths、registry、schema，对应四类检查：

• authors（check_github_handle）：对 authors.yaml 中每个 key 发 HEAD 请求确认 GitHub profile 存在（404 即失败），并核验 website/avatar URL 可访问；其中对x.com域名做了跳过处理，因为该站屏蔽 HEAD 请求；
• registry（verify_registry_authors）：收集 registry.yaml 全部作者的并集，逐一确认其在 authors.yaml 中有定义——这正是/add-registry步骤 2 的自动化复核；
• paths（verify_paths）：以仓库根为基准解析每个条目的path，文件不存在即失败；
• schema（verify_schemas）：用jsonschema把两份 YAML 分别对照各自的 JSON schema 验证，未安装 jsonschema 时跳过。

任一检查失败时脚本以sys.exit(1)退出，从而让 CI 步骤判红。本地可先跑python .github/scripts/verify_registry.py schema或paths这类离线子命令快速自检，联网核验（authors）视网络环境执行。

5.3 CI 触发与作者排序检查

.github/workflows/verify-authors.yml 规定：只要 PR 或 main 分支的推送触碰authors.yaml或registry.yaml，即在 ubuntu-latest 上安装pyyaml requests jsonschema并运行python .github/scripts/verify_registry.py（默认all模式，含全部联网核验）。

另一条容易被忽略的约束来自 scripts/validate_authors_sorted.py：它校验 authors.yaml 的 key 必须按case-insensitive 字母序排列（is_sorted 用sorted(keys, key=str.lower)比较），--fix模式会自动重排并保留文件头注释块 HEADER。这意味着/add-registry为新作者写入 authors.yaml 时，应把条目插在正确的位置（对照现有 key 的排序），而不是简单追加到文件末尾——命令文档对 registry 的“按 path 字母序或末尾追加”并不等价地适用于 authors 排序。

六、实操路径总结

结合命令文档与仓库校验链，为 claude-cookbooks 新增一个 notebook 元数据条目的完整闭环是：

1. 在 Claude Code 中运行/add-registry，并在 prompt 中给出 notebook 路径（如capabilities/new_topic/guide.ipynb）；
2. Agent 读取 notebook → 询问你的 GitHub 用户名 → 检查 authors.yaml；若是新作者，按name/website/avatar三字段展示拟议条目，等你批准；
3. Agent 展示拟议的 registry 条目（title、15–20 词 description、相对根路径、authors、YYYY-MM-DD日期、1–2 个分类），按 path 字母序给出插入建议；
4. 你确认后 Agent 用Edit追加；
5. 本地自检：python .github/scripts/validate_authors_sorted.py（或加--fix）与python .github/scripts/verify_registry.py schema paths；
6. 推送后由 verify-authors.yml 工作流做最终的全量核验。

这套“命令固化工具人流程 + schema 定义约束 + 脚本执行核验 + CI 触发兜底”的分层设计，是 claude-cookbooks 维持大规模 notebook 元数据一致性的核心机制；对任何以 YAML 注册表驱动内容站点的仓库，同样可以直接借鉴。

【免费下载链接】claude-cookbooksA collection of notebooks/recipes showcasing some fun and effective ways of using Claude.项目地址: https://gitcode.com/GitHub_Trending/an/claude-cookbooks