AI编码助手工程化实践：从提示词到可复用技能库

1. 项目概述：一个为AI编码助手量身定制的“弹药库”

如果你和我一样，日常开发已经离不开像 Cursor、Claude Code、Windsurf 这类 AI 编码助手，那你肯定也遇到过这样的时刻：想让 AI 帮你写一个规范的 Git 提交信息，或者生成一个清晰的 PR 描述，却发现每次都要重新组织语言，费时费力，效果还不稳定。我们需要的不是一次性的对话，而是可复用、可集成、经过实战检验的“标准操作程序”。这正是liatrio-labs/ai-prompts这个开源项目要解决的问题。

简单来说，这是一个专门为软件工程师和开发者打造的 AI 提示词与技能库。它不是一个简单的文本集合，而是一个结构化的、工程化的工具箱，旨在将我们日常开发中的高频任务——比如代码审查、提交规范、文档撰写、图表生成——转化为 AI 助手能够稳定、高质量执行的标准化流程。项目将零散的“咒语”升级为可安装、可管理的“技能”，让你能像调用命令行工具一样，在 AI 助手中一键触发复杂的、多步骤的工作流。

这个项目适合所有希望提升 AI 助手使用效率的开发者。无论你是想规范团队的 Git 提交习惯，还是希望 AI 能更可靠地帮你处理分支拆分、Mermaid 图表生成这类复杂任务，这里都提供了开箱即用的解决方案。更重要的是，它背后的设计理念——如“上下文标记”用于对抗 AI 的“上下文腐烂”——为我们如何更工程化地与 AI 协作提供了宝贵的思路。

2. 核心设计理念：从临时“咒语”到工程化“技能”

初次接触这个项目，你可能会觉得它只是一个提示词的文件夹。但深入看下去，你会发现它的设计远不止于此。其核心思路是将 AI 提示词进行“产品化”和“工程化”处理，这主要体现在两个关键概念上：技能和上下文标记。

2.1 技能：封装复杂工作流的可执行单元

在传统的 AI 助手使用中，我们输入一段提示词，AI 返回一段结果，交互是线性的、一次性的。而ai-prompts项目中的“技能”则不同。一个技能（例如git-commit-conventional）是一个完整的、自包含的工作流包。它通常包含：

1. 一个定义明确的输入/输出规范：明确告诉 AI 需要用户提供什么信息（如变更的文件列表、变更类型），以及最终应该输出什么格式的内容（如符合 Conventional Commits 规范的提交信息）。
2. 多轮对话的逻辑：技能可能引导 AI 与用户进行多轮问答，以收集必要信息，而不是要求用户一次性提供所有细节。
3. 错误处理与验证逻辑：例如，在create-mermaid-diagrams技能中，AI 不仅生成图表代码，还会调用本地 CLI 工具进行语法验证，形成一个“生成-验证-修复”的确定性循环。
4. 与外部工具的集成：部分技能设计为可以与命令行工具联动。比如create-pull-request技能，在生成 PR 描述后，可以进一步通过 CLI 自动在 GitHub/GitLab 上创建 PR。

这种设计将 AI 从一个“问答机”变成了一个“工作流执行引擎”。对于开发者而言，使用体验从“我该如何向 AI 描述这个任务”变成了“我该调用哪个技能来完成这个任务”，心智负担大大降低。

2.2 上下文标记：对抗“上下文腐烂”的巧妙策略

“上下文腐烂”是使用大型语言模型时的一个经典问题。当对话或输入的上下文非常长时，模型可能会“忘记”或忽略在上下文早期给出的重要指令，导致输出不符合预期。这在处理复杂的、多步骤的技能时尤为致命。

这个项目引入了一个极其简单却有效的解决方案：上下文标记。其原理是，在技能或提示词的关键指令中，要求 AI 在回复时必须以一个特定的表情符号开始。

例如，在git-commit-conventional技能中，指令可能包含：“你的所有回复都必须以 🎯 这个表情符号开始。” 当用户看到 AI 的回复以 🎯 开头时，他就能立即获得一个粗粒度的确认：AI 至少“看到”并“记住”了这条核心指令。如果回复没有以约定的表情符号开头，用户就能立刻警觉——上下文可能已经“腐烂”，指令未被遵循，需要重新调整或简化输入。

这就像网络通信中的“心跳包”或“校验和”，用一个极低成本的方式，提供了对指令是否被有效处理的可视化反馈。项目文档中的“上下文标记速查表”正是为了这个目的而存在，让用户能快速核对。

