AI编程技能库：用Scribe构建可复用的智能开发工作流

1. 项目概述：一个为AI编程工具量身打造的技能库

如果你和我一样，日常重度依赖 Claude Code、Cursor 这类AI驱动的编程工具，那你一定有过这样的体验：每次开启一个新项目，或者面对一个特定的任务（比如配置一个复杂的开发环境，或者写一个特定框架的单元测试），你都需要花时间向AI助手解释你的需求、你偏好的代码风格、甚至是一些重复性的操作步骤。这个过程本身就在消耗“让AI提升效率”所带来的增益。

Naoray/skills 这个项目，就是为了终结这种低效循环而生的。它本质上是一个个人化的、可共享的AI技能库。你可以把它理解为一个超级工具箱，里面装满了针对不同编程场景优化过的“操作指南”或“最佳实践模版”。这些“技能”不是简单的代码片段，而是包含了完整上下文、预设指令和行动逻辑的“智能配方”，能够直接被你常用的AI编程工具（如Claude Code, Cursor, Codex）理解和执行。

这个项目的核心价值在于“标准化”和“复用”。通过scribe这个命令行工具，你可以轻松地将这些技能连接到你的本地环境。一旦连接，AI助手就能直接调用这些预设的技能，省去大量前期沟通和调试成本。比如，项目中可能包含一个“初始化Next.js项目并配置Tailwind CSS和TypeScript”的技能，当你需要创建这样一个项目时，无需再向AI描述每一步细节，直接触发该技能，AI就能基于这个成熟的配方高效完成任务。

2. 核心思路与工具链解析：为什么是Scribe与技能库？

在深入实操之前，我们有必要拆解一下这个方案背后的设计哲学。市面上有很多管理代码片段或脚本的工具，那为什么Naoray/skills选择了“技能（Skills）”这个概念，并依赖scribe来实现？这背后是对AI辅助编程工作流的一次深刻优化。

2.1 从代码片段到可执行技能：思维的跃迁

传统的代码片段库（如VS Code的Snippets）解决的是“代码块”的复用问题。但它们缺乏上下文和意图。一个片段告诉你“如何写一个React组件”，但它不会告诉AI“现在应该创建一个表单组件，并且需要包含验证逻辑和提交状态”。

“技能”则更进一步。它是一组结构化、目标明确的指令集合，通常包含：

• 目标描述：这个技能要完成什么任务？（例如：“为一个Python Flask API设置完整的测试环境”）
• 上下文预设：执行这个技能需要什么前提？（例如：当前目录是一个Flask项目，已安装pytest）
• 行动步骤：AI应该按什么顺序、以什么方式执行任务？（例如：1. 创建tests/目录；2. 编写conftest.py设置测试客户端；3. 为现有路由生成测试用例骨架）
• 偏好设置：用户个人的代码风格、工具选择是什么？（例如：使用pytest-mock而非unittest.mock，断言消息的格式等）

通过scribe，这些技能被格式化成AI工具可以直接解析和执行的“食谱”。AI不再是凭空生成代码，而是扮演一个“熟练的执行厨师”，按照既定的、经过验证的菜谱操作，结果自然更可控、更符合预期。

2.2 Scribe：技能生态的粘合剂与路由器

Scribe在这里扮演了核心基础设施的角色。它的设计非常巧妙，主要解决了三个问题：

1. 技能的分发与同步：Scribe通过连接GitHub仓库（如Naoray/skills）作为技能注册表（Registry）。这意味着技能库的维护者（Naoray）可以持续更新他的最佳实践，而用户只需一条scribe sync命令就能获取所有更新，无需手动复制粘贴。
2. 技能的本地化与注入：Scribe并非将技能硬编码到某个特定IDE。它采用了一种“链接”机制。技能被存储在统一的本地目录（~/.scribe/skills/），然后scribe会智能地将其“注入”或“链接”到你已安装的、它支持的AI工具（Claude Code, Cursor等）的上下文中。这实现了一次安装，多端可用。
3. 使用的便捷与安全：Scribe提供了browse（浏览）、add（安装）、list（列表）等清晰的CLI命令。更重要的是，它的默认操作模式是“选择加入”（Opt-in）。你可以浏览整个技能目录，只安装你需要的部分，并且sync命令只会更新已安装的技能，不会擅自添加新内容，给予了用户充分的控制权。

这种架构使得个人或团队可以构建自己的私有技能库，形成高度定制化、不断进化的AI辅助知识体系。

3. 从零开始：完整配置与接入指南

理解了背后的理念，我们现在进入实战环节。我将以一个新用户的视角，带你完整走一遍从环境准备到技能安装的全过程。请打开你的终端，我们一步步来。

