waynesutton/builder-skills

概览

builder-skills 是一套代理技能 (agent skills)，旨在协助 AI 代码助手（如 Claude、Codex、Cursor、OpenCode 等）在 Convex（一个无服务器后端平台）上构建应用程序时，遵循最佳实践规范。该仓库提供了 17 个小型、独立的“SKILL.md”文件——每个文件都是一份决策指南、示例、检查清单与参考资料——供 LLM 按需加载。它们涵盖了 Convex 特有的关注点（验证器、索引、迁移、安全检查）以及一般的项目管理习惯（撰写 PRD、维护任务/变更日志/文件文档、防止破坏性的 git 指令）。

该包可通过通用的 skills.sh 安装程序、Claude Code 插件或直接从 npm 安装。安装后，一组入门 Markdown 文件（AGENTS.md、task.md、changelog.md 等）会被加入用户的仓库中，为代理提供一个结构化的工作区，以追踪工作并保持文档与代码同步。

---

主要功能

功能	作用	重要性
17 个即用技能	每个技能都是一个 SKILL.md (≤300 行)，包含描述、触发条件、示例代码与选用的参考文件。	为 LLM 代理提供具体、经过验证的指导，避免违反 Convex 规范或破坏仓库。
专注于 Convex 的技能	验证器、索引、幂等变更 (idempotent mutations)、HTTP 动作、迁移、安全检查等。	确保生成的代码符合 Convex 的最佳实践，并避免运行时错误。
项目工作流程技能	project-workflow、project-docs、git-safety、avoid-feature-creep。	强制执行严谨的开发循环：PRD → 任务追踪 → 自动文档更新 → 安全的 git 使用。
多代理安装	支持 Claude、Codex、Cursor、通用代理，或通过 npm CLI 支持任何自定义文件夹。	让团队使用其偏好的 LLM 助手，而无需重写技能。
模板引导	install-templates 会部署入门 Markdown 文件 (AGENTS.md、task.md、changelog.md、files.md、prds/lessons.md)。	提供一个现成的“知识库”，让代理在对话期间可以读取/写入。
程序化 API	从 npm 包导出的 listSkills、getSkillMeta、getSkill。	让工具或自定义脚本能够查询或加载技能的原始 Markdown。
安全护栏	git-safety 会封锁破坏性的 git 指令，除非经过明确批准。	防止 LLM 尝试执行危险指令时意外丢失工作成果。

---

典型使用流程

1. 安装技能集 (例如 npx skills add waynesutton/builder-skills)。
2. 执行 npx @waynesutton/builder-skills install-templates – 仓库现在包含五个文档文件与可编辑的技能存根。
3. 要求代理进行变更。代理首先会在 prds/ 中创建 PRD，在 task.md 中新增任务条目，然后使用适当的 Convex 技能（例如 convex-functions）来生成代码。
4. 变更完成后，执行 project-docs 技能。它会读取 git log 与工作树，自动更新 changelog.md、files.md 与 task.md，并扫描机密信息。
5. 使用技能打印的提交信息来提交变更。

此循环重复进行，在保护免受常见陷阱的同时，保持代码、文档与项目追踪的同步。

---

安装选项

方法	运作方式	使用时机
skills.sh (npx skills add …)	交互式安装程序将纯文本文件写入您的仓库；后续使用 npx skills update 更新。	若您希望拥有可编辑的文件以及简单、与代理无关的设置，则优先选择此方式。
Claude Code 插件 (claude plugins …)	在 Claude 的市场中注册技能；Claude 会自动管理更新。	若您主要使用 Claude Code 且希望实现自动化更新。
npm CLI (npx @waynesutton/builder-skills install-all …)	将技能文件复制或符号链接到目标文件夹 (.claude/skills, .codex/skills 等)。	用于自定义代理或当您需要在特定目录中使用技能时。

---

谁适合使用

• 构建 Convex 后端的开发者，希望 AI 助手能尊重 Convex 的 API 合约。
• 使用 LLM 代码助手 (Claude, Codex, Cursor, OpenCode) 且需要一套共享、可强制执行规则的团队。
• 项目经理，希望自动化 PRD/任务追踪与文档同步。
• 开源贡献者，寻求一种可重现的工作流程，以防止意外的 git 数据丢失。

---

限制 / 未决问题

• 这些技能对作者的工作流程有主观偏好；可能需要针对不同团队的惯例进行调整。
• 它们依赖于主机 LLM 能够读取 SKILL.md 文件；不支持此格式的代理将需要一个封装器。
• 没有内置测试或 CI 集成 – 技能会生成代码，但您仍需要自己的测试套件。

---

快速开始 (CLI)

# 全局或在项目中安装包
npm i -D @waynesutton/builder-skills

# 为 Claude (默认) 安装所有技能并部署入门模板
npx @waynesutton/builder-skills install-all
npx @waynesutton/builder-skills install-templates

现在您已拥有 Markdown 架构与准备好供 LLM 助手使用的技能文件。

---

授权

Apache-2.0 – 可免费进行商业与非商业用途。