注意：上下文标记虽然有效，但它是一种“尽力而为”的检测机制，不能保证 AI 完全理解了所有复杂指令。它最适合用于检测因上下文过长导致的指令完全丢失。对于更精细的逻辑错误，仍需人工审查。

3. 项目结构深度解析与使用指南

理解了核心概念，我们来看看这个“弹药库”具体是如何组织的，以及我们如何将它集成到自己的工作流中。项目的结构清晰地区分了“提示词”和“技能”，并提供了多种集成方式。

3.1 目录结构与内容分类

克隆仓库后，你会看到以下核心结构：

ai-prompts/ ├── prompts/ # 传统提示词库 │ ├── development/ # 开发工作流相关 │ │ ├── address-pr-review-feedback.md │ │ ├── review-branch.md │ │ └── squash-merge.md │ └── documentation-and-research/ # 文档与研究相关 │ ├── check-docs.md │ ├── improve-prompt-with-research.md │ └── review-documentation.md ├── skills/ # 技能库（核心） │ ├── git-commit-conventional/ │ │ └── SKILL.md │ ├── create-pull-request/ │ │ └── SKILL.md │ ├── create-mermaid-diagrams/ │ │ └── SKILL.md │ └── ... (其他技能目录) └── ...

提示词位于prompts/目录，按用例分类，是相对传统的、可直接复制的文本片段。它们适合快速、一次性的使用场景。

技能位于skills/目录，每个技能是一个独立的文件夹，核心是SKILL.md文件。这个文件包含了该技能的完整定义、使用说明、前置条件以及给 AI 的详细指令。技能是项目进化的方向，许多原有的提示词都已迁移为技能（如commit.md->git-commit-conventional）。

3.2 三种集成方式详解

项目提供了从简单到高级的多种集成方式，适应不同的使用习惯和技术栈。

方式一：直接复制（最灵活，适合尝鲜）这是最基本的方式。直接打开你感兴趣的.md文件，复制里面的提示词文本，粘贴到你的 AI 助手聊天框中，然后根据你的具体场景替换其中的变量（如{file_changes}、{base_branch}）。这种方式零依赖，立即可用，适合快速测试某个提示词或技能的效果。

方式二：使用 Slash Command Manager（推荐，用于管理提示词）对于prompts/目录下的提示词，项目推荐使用配套工具Slash Command Manager。这个工具能自动检测你系统上安装的 AI 助手（如 Cursor、Windsurf），并将提示词批量安装为助手内的“斜杠命令”。

例如，你想把所有的开发工作流提示词安装到 Cursor 中，可以运行：

uvx --from git+https://github.com/liatrio-labs/slash-command-manager slash-man generate \ --github-repo liatrio-labs/ai-prompts \ --github-branch main \ --github-path prompts/development

运行后，工具会列出检测到的 AI 助手，让你选择安装目标。完成后，在 Cursor 的聊天框里输入/，你就能看到诸如/review-branch这样的命令，点击即可直接插入对应的完整提示词模板，极大地提升了效率。

方式三：使用skills.shCLI（核心，用于管理技能）对于更强大的skills/，项目使用了一个名为skills.sh的 CLI 工具来管理。这是一个通用的技能包管理器，概念上类似npm或pip，但专门用于分发和安装 AI 技能。

基础操作如下：

• 浏览技能：npx skills add liatrio-labs/ai-prompts --list。在不安装的情况下，列出该仓库中所有可用的技能。
• 一键安装所有技能：npx skills add liatrio-labs/ai-prompts --all。这会将所有技能的元信息安装到本地，通常位于用户主目录下的.skills目录中。
• 选择性安装：npx skills add liatrio-labs/ai-prompts --skill git-commit-conventional --skill create-pull-request。只安装你需要的特定技能。
• 指定安装代理：npx skills add liatrio-labs/ai-prompts --skill create-mermaid-diagrams -a cursor -a codex。将技能安装到特定的 AI 代理（如 Cursor、Claude Code）的配置中，实现深度集成。

安装完成后，如何使用取决于 AI 助手本身对技能标准的支持程度。一些先进的助手能直接识别.skills目录下的技能并提供调用界面。

实操心得：对于个人使用，我推荐从“方式一”开始，手动复制几个核心技能（如git-commit-conventional）的SKILL.md内容来体验。当确定这些技能有价值后，再使用skills.shCLI 进行批量安装和管理，这样更干净、易于更新。Slash Command Manager则非常适合团队统一部署一套标准的提示词命令集。

4. 核心技能实战拆解与避坑指南

理论说再多，不如亲手实践。我们来深入剖析两个最具代表性的技能，看看它们是如何工作的，以及在实践中可能会遇到哪些“坑”。