3.1 前期准备：环境检查与Scribe安装

在连接任何技能库之前，我们必须确保核心工具scribe已就位并能正常工作。

第一步：检查Node.js与npmScribe是一个Node.js命令行工具，因此你需要先确保系统已安装Node.js环境。在终端中执行：

node --version npm --version

如果能看到版本号（例如v18.x.x和9.x.x），说明环境已就绪。如果未安装，请前往Node.js官网下载并安装LTS（长期支持）版本。

第二步：安装Scribe通过npm全局安装scribe：

npm install -g @naoray/scribe

安装完成后，验证安装是否成功：

scribe --version

如果成功显示版本号（如0.9.0-beta.1），恭喜你，核心工具已安装完毕。

注意：有时全局安装可能会遇到权限问题（尤其在Linux或macOS上）。如果报错，可以尝试使用sudo npm install -g @naoray/scribe，或者更推荐的方式是使用Node版本管理器（如nvm）来管理你的Node环境，这样可以避免使用sudo。

第三步：配置GitHub身份验证（关键步骤）Scribe需要通过GitHub CLI (gh) 来安全地读取远程的技能库（Registry）。因此，你需要确保gh已安装且已完成登录认证。

1. 安装GitHub CLI：
   • macOS:brew install gh
   • Linux: 请参照GitHub官方文档，通常可以通过包管理器安装，如Ubuntu的sudo apt install gh。
   • Windows: 可通过Winget (winget install --id GitHub.cli) 或从GitHub releases页面下载安装包。
2. 进行身份认证：在终端运行gh auth login。按照提示操作：
   • 选择GitHub.com。
   • 选择HTTPS协议（推荐）。
   • 当询问“Authenticate Git with your GitHub credentials?”时，选择Y。
   • 选择登录方式，通常选择“通过浏览器登录”最为方便。终端会生成一个一次性代码并尝试打开浏览器让你授权。
3. 验证认证状态：运行gh auth status。如果看到Logged in to github.com as <你的用户名>的提示，说明配置成功。

实操心得：这一步是后续所有操作的基础，也是最容易卡住的地方。如果gh auth login过程失败，常见原因有：1) 代理网络问题，请检查你的网络连接；2) 浏览器未正常弹出，可以尝试手动复制终端给出的验证链接到浏览器中打开。确保认证成功是重中之重。

3.2 连接技能库：两种路径的抉择

环境准备好后，我们就可以连接Naoray的技能库了。这里提供了两种路径，对应着不同的使用哲学。

路径一：手动连接与精选安装（推荐给大多数用户）这是默认的、也是我比较推荐的“选择加入”模式。你首先连接仓库，然后像逛超市一样浏览所有技能，只把需要的放进购物车。

1. 连接注册表：执行以下命令，告诉scribe你想要使用Naoray/skills这个远程技能库。

   scribe registry connect Naoray/skills

   这个命令执行速度很快，它只是在本地建立了一个指向该仓库的索引，不会下载任何技能内容。

2. 浏览技能目录：现在，让我们看看这个“超市”里都有什么好东西。

   scribe browse --registry Naoray/skills

   终端会输出一个清晰的列表，展示所有可用的技能。每个技能通常会有一个简短的名称和一句描述。例如，你可能会看到诸如init-nextjs-ts-tailwind、setup-python-poetry、add-auth-middleware之类的技能名。这时，你可以根据自己当前的项目需求，记下你感兴趣的技能名称。

路径二：一键安装整个目录（适合追求全面或深度探索的用户）如果你信任该技能库的维护质量，并且希望一次性获得所有能力，可以使用“全家桶”安装模式。请注意，这需要scribe的版本在v0.9.0-beta.1或更高。

scribe registry connect Naoray/skills --install-all

这条命令合并了“连接”和“安装”两个步骤，会将该注册表中的所有技能一次性下载并链接到你的本地环境。

注意事项：虽然一键安装很方便，但我个人更倾向于第一种“精选”模式。原因有三：第一，技能库可能包含一些你永远用不到的技能（例如针对你未使用的特定框架），全部安装会占用不必要的磁盘空间（虽然很小）。第二，技能库在更新时，sync会更新所有已安装的技能，如果你安装了很多不用的，同步时可能会看到大量无关的更新日志。第三，精选的过程本身也是你了解技能库内容构成的好机会。

3.3 技能的安装与管理

假设我们通过browse命令发现了一个名为setup-react-testing的技能，看起来正是我们需要的。

安装单个技能：

scribe add Naoray/skills:setup-react-testing --yes

或者，如果你正在浏览目录，也可以使用：

