Spellbook：跨运行时的 Claude Code 与 Codex 技能库

Spellbook 是一个为 Claude Code、Codex 和多智能体工作流设计的跨运行时技能库，提供可复用的技能模板、工作流定义和插件系统，让 AI 编程助手的能力可以在不同环境中无缝迁移。

• 原作者/维护者：majiayu000
• 来源平台：github
• 原始标题：spellbook
• 原始链接：https://github.com/majiayu000/spellbook
• 来源发布时间/更新时间：2026-06-12T19:15:42Z

|------|-----------|-----------------|-------------|--------------|\n| 跨运行时 | ✅ 核心目标 | ❌ Claude 专属 | ❌ Codex 专属 | ❌ Devin 专属 |\n| 技能复用 | ✅ 标准化格式 | ⚠️ 协议级 | ⚠️ API 级 | ❌ 封闭 | | 开源 | ✅ | ✅ | ❌ | ❌ |\n| 社区生态 | 建设中 | 活跃 | 受限 | 无 |\n| 工作流编排 | ✅ | 基础 | 基础 | 内置 | | 自托管 | ✅ | ✅ | ❌ | ❌ |\n\nSpellbook 的独特定位是「跨运行时的技能交换格式」。它不试图取代 MCP 或 Codex Agent，而是在它们之上提供互操作层。\n\n## 技术实现细节\n\n### 依赖管理\n\n技能可以声明依赖其他技能，Spellbook 会自动解析依赖树并确保正确加载顺序。\n\n### 版本控制\n\n技能和工作流都有版本号，支持语义化版本控制。项目可以锁定特定版本，确保行为稳定性。\n\n### 沙箱执行\n\n敏感操作（如执行命令）在沙箱环境中运行，限制文件系统访问和网络权限，防止恶意技能造成损害。\n\n### 缓存机制\n\n重复执行的技能结果会被缓存，避免不必要的计算。缓存可以配置 TTL 和失效策略。\n\n## 未来展望\n\nSpellbook 项目展现了 AI 编程工具互操作性的重要方向。未来可能的发展包括：\n\n- 更多运行时支持：Cursor、Windsurf、Continue 等\n- 技能市场：社区贡献的技能仓库\n- 可视化编辑器：图形化工作流设计\n- IDE 集成：VS Code、JetBrains 插件\n- 企业功能：私有技能仓库、审计日志、权限管理\n- AI 生成技能：用自然语言描述需求，自动生成技能定义\n\n## 总结\n\nSpellbook 是 AI 辅助编程领域的一个前瞻性项目。它直面当前工具碎片化的问题，试图通过标准化技能格式和跨运行时适配，让开发者真正拥有「一次编写，处处运行」的能力。\n\n对于同时使用多种 AI 编程工具的开发者，Spellbook 提供了宝贵的技能复用机制。对于团队而言，它是统一开发规范和最佳实践的有效工具。对于整个生态，Spellbook 可能成为连接不同平台的桥梁，促进更开放、更互通的 AI 编程未来。\n\n项目的开源性质和清晰的架构设计，使其成为研究 AI 工具互操作性的优秀参考案例。随着 AI 编程助手的普及，这类跨平台技能框架将会越来越重要。

原作者与来源