4.1git-commit-conventional：不止于提交信息生成

这个技能的目标是生成符合 Conventional Commits 规范的提交信息。但它的精妙之处在于，它考虑了一个完整的提交前工作流。

标准工作流解析：

1. 收集变更：技能会引导 AI 分析暂存区的变更（或用户提供的文件列表），自动识别变更类型（feat、fix、docs、style、refactor、test、chore）。
2. 撰写信息：基于变更类型和范围，生成结构化的提交信息，包括类型、可选的作用域、清晰的描述、可选的正文和页脚。
3. 提交卫生检查：这是关键一步。技能会提醒 AI 检查一些常见问题，例如：提交信息是否过于冗长？是否包含了不必要的调试代码？是否应该将大变更拆分为多个小提交？这相当于一个 AI 驱动的“预提交钩子”检查。

避坑指南：

• 变更识别误差：AI 对于“重构”和“修复”的边界，或者“功能”和“文档”的混合变更，判断可能不准确。技巧：在启动技能前，最好自己先对变更做个简单归类，并在与 AI 交互时主动给出提示，如“这次主要是修复了登录模块的边界条件错误，附带更新了相关注释”。
• 作用域过度泛化：AI 有时会倾向于使用像(core)这样宽泛的作用域。技巧：在技能询问时，明确指定一个具体的作用域，如(auth)或(ui/login-button)，这能极大提升提交日志的可读性。
• 忽略破坏性变更：如果变更包含了不兼容的 API 修改，需要在提交信息页脚添加BREAKING CHANGE:。AI 可能会遗漏这一点。技巧：务必在对话中明确指出“这是一个破坏性变更，移除了某个已弃用的函数”。

4.2create-mermaid-diagrams：实现“生成-验证”闭环

这个技能解决了用 AI 生成图表代码的一大痛点：生成的 Mermaid 语法可能有错误，导致无法渲染。该技能通过集成本地 CLI 验证，形成了一个强大的闭环。

工作流闭环解析：

1. 需求描述：用户用自然语言描述想要的图表（如“请画一个展示用户从登录到下单的序列图”）。
2. AI 生成代码：AI 根据描述生成 Mermaid 代码。
3. CLI 验证：技能会自动调用本地的mermaid-cli或类似工具，尝试将代码渲染为图片或进行语法检查。
4. 错误反馈与修复：如果验证失败，CLI 输出的错误信息会被反馈给 AI，AI 据此分析错误并重新生成修正后的代码。这个过程可以循环多次，直到生成语法完全正确的 Mermaid 代码。

避坑指南：

• 环境依赖：这个技能的强大功能依赖于本地安装的 Mermaid CLI 工具。如果没安装，验证环节会失败。技巧：在使用该技能前，先确保能通过命令行运行mmdc -h或npx @mermaid-js/mermaid-cli等命令。项目文档应明确列出所需依赖。
• 复杂图表迭代：对于非常复杂的图表，可能需要多轮“生成-验证”循环。技巧：保持耐心，并观察 AI 是如何根据错误信息进行修正的。有时，将复杂需求拆解为几个简单的子图分别生成，成功率更高。
• 样式定制局限：AI 生成的通常是基础语法，对于深度的样式定制（如特定主题、字体）可能不擅长。技巧：先让 AI 生成正确的结构图，然后手动在其基础上添加样式定义，这样效率更高。

4.3branch-surgery-pr-split：处理“巨无霸”分支的精密手术

这个技能面向一个非常具体的痛点：一个分支包含了太多混杂的修改，无法直接进行代码审查，需要被拆分成多个逻辑独立、可单独评审和合并的小 PR。

手术流程解析：

1. 分支分析：AI 首先分析目标分支与基准分支（如main）的所有差异，尝试理解不同的修改“簇”分别属于什么逻辑功能或修复。
2. 拆分策略制定：AI 会提出一个拆分方案，例如：“建议拆分为三个 PR：1) 用户认证模块重构（涉及 A、B 文件）；2) 支付接口 Bug 修复（涉及 C、D 文件）；3) 日志格式统一（涉及 E、F 文件）”。并说明每个部分的依赖关系。
3. 创建拆分脚本（高级功能）：在一些实现中，技能甚至可以生成一个交互式的 Shell 脚本，引导用户一步步创建新的特性分支、挑选指定的提交，并推送到远程仓库。
4. 合并顺序指导：技能会建议 PR 的合并顺序，特别是当拆分后的 PR 之间存在依赖时。

避坑指南：