scribe browse --install setup-react-testing --yes

命令中的--yes参数是为了跳过确认提示，直接安装。如果你是第一次操作，可以不加这个参数，看看确认信息。

安装后发生了什么？

1. Scribe会从Naoray/skills仓库中拉取名为setup-react-testing的技能定义文件。
2. 将其存储在本地统一目录：~/.scribe/skills/Naoray/skills/setup-react-testing/下。
3. 自动在你已安装的、scribe支持的AI工具（如Claude Code, Cursor）中创建链接或注入配置，使得这些工具在运行时能够发现并调用此技能。

查看已安装技能： 任何时候，你都可以运行以下命令查看所有已安装的技能及其来源。

scribe list

这个列表能让你对自己装备了哪些“技能”一目了然。

同步技能更新： 技能库的维护者会不断优化和添加新技能。要获取你已安装技能的更新，只需运行：

scribe sync

这个命令非常“礼貌”，它只会更新那些你已经安装了的技能，不会擅自为你安装任何新的技能。这保证了你的环境不会因为远程仓库的变动而出现意外变化。

移除技能： 如果你觉得某个技能不再有用，可以将其移除。移除操作通常需要在AI工具本身的设置或技能管理界面中进行，因为scribe主要负责安装和链接。对于Cusor或Claude Code，你可以在其设置中查找“External Skills”或“Scribe Skills”相关选项进行管理。直接删除本地文件 (~/.scribe/skills/下的对应目录) 可能不会完全清理AI工具中的配置，因此推荐通过工具界面操作。

4. 实战演练：在AI编程工具中调用技能

技能安装好了，但它的威力只有在AI编程工具中才能完全释放。不同的工具集成方式略有不同，但核心逻辑相似：技能会成为AI上下文的一部分，你可以通过特定的指令或方式来触发它。

4.1 在Cursor中的使用体验

Cursor是深度集成AI的IDE。安装scribe技能后，通常有两种调用方式：

方式一：通过Chat指令直接触发在Cursor的Chat界面中，你可以尝试输入类似这样的指令：

请使用 “setup-react-testing” 技能为当前项目配置测试环境。

或者更简单直接地提及技能名：

/setup-react-testing

如果技能集成良好，AI助手（通常是Claude）会识别出这个技能，并开始执行技能中定义的一系列操作，比如询问你一些参数（项目类型、测试框架偏好），然后自动创建jest.config.js、__tests__目录、示例测试文件，甚至帮你安装必要的npm包 (npm install -D jest @testing-library/react)。

方式二：在代码上下文中右键或使用快捷键有些深度集成的技能，可能会在项目的特定文件（如package.json）上提供右键菜单选项。例如，右键点击package.json，可能会在上下文菜单中看到“Run skill: setup-react-testing”之类的选项。

实操心得：在Cursor中，最顺畅的方式是通过Chat。你需要清晰地表达“使用XX技能”的意图。有时技能名称可能比较具体，如果你记不全，可以尝试输入技能名的关键词，AI也可能会识别并给出提示。另外，首次使用时，注意观察AI的回复，它可能会向你确认一些选项或前提条件，请根据你的实际情况回答。

4.2 在Claude Code中的使用方式

Claude Code（这里指Claude桌面应用或深度集成Claude的编辑器插件）的使用逻辑与Cursor类似，但更依赖于对话。

1. 开启一个新对话或在你已有的项目对话中。
2. 在输入框中，明确引用技能。例如： “我当前在这个Node.js项目目录下。请应用你技能库中的 ‘init-express-api’ 技能，帮我初始化一个基础的Express.js API结构。”
3. Claude会识别到该技能已被加载到它的上下文中，并开始按技能定义的步骤执行。它可能会输出它将要做的事情的概要，然后逐一执行，比如创建app.js、routes/文件夹、基本的package.json脚本等。

核心机制：无论是Cursor还是Claude Code，背后的原理都是scribe将技能文件放置在了一个AI工具能够扫描到的特定位置。这些工具在启动或项目加载时，会读取这些技能定义，将其转化为AI模型可以理解的“系统提示词”或“工具调用”的一部分，从而扩展了AI的能力边界。

4.3 技能执行过程深度解析

当AI执行一个技能时，具体发生了什么？我们以“初始化一个Next.js项目”的技能为例，拆解这个黑盒：

