phrazzld/spellbook
GitHub: phrazzld/spellbook
一个为多种 AI 编码助手提供可移植技能模块的清单驱动型分发框架，支持跨仓库语义搜索与多模型复用。
Stars: 5 | Forks: 0
# Spellbook
适用于多模型 AI harness 的可移植 Agent 原语（skills + agents）库。支持 Claude Code、Codex、Gemini、Factory 和 Pi。
Markdown 优先。无应用程序代码，无依赖。原语教导 agents *如何工作*：调试、PR 工作流、设计系统、事件响应以及特定领域的 Playbook。
## 快速开始
```
# Bootstrap (每台机器执行一次)
curl -sL https://raw.githubusercontent.com/phrazzld/spellbook/master/bootstrap.sh | bash
```
这将安装两个全局 skills：`/focus`（原语管理器）和 `/research`（多源网络研究）。其他所有内容都是项目本地的。
```
# 在任意项目中：
/focus init # Analyze project, generate .spellbook.yaml
/focus # Pull declared primitives from GitHub
/focus add stripe # Add a skill to manifest
/focus search "webhook handler" # Semantic search across all sources
```
## 工作原理
项目在 `.spellbook.yaml` 中声明所需内容：
```
skills:
- debug
- autopilot
- anthropics/skills@frontend-design # external source
agents:
- ousterhout
- grug
```
`/focus` 读取清单，从 GitHub 拉取原语，并将它们安装到项目的本地 harness 目录（`.claude/skills/`、`.claude/agents/`）。被管理的原语通过 `.spellbook` 文件进行标记 —— 没有标记的项目本地原语永远不会被触碰。
### 多源发现
Spellbook 使用 Gemini Embedding 2 对来自多个 GitHub 仓库的 skills 进行索引以实现语义搜索。当你运行 `/focus init` 或 `/focus search` 时，它会根据项目上下文或查询匹配完整的索引。
非限定名称（`debug`）解析为 `phrazzld/spellbook`。外部 skills 使用完全限定名称（`owner/repo@skill-name`）以避免冲突。
请参阅 `embeddings.json` 以获取预计算的索引，以及 `scripts/generate-embeddings.py` 以了解生成器。
## 仓库结构
```
spellbook/
├── skills/ # All skills, flat
├── agents/ # Agent definitions, flat
├── embeddings.json # Pre-computed semantic search index
├── index.yaml # Generated text catalog
├── collections.yaml # Named skill groups (human browsing)
├── bootstrap.sh # One-command global install
└── scripts/
├── generate-index.sh
├── generate-embeddings.py
└── search-embeddings.py
```
## 添加 Skill
1. 使用 frontmatter 创建 `skills/{name}/SKILL.md`
2. 根据需要添加 `references/`、`scripts/`、`assets/`
3. 运行 `./scripts/generate-index.sh && python3 scripts/generate-embeddings.py`
4. 提交并推送 —— 消费者将在下次 `/focus` 时获取
## 原则
- **扁平优于嵌套** —— 每个 skill 都位于 `skills/{name}/`
- **清单驱动** —— 项目声明需求，`/focus` 负责交付
- **与 Harness 无关** —— 适用于 Claude Code、Codex、Pi、Factory、Gemini
- **销毁并重建** —— `/focus` 在每次同步时删除并重新创建被管理的原语
- **基于 Embedding 的发现** —— 语义搜索，而非关键词匹配
- **多源** —— 索引来自任何 GitHub 仓库的 skills，不仅限于此仓库
- **始终项目本地** —— `/focus` 安装到项目目录，从不全局安装
## 许可证
MIT
标签：AI代理, Claude, Codex, Cutter, CVE检测, DLL 劫持, Gemini, Git, LLM, Markdown, Playbooks, PR工作流, RAG, SRE, Unmanaged PE, 人工智能, 代码生成, 偏差过滤, 大语言模型, 威胁情报, 嵌入式向量, 工作流自动化, 开发者工具, 技能库, 提示词工程, 无依赖, 渗透测试工具, 用户模式Hook绕过, 知识管理, 策略决策点, 网络安全研究, 脚手架, 设计系统, 语义搜索, 调试, 逆向工具, 防御加固