• AI 的代码理解局限：AI 对代码逻辑关联性的判断可能不完美，尤其是面对高度耦合的代码时。技巧：不要完全依赖 AI 的拆分方案。将其作为初步建议，然后由最熟悉代码的开发者进行复核和调整。拆分的基本原则是“高内聚、低耦合”。
• 提交历史的整洁性：使用git cherry-pick进行拆分可能会产生重复的提交哈希，影响历史可读性。技巧：对于重要的主干分支，在合并拆分后的 PR 时，考虑使用Squash and Merge来保持主线历史的清晰。同时，确保每个拆分 PR 都有清晰、独立的描述。
• 沟通成本：拆分分支会产生多个 PR，增加评审和跟踪的管理成本。技巧：在拆分前，务必在团队内同步拆分计划和各个 PR 的职责，可以使用技能生成的方案作为讨论蓝本。

5. 自定义技能开发与贡献指南

当你熟练使用这些技能后，很可能会产生为自己团队或特定技术栈定制技能的想法。ai-prompts项目不仅是一个使用库，也提供了一套创建新技能的脚手架和工具。

5.1 技能创作脚本与工作流

项目根目录下的scripts/文件夹提供了一些 Python 脚本，用于辅助技能的创建和验证，这些脚本灵感来源于 OpenAI 的技能项目。

• 技能验证：uv run scripts/quick_validate.py skills/git-commit-conventional这个脚本会检查技能目录的结构、SKILL.md的格式是否基本符合规范。在提交贡献前运行一下，可以避免低级错误。

• 初始化新技能：uv run scripts/init_skill.py my-new-skill --path skills --resources scripts,references --examples这是最实用的工具。它会创建一个新的技能目录骨架，包含：

  • SKILL.md模板文件，里面已经预置了技能描述、示例交互等结构。
  • resources/目录（如果指定），用于存放技能可能用到的参考文件、数据样本。
  • examples/目录（如果指定），用于存放展示技能输入输出的示例文件。 使用这个脚手架能确保你的技能结构与仓库中的其他技能保持一致。

• 生成 OpenAI 代理配置：uv run scripts/generate_openai_yaml.py skills/my-new-skill对于一些能识别特定 YAML 配置格式的 AI 代理，这个脚本可以帮助生成对应的配置文件，实现更深度的集成。

5.2 编写高质量技能的要点

基于对现有技能的分析，我总结出几个编写高效、可靠技能的关键点：

1. 明确的单一职责：一个技能应该只做好一件事。git-commit-conventional只管生成提交信息，create-mermaid-diagrams只管生成和验证图表。避免创建“瑞士军刀”式的庞杂技能。
2. 强上下文引导：在SKILL.md的开头，用清晰、无歧义的语言定义技能的角色、目标和约束。使用“你是一个专注于...的助手”这样的句式来设定 AI 的行为模式。
3. 结构化输入输出：尽可能定义清晰的输入参数和输出格式。例如，使用类似“请提供以下信息：1. 变更的文件列表；2. 本次变更的主要目的...”的引导来收集结构化信息，而不是让用户写一段自由描述。
4. 集成上下文标记：务必为你的技能设计一个独特的表情符号作为上下文标记，并在指令中明确要求。这能极大提升技能在长对话中的可靠性。
5. 包含错误处理逻辑：预判 AI 可能犯的错或用户可能给的模糊输入，并在指令中告诉 AI 如何应对。例如，“如果用户无法提供明确的作用域，则留空，不要猜测”。
6. 提供丰富示例：在SKILL.md或examples/目录下，提供 2-3 个从输入到输出的完整示例。这是让 AI 理解你期望的最佳方式。

5.3 向原项目贡献

如果你开发了一个对社区可能有用的技能，可以考虑贡献给上游项目。步骤大致如下：

1. Fork 仓库：在 GitHub 上 Forkliatrio-labs/ai-prompts项目。
2. 创建特性分支：基于main分支创建一个描述性的分支，如feat/add-python-type-hint-skill。
3. 开发与测试：使用上述脚本创建技能骨架，并充分测试。确保你的技能在 Cursor、Claude Code 等主流助手中都能良好工作。
4. 更新文档：如果添加了新技能，记得在根目录的README.md中的技能目录表里添加一行，并更新上下文标记速查表（如果使用了标记）。
5. 提交 Pull Request：确保提交信息符合 Conventional Commits 规范（你可以用现有的git-commit-conventional技能来生成！），清晰描述变更内容。

注意事项：在贡献前，务必仔细阅读项目的CONTRIBUTING.md和CODE_OF_CONDUCT.md文件。特别是，确保你的技能不包含任何特定公司的私有信息、API密钥或过于狭窄、不具有普适性的逻辑。