• 原作者/维护者：majiayu000
• 来源平台：github
• 原始标题：spellbook
• 原始链接：https://github.com/majiayu000/spellbook
• 来源发布时间/更新时间：2026-06-12T19:15:42Z 原作者与来源\n\n- 原作者/维护者：majiayu000\n- 来源平台：GitHub\n- 原始标题：spellbook\n- 原始链接：https://github.com/majiayu000/spellbook\n- 来源发布时间/更新时间：2026-06-12T19:15:42Z\n\n背景：AI 编程助手的碎片化困境\n\n2024-2025 年，AI 辅助编程工具迎来爆发式增长。Claude Code、GitHub Copilot、Codex、Cursor、Windsurf 等产品相继推出，各自拥有独特的交互方式和扩展机制。\n\n然而，这种繁荣背后隐藏着碎片化的问题：\n\n- 技能无法复用：为 Claude Code 编写的技能无法在 Codex 中使用\n- 工作流割裂：不同工具的代理模式和工作流定义互不兼容\n- 学习成本倍增：开发者需要为每个工具学习不同的扩展方式\n- 生态孤岛：每个平台都有自己的插件市场，资源分散\n\n对于追求效率的开发者来说，这种碎片化意味着重复投入。一个常见的场景是：团队已经用 Claude Code 构建了一套代码审查工作流，但当切换到 Codex 时，所有配置都需要重写。\n\nSpellbook 项目概览\n\nSpellbook 是 majiayu000 发起的开源项目，目标是创建一个「跨运行时的技能库」。它提供了一套标准化的技能定义格式，让同样的自动化能力可以在 Claude Code、Codex 乃至其他多智能体环境中运行。\n\n核心理念\n\nWrite once, run anywhere（一次编写，处处运行）\n\n这个口号可能让人联想到 Java，但 Spellbook 的实现方式完全不同。它不是创建一个新的运行时，而是为现有的 AI 编程工具提供统一的技能抽象层。\n\n项目结构解析\n\n从仓库结构可以看出 Spellbook 的架构设计：\n\n\nspellbook/\n├── agents/ 智能体定义\n├── claude-md/ Claude Code 特定配置\n├── codex/ Codex 特定配置\n├── commands/ 通用命令定义\n├── docs/ 文档\n├── hooks/ 生命周期钩子\n├── learn/ 学习资源和示例\n├── plugins/ 插件目录\n│ └── rust-dev/ Rust 开发插件示例\n├── registry/ 技能注册表\n├── scripts/ 辅助脚本\n├── skills/ 核心技能库\n├── tests/ 测试用例\n└── workflows/ 工作流定义\n\n\n关键目录说明\n\nskills/\n\n这是项目的核心，包含各种可复用的技能定义。每个技能都是一个独立的单元，描述如何完成特定任务（如代码审查、重构、测试生成等）。\n\nworkflows/\n\n工作流定义将多个技能组合成完整的自动化流程。例如，「代码提交前检查」工作流可能包含格式化、静态分析、测试运行等多个步骤。\n\nagents/\n\n智能体定义描述 AI 助手的角色和行为模式。不同的智能体可以专注于不同领域（如前端专家、DevOps 工程师、技术写手）。\n\nclaude-md/ 和 codex/\n\n这两个目录包含针对特定运行时的适配配置。Spellbook 的核心技能是平台无关的，但每个运行时可能有特定的调用方式或环境要求，这些目录存放相应的映射规则。\n\nregistry/\n\n技能注册表管理技能的发现和加载。它定义了技能的元数据格式、版本管理规则和依赖解析机制。\n\n技能定义格式\n\nSpellbook 设计了一套声明式的技能定义格式，示例如下：\n\nyaml\nskills/code-review.yaml\nskill:\n name: code-review\n version: 1.0.0\n description: 自动代码审查，检查常见问题和最佳实践\n \n runtime:\n claude-code:\n entry: review_with_claude\n context: file-diff\n codex:\n entry: review_with_codex\n context: git-diff\n \n steps:\n - name: analyze-diff\n action: parse_git_diff\n output: changed_files\n \n - name: check-style\n action: lint\n input: changed_files\n config: .lintrc\n \n - name: ai-review\n action: llm_analyze\n prompt: prompts/code-review.txt\n context:\n - changed_files\n - project_guidelines\n \n outputs:\n - review_comments\n - severity_score\n - suggestions\n\n\n这种格式的特点是：\n\n- 运行时无关：核心逻辑不绑定特定工具\n- 步骤化：清晰定义执行流程\n- 可配置：支持参数化和环境适配\n- 输出标准化：统一的结果格式便于后续处理\n\n跨运行时适配机制\n\nSpellbook 如何实现「一次编写，处处运行」？关键在于抽象层和适配器模式。\n\n抽象层设计\n\n项目定义了一套通用的能力接口：\n\n- FileSystem：文件读写、路径操作\n- Process：命令执行、进程管理\n- Git：版本控制操作\n- LSP：语言服务器协议交互\n- LLM：大语言模型调用\n- UI：用户交互（输入/输出）\n\n技能定义使用这些抽象接口，而非直接调用特定工具的 API。\n\n运行时适配器\n\n每个支持的目标运行时都有对应的适配器实现：\n\nClaude Code 适配器\n\n将通用接口映射到 Claude Code 的 MCP（Model Context Protocol）工具：\n- FileSystem → @read-file, @write-file\n- Process → @execute-command\n- Git → @git-diff, @git-commit\n\nCodex 适配器\n\n映射到 Codex 的 Agent 模式 API：\n- FileSystem → codex.fs.read(), codex.fs.write()\n- Process → codex.exec()\n- Git → codex.git.\n\n*通用 Shell 适配器\n\n对于不支持特定扩展机制的环境，提供纯 Shell 脚本实现，确保技能可以在任何命令行环境中运行。\n\n技能生态系统\n\nSpellbook 内置了丰富的技能库，涵盖软件开发的各个环节：\n\n代码质量\n\n- lint：多语言静态分析\n- format：代码格式化\n- type-check：类型检查\n- security-scan：安全漏洞扫描\n- complexity-analysis：复杂度分析\n\n测试\n\n- test-run：执行测试套件\n- test-generate：基于代码生成测试\n- coverage-report：覆盖率报告\n- mutation-test：变异测试\n\n文档\n\n- doc-generate：自动生成文档\n- readme-update：更新 README\n- api-doc：API 文档生成\n- changelog：变更日志维护\n\n部署\n\n- docker-build：Docker 镜像构建\n- k8s-validate：Kubernetes 配置验证\n- terraform-plan：基础设施变更预览\n\n协作\n\n- pr-review：Pull Request 审查\n- issue-triage：Issue 分类\n- commit-message：提交信息生成\n\n工作流编排\n\n技能可以组合成复杂的工作流。Spellbook 提供了类似 GitHub Actions 的 YAML 工作流定义：\n\nyaml\nworkflows/pre-commit.yaml\nname: Pre-commit Checks\ntrigger: git pre-commit\n\njobs:\n check:\n steps:\n - uses: skills/format\n with:\n fail_on_change: true\n \n - uses: skills/lint\n with:\n severity: error\n \n - uses: skills/type-check\n \n - uses: skills/test-run\n with:\n pattern: \"**/*.test.ts\"\n \n - uses: skills/security-scan\n if: branch == 'main'\n\n\n这种设计让团队可以将最佳实践编码为可复用的工作流，确保每个成员都遵循相同的质量标准。\n\n插件系统\n\nSpellbook 支持插件扩展，允许社区贡献新的技能和适配器。插件目录 plugins/rust-dev 展示了如何为特定技术栈创建扩展：\n\n\nplugins/rust-dev/\n├── skills/\n│ ├── cargo-check.yaml\n│ ├── clippy-review.yaml\n│ └── rustfmt.yaml\n├── prompts/\n│ └── rust-specific.txt\n└── manifest.yaml\n\n\n插件可以：\n- 添加新的技能定义\n- 提供运行时特定的优化\n- 包含领域特定的提示词模板\n- 定义自定义的抽象接口\n\n使用场景\n\n团队标准化\n\n技术团队可以使用 Spellbook 统一开发规范：\n\n1. 定义团队的代码审查标准\n2. 配置统一的格式化规则\n3. 设置提交前的强制检查\n4. 共享最佳实践工作流\n\n所有成员无论使用 Claude Code 还是 Codex，都能获得一致的辅助体验。\n\nCI/CD 集成\n\nSpellbook 的工作流可以直接在 CI 环境中运行：\n\nyaml\n.github/workflows/ci.yaml\nname: CI\non: [push]\njobs:\n spellbook:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: majiayu000/spellbook-action@v1\n with:\n workflow: ci-checks\n\n\n这让本地开发和 CI 检查使用完全相同的逻辑，避免「在我机器上能跑」的问题。\n\n多工具迁移\n\n当团队需要从一个 AI 工具迁移到另一个时，Spellbook 可以大幅降低迁移成本：\n\n1. 导出现有的技能和工作流定义\n2. 切换目标运行时适配器\n3. 微调平台特定的配置\n4. 验证功能一致性\n\n核心逻辑无需重写，只需处理适配层差异。\n\n与同类项目的对比\n\n| 特性 | Spellbook | MCP (Anthropic) | Codex Agent | Devin Skills |