1. 技能解析：AI读取技能定义文件。这个文件可能是一个YAML、JSON或特定格式的文本，里面用结构化的语言描述了目标、检查点、步骤和回退方案。
2. 环境检测：AI首先会检查当前环境是否满足技能执行的前提。例如，它会检查当前目录是否为空（或允许非空），检查本地是否安装了Node.js和npm/yarn/pnpm。
3. 交互确认：技能可能定义了需要用户输入的参数。AI会向你提问：“项目名称是什么？”“是否要使用TypeScript？”“是否要集成Tailwind CSS？”。
4. 顺序执行：获得必要信息后，AI开始按步骤执行。这不再是它“自由发挥”生成代码，而是严格遵循技能脚本：
   • 步骤1：运行npx create-next-app@latest . --typescript --tailwind --app --no-eslint（这是一个示例命令）。
   • 步骤2：检查命令执行成功与否。如果失败，根据技能定义尝试回退方案，比如换用yarn或指定版本。
   • 步骤3：创建成功后，技能可能指示AI去修改next.config.js增加一些推荐配置，或者创建一个README.md的模板。
5. 结果验证与总结：所有步骤完成后，AI会检查关键文件是否生成，并给你一个简短的总结，比如“项目已创建，依赖已安装，你可以在package.json中看到启动脚本”。

这个过程将原本需要多次对话、反复调试的复杂任务，压缩成了一次高效的、可预测的自动化流程。技能的可靠性，完全取决于技能定义本身的质量和维护者的经验，这也是像Naoray/skills这样由资深开发者维护的库价值所在。

5. 构建你自己的技能库：从消费者到创造者

使用别人的技能库固然高效，但最高阶的用法是创建属于你自己或你团队的技能库。这能将你重复性的工作彻底自动化、标准化。

5.1 技能的定义与创建

Scribe的技能有特定的格式。虽然官方文档是最佳参考，但一个基础的技能通常包含以下几个部分：

1. 元信息：技能名称、描述、版本、作者。
2. 触发器：如何调用这个技能？是通过特定的命令关键词，还是匹配某种文件模式？
3. 前提条件：执行前需要检查什么？（如：必须在Git仓库中？必须存在package.json？）
4. 参数：需要从用户那里获取哪些输入？（如：项目名、框架选择、是否启用特性A/B）。
5. 执行步骤：核心部分，定义一系列有序的操作。每个操作可以是：
   • 运行命令：如npm install。
   • 创建/修改文件：根据模板生成文件内容。
   • 询问用户：在过程中进行交互。
   • 条件判断：根据上一步结果决定下一步。
6. 后置处理与输出：执行成功后做什么？输出什么信息给用户？

创建一个技能，本质上就是编写一个YAML或JSON文件，用scribe能够理解的语法来描述上述逻辑。你可以从模仿Naoray/skills仓库中的现有技能开始。

5.2 本地测试与发布

1. 本地创建技能文件：在你的本地目录，例如~/.scribe/myskills/下，创建一个.scribe-skill后缀的文件，并编写内容。
2. 本地测试：你可以使用scribe命令在本地模拟运行你的技能，或者直接在Cursor/Claude Code中，通过指定本地技能文件的路径来测试。
3. 创建自己的注册表：在GitHub上创建一个新的仓库（例如yourname/my-awesome-skills）。
4. 推送技能：将你编写好的技能文件按照一定的目录结构推送到这个仓库。
5. 连接并使用：现在，你可以像连接Naoray/skills一样，连接你自己的仓库了：

   scribe registry connect yourname/my-awesome-skills scribe browse --registry yourname/my-awesome-skills

这样，你就拥有了一个私有的、可迭代的、可分享的技能中心。团队协作时，每个成员连接同一个技能库，就能保证项目初始化、代码规范、部署脚本等操作的高度一致性。

6. 常见问题与故障排查实录

在实际使用中，你可能会遇到一些问题。下面是我在多次使用和配置中遇到的一些典型情况及解决方法。

一个我踩过的坑：早期我在一个公司内网环境中使用，由于网络策略限制，gh命令和scribe访问GitHub API时总是超时。解决方案是在能访问外网的机器上，通过gh auth login生成一个认证令牌（Token），然后在内网机器上使用gh auth login --with-token < 你的令牌文件的方式进行认证，避免了命令行交互时的网络问题。这提醒我们，在受限环境下，灵活利用令牌认证是一个突破口。

最后，我想分享的一点体会是，像Naoray/skills配合scribe这样的工具，其意义远不止于节省几次敲键盘的时间。它代表了一种工作范式的转变：从每次都与AI进行开放式的、结果不确定的对话，转向构建一个可积累、可验证、可分享的“智能操作标准库”。你投入时间精选和打磨的技能，会成为你个人或团队开发资产的一部分，随着时间不断增值。开始可能只是安装一两个技能试试看，但当你习惯这种“技能即代码”的思维后，你会自然而然地想去封装更多自己的流程，这才是提升长期研发效能的关键。