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.yamlcookbook 元数据注册表每个条目记录一个 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 - Toolsauthors.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?v4之所以值得用一条斜杠命令来维护是因为这两个文件受到严格的双重约束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 中两项声明都值得注意description一句话说明命令用途“Add a new notebook to registry.yaml”它会在 Claude Code 的命令列表中作为提示文本展示。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.yamlCheck author existsinauthors.yaml具体规则向用户询问 notebook 作者的 GitHub username读取 authors.yaml 检查该 username 是否已作为 key 存在若不存在向用户收集信息并新增作者条目字段为name完整展示名websiteGitHub 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 条目命令为条目字段给出了完整规格。必需字段字段取值规则title从 notebook 首个 heading 提取或撰写一个简洁、有描述性的标题description1–2 句话概括该 notebook 教会什么path相对仓库根目录的 notebook 路径authors步骤 2 中确认的 GitHub usernamedate当天日期YYYY-MM-DD格式categories从下列列表中选 1–2 个Agent Patterns、Claude Agent SDK、Cybersecurity、Evals、Fine-Tuning、Multimodal、Integrations、Observability、RAG Retrieval、Responses、Skills、Thinking、Tools关于 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 GuidelinesTitle简洁但有描述性可参照既有条目风格Description约 15–20 词聚焦“用户将学到/构建什么”Categories选择最贴合 notebook 主要聚类的分类。命令文档还直接给出两种条目的标准格式authors.yaml仅新作者时github-username: name: Full Name website: https://github.com/github-username avatar: https://github.com/github-username.pngregistry.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闸门若作者为新作者先展示拟定的authors.yaml条目供审阅获批后追加展示拟定的registry.yaml条目供审阅用户批准后才使用Edit工具把条目追加进registry.yaml条目在文件内按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、difficultybeginner/intermediate/advanced/空串、use_case、thumbnail、archiveddate正则^\d{4}-\d{2}-\d{2}$与命令中“YYYY-MM-DD”要求一致categories枚举15 个分类值、minItems: 1即“1–2 个分类”的下限约束authorsminItems: 1注释明确 “GitHub username (must match keys in authors.yml)”。.github/authors_schema.json 则约束 authors.yamlkey 必须匹配^[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对应四类检查authorscheck_github_handle对 authors.yaml 中每个 key 发 HEAD 请求确认 GitHub profile 存在404 即失败并核验 website/avatar URL 可访问其中对x.com域名做了跳过处理因为该站屏蔽 HEAD 请求registryverify_registry_authors收集 registry.yaml 全部作者的并集逐一确认其在 authors.yaml 中有定义——这正是/add-registry步骤 2 的自动化复核pathsverify_paths以仓库根为基准解析每个条目的path文件不存在即失败schemaverify_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, keystr.lower)比较--fix模式会自动重排并保留文件头注释块 HEADER。这意味着/add-registry为新作者写入 authors.yaml 时应把条目插在正确的位置对照现有 key 的排序而不是简单追加到文件末尾——命令文档对 registry 的“按 path 字母序或末尾追加”并不等价地适用于 authors 排序。六、实操路径总结结合命令文档与仓库校验链为 claude-cookbooks 新增一个 notebook 元数据条目的完整闭环是在 Claude Code 中运行/add-registry并在 prompt 中给出 notebook 路径如capabilities/new_topic/guide.ipynbAgent 读取 notebook → 询问你的 GitHub 用户名 → 检查 authors.yaml若是新作者按name/website/avatar三字段展示拟议条目等你批准Agent 展示拟议的 registry 条目title、15–20 词 description、相对根路径、authors、YYYY-MM-DD日期、1–2 个分类按 path 字母序给出插入建议你确认后 Agent 用Edit追加本地自检python .github/scripts/validate_authors_sorted.py或加--fix与python .github/scripts/verify_registry.py schema paths推送后由 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 claude-cookbooks 中的 /add-registry 斜杠命令：自动化维护 registry.yaml 元数据注册表
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.yamlcookbook 元数据注册表每个条目记录一个 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 - Toolsauthors.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?v4之所以值得用一条斜杠命令来维护是因为这两个文件受到严格的双重约束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 中两项声明都值得注意description一句话说明命令用途“Add a new notebook to registry.yaml”它会在 Claude Code 的命令列表中作为提示文本展示。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.yamlCheck author existsinauthors.yaml具体规则向用户询问 notebook 作者的 GitHub username读取 authors.yaml 检查该 username 是否已作为 key 存在若不存在向用户收集信息并新增作者条目字段为name完整展示名websiteGitHub 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 条目命令为条目字段给出了完整规格。必需字段字段取值规则title从 notebook 首个 heading 提取或撰写一个简洁、有描述性的标题description1–2 句话概括该 notebook 教会什么path相对仓库根目录的 notebook 路径authors步骤 2 中确认的 GitHub usernamedate当天日期YYYY-MM-DD格式categories从下列列表中选 1–2 个Agent Patterns、Claude Agent SDK、Cybersecurity、Evals、Fine-Tuning、Multimodal、Integrations、Observability、RAG Retrieval、Responses、Skills、Thinking、Tools关于 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 GuidelinesTitle简洁但有描述性可参照既有条目风格Description约 15–20 词聚焦“用户将学到/构建什么”Categories选择最贴合 notebook 主要聚类的分类。命令文档还直接给出两种条目的标准格式authors.yaml仅新作者时github-username: name: Full Name website: https://github.com/github-username avatar: https://github.com/github-username.pngregistry.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闸门若作者为新作者先展示拟定的authors.yaml条目供审阅获批后追加展示拟定的registry.yaml条目供审阅用户批准后才使用Edit工具把条目追加进registry.yaml条目在文件内按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、difficultybeginner/intermediate/advanced/空串、use_case、thumbnail、archiveddate正则^\d{4}-\d{2}-\d{2}$与命令中“YYYY-MM-DD”要求一致categories枚举15 个分类值、minItems: 1即“1–2 个分类”的下限约束authorsminItems: 1注释明确 “GitHub username (must match keys in authors.yml)”。.github/authors_schema.json 则约束 authors.yamlkey 必须匹配^[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对应四类检查authorscheck_github_handle对 authors.yaml 中每个 key 发 HEAD 请求确认 GitHub profile 存在404 即失败并核验 website/avatar URL 可访问其中对x.com域名做了跳过处理因为该站屏蔽 HEAD 请求registryverify_registry_authors收集 registry.yaml 全部作者的并集逐一确认其在 authors.yaml 中有定义——这正是/add-registry步骤 2 的自动化复核pathsverify_paths以仓库根为基准解析每个条目的path文件不存在即失败schemaverify_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, keystr.lower)比较--fix模式会自动重排并保留文件头注释块 HEADER。这意味着/add-registry为新作者写入 authors.yaml 时应把条目插在正确的位置对照现有 key 的排序而不是简单追加到文件末尾——命令文档对 registry 的“按 path 字母序或末尾追加”并不等价地适用于 authors 排序。六、实操路径总结结合命令文档与仓库校验链为 claude-cookbooks 新增一个 notebook 元数据条目的完整闭环是在 Claude Code 中运行/add-registry并在 prompt 中给出 notebook 路径如capabilities/new_topic/guide.ipynbAgent 读取 notebook → 询问你的 GitHub 用户名 → 检查 authors.yaml若是新作者按name/website/avatar三字段展示拟议条目等你批准Agent 展示拟议的 registry 条目title、15–20 词 description、相对根路径、authors、YYYY-MM-DD日期、1–2 个分类按 path 字母序给出插入建议你确认后 Agent 用Edit追加本地自检python .github/scripts/validate_authors_sorted.py或加--fix与python .github/scripts/verify_registry.py schema paths推送后由 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考