6. 常见问题与实战排查实录

在实际使用和集成ai-prompts项目的过程中，我遇到了一些典型问题。这里将它们整理出来，并提供解决思路，希望能帮你少走弯路。

问题一：使用skills.sh安装技能后，在 AI 助手中找不到或无法调用。

• 可能原因 1：助手不支持。并非所有 AI 编码助手都原生支持skills.sh的集成标准。目前对 Cursor、Windsurf、Claude Code 等较新的、专注于开发的助手支持较好。
• 排查与解决：
  • 首先运行npx skills list查看技能是否已成功安装到本地仓库。
  • 查阅你所用的 AI 助手官方文档，看其是否支持“技能”或“自定义指令”的外部导入。有些助手可能需要手动将技能内容复制到其特定的配置目录。
  • 对于不支持原生集成的助手，最可靠的方式还是回归“方式一”：直接复制SKILL.md的核心指令部分到聊天窗口。

问题二：AI 的回复没有以约定的上下文标记开头，我该怎么办？

• 可能原因：这是典型的“上下文腐烂”迹象。可能是因为你在此次对话中已经进行了多轮复杂的交互，导致早期的技能指令被模型“遗忘”。
• 排查与解决：
  1. 简化上下文：开启一个新的聊天会话，并首先粘贴技能指令。这是最彻底的方法。
  2. 指令重发：在当前会话中，重新发送一次完整的技能指令，并明确要求：“请重新确认你的角色和任务，并且后续所有回复必须以[约定好的表情]开头。”
  3. 检查指令完整性：确保你复制的技能指令是完整的，没有在中间被截断。

问题三：技能执行的结果（如生成的提交信息、PR描述）质量不稳定，时好时坏。

• 可能原因：AI 模型本身具有随机性，且技能指令的编写质量、用户提供的输入信息的清晰度都会影响结果。
• 排查与解决：
  1. 优化你的输入：技能不是魔法。你给 AI 的输入越清晰、越结构化，输出质量就越高。例如，让git-commit-conventional生成提交信息前，自己先简要总结一下“修复了什么 Bug”、“增加了什么功能”。
  2. 迭代提示：如果第一次输出不满意，不要放弃。直接告诉 AI 哪里不对，例如：“这个描述不够具体，请更详细地说明这个修复是如何解决用户无法登录的问题的。” AI 会根据反馈进行修正。
  3. 组合使用技能：复杂任务可以分解。例如，先让 AI 用“代码解释”技能分析一段复杂变更，然后将解释结果作为输入，喂给git-commit-conventional技能来生成提交信息。

问题四：在团队中推广使用，如何保证大家用的都是同一套最新技能？

• 挑战：如果每个人都手动复制粘贴，很容易出现版本不一致、有人用了老版本提示词的情况。
• 解决方案：
  1. 标准化安装脚本：为团队创建一个初始化脚本（如setup_dev_skills.sh），里面封装了使用skills.sh或Slash Command Manager安装指定版本技能的命令。新成员 onboarding 时运行一下即可。
  2. 将技能库作为子模块：可以将ai-prompts仓库作为 Git 子模块添加到团队的项目模板或基础设施仓库中。这样，更新子模块即可为所有项目同步最新技能。
  3. 内部技能仓库：对于高度定制化的内部技能，可以参照此项目的结构，搭建一个团队内部的私有技能仓库。使用同样的工具链（skills.sh）进行管理，实现技能的内部共享和版本控制。

问题五：技能中提到的某些工具（如mermaid-cli,uv）在我的环境里没有，导致技能部分功能失效。

• 解决思路：技能文档应当（或使用者应当补充）明确列出其所有的外部依赖。这是一个很好的贡献点。
• 行动建议：为你常用的、但依赖外部工具的技能，创建一个简单的依赖检查或安装说明文档。例如，为create-mermaid-diagrams技能写一个SETUP.md，说明如何在 macOS (Homebrew)、Linux (apt) 和 Windows 上安装mermaid-cli。这不仅能方便自己，未来也可以贡献回社区。

通过这个项目近半年的实践，我的核心体会是：将 AI 助手工程化的价值，远大于零散地使用它。ai-prompts提供的不仅是一套工具，更是一种方法论——它教会我们如何通过设计精良的“技能”，将人类模糊的意图转化为 AI 可稳定执行的确定流程。这其中的关键，在于我们作为开发者，要从“与 AI 对话”转变为“为 AI 设计程序”。当你开始像设计 API 接口一样设计你的提示词时，你就会发现，AI 编码助手的潜力才真正开始被释放。