我用这些 AI Skill 把一个企业级 Agent 平台从零撸到了上线

ITZHIHONH

350人浏览 · 2026-05-29 15:56:33

ITZHIHONH · 2026-05-29 15:56:33 发布

如果你也在用 AI 编码助手做严肃的项目开发，大概率遇到过这些问题：AI 写了代码不编译直接说"完成了"、改 A 模块忘了同步改 B 模块、长对话中逐渐忘记最初的架构约定。Skill 就是为了解决这些问题而生的——它是 AI 编码助手的"工作流引擎"。

本文基于 wagent（一个从零搭建的企业级多租户智能 Agent 平台，Java + Spring Boot + Vue 3 + PostgreSQL，累计数万行代码）的真实开发经历，介绍我日常使用的 Skill 体系，以及每种 Skill 在什么场景下最有用。

1. 为什么需要 Skill？

先说一个真实场景。

项目初期，我对 AI 编码助手说：“帮我实现知识库的文档上传和向量化流水线”。AI 立刻开始写代码——没看现有表结构，没读已有的 Service 层模式，直接写了一整套新类。风格和项目已有代码完全不同，连异常处理都用的是 RuntimeException 而不是项目里定义好的 BizException。

这就是没有 Skill 约束的 AI：能力强，但缺乏工作纪律。

Skill 的本质是把软件工程的最佳实践固化为 AI 的工作流程。就像你不会让一个新人直接上手写代码而没有任何代码规范、Code Review、测试要求一样，你也不应该让 AI 在零约束下写生产代码。

我目前使用的是 Superpowers（社区版） + UI/UX Pro Max 两套 Skill 插件，再加上 Claude Code 内置的若干 Skill。下面逐一介绍。

2. Superpowers：把软件工程纪律注入 AI

Superpowers 是目前最成熟的 AI 编码工作流 Skill 集，涵盖了从需求分析到代码合并的完整生命周期。我安装了 14 个 Skill，日常高频使用的约 8 个。

2.1 brainstorming — 动笔之前先动脑

触发时机：任何新功能、组件、行为变更，在写第一行代码之前。

实际体验：

这个 Skill 强制 AI 在实现之前走完一个完整的"需求 → 方案 → 设计文档"流程。在 wagent 项目中，每次我说"加一个 Skill Builder 功能，让用户用自然语言描述需求，AI 自动生成 Skill"，它不会立刻开始写代码，而是：

先探索现有代码结构（读 SkillRegistry、SkillService、SkillExecutor 接口）
逐个提问澄清需求（“Builder 生成的 Skill 存到哪？需要预览吗？需要审批流程吗？”）
输出 2-3 个方案对比（内联生成 vs 独立 Builder 服务 vs 前端纯 LLM 调用）
写出设计文档，保存到 docs/superpowers/specs/
让我确认后再进入实现

价值：避免了至少 3 次"写完了才发现方向不对"的大返工。对于企业级项目，返工成本远高于前期设计时间。

几个让我印象深刻的点：

它拒绝了我"直接实现"的指令，说"先让我理一下需求"，这种"违抗"其实是正确的工程纪律
设计文档是 markdown 格式，可以直接提交到 Git，后来新加入项目的人也能看到当时的决策背景
问题是一次一个地抛出来的，不是一下子甩 10 个问题，体验很好

2.2 writing-plans — 把设计翻译成可执行的任务列表

触发时机：设计确认后，写代码之前。

如果 brainstorming 产出了"做什么"，writing-plans 就是定义"怎么做、按什么顺序做、每个步骤哪些文件要改"。

以 Skill Builder 功能为例，writing-plans 产出的计划长这样：

Task 1: 数据库迁移 — 给 llm_provider 表加 skill_builder 列
Task 2: 后端 DO 层 — LlmProviderDO 新增字段
Task 3: 后端 Service 层 — LlmProviderService 新增 setSkillBuilder/clearSkillBuilder
Task 4: 后端 Controller — SkillBuilderController + DTO
Task 5: 前端 API 层 — skillBuilderApi.ts
Task 6: 前端组件 — SkillBuilderDrawer.vue
Task 7: 前端集成 — 在 SkillManager 中集成抽屉组件
Task 8: 网关路由 — Gateway 添加 skill-builder 路由
Task 9: 端到端验证

每个 task 的目标是 2-5 分钟可完成，粒度非常细。这样做的好处是：

每步做完都能验证，出问题立刻知道是哪个 task 引入了 bug
可以随时暂停、恢复，不会丢失上下文
提交记录干净，一个 task 一个 commit

实际体验：粒度确实够细，不太会出现"一个 task 做了一半不知道接下来干什么"的情况。但它也有个"职业病"——有时候会把很琐碎的步骤（比如"给 DTO 加一个字段"）也拆成独立 task，略显冗余。不过仔细想想，这在大型项目中反而是对的——每个改动都应该可以独立 review。

2.3 test-driven-development — 没测试的代码等于没写

触发时机：任何功能实现、Bug 修复，在写实现代码之前。

这是我最开始抗拒、后来最依赖的一个 Skill。它的铁律是：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

不接受任何借口。哪怕只是一个 getter/setter，也要先写测试。

在 wagent 的 Skill Builder 模块开发中，TDD 流程是这样的：

// Step 1: 先写测试（此时 SkillBuilderService 还不存在）
@Test
void shouldParseSkillNameFromSimplePrompt() {
    String llmOutput = "Skill Name: Weather Query\nDescription: Get weather info";
    SkillDraftDTO draft = skillBuilderService.parseLlmOutput(llmOutput);
    assertEquals("Weather Query", draft.getName());
    assertEquals("Get weather info", draft.getDescription());
}

// Step 2: 运行测试 → 失败（预期的红）
// Step 3: 写最简实现 → 运行测试 → 通过（绿）
// Step 4: 重构优化（保持绿）

实际体验：

TDD 在 wagent 这个项目里救了我不止一次。有一次重构 ContextAssembler 的 token 预算计算逻辑，改完后我自己觉得没问题，但 TDD 的测试直接挂了——原来我把 selectHistory 的最小保证数从 2 改成了 1，这个 behavior change 我自己都没意识到。如果没有测试，这个 regression 大概率会带着上线，然后出现"对话历史被截断导致 Agent 回答质量下降"这种难以排查的问题。

当然，TDD 不是没有成本。wagent 的测试代码量大概和业务代码量是 1:0.6 的关系，这意味着多写了 60% 的代码。但考虑到这个项目是单人开发、没有 QA 团队、随时可能重构，这 60% 是项目能持续演进的保险金。

2.4 verification-before-completion — 没验证过的事情不要说"完成了"

触发时机：任何声称"完成"“修复”"通过"之前。

这是最容易被忽视但最实用的 Skill 之一。它的核心要求很简单：

声称完成之前，必须运行验证命令并看到通过结果。

听起来像废话，但 AI 经常犯的错误是：写完代码就说"已完成"，但实际上：

Maven 编译报错（少了一个 import）
前端 TypeScript 类型不匹配
只改了 Agent 模块，忘了同步改 Gateway 路由
改了数据库字段没更新 MyBatis 映射

这个 Skill 强制 AI 在每次修改后运行 mvn compile -pl <module> -am -q，真正看到 BUILD SUCCESS 才说完成。

在这个项目里的实际价值：

wagent 有 6 个 Maven 子模块，模块间有编译依赖。每次我的做法是让 AI：

1. 改代码
2. mvn compile -pl <module> -am -q  ← 必须亲眼看到 BUILD SUCCESS
3. 如果失败，读错误日志 → 定位 → 修复 → 回到步骤 2
4. 通过后才说"完成"

这个循环在开发 Skill Builder 模块时跑了不下 20 次，每次都是 AI 自己发现、自己修复，我只需要在最后确认。

2.5 systematic-debugging — 不要猜，要验证

触发时机：遇到任何 Bug、测试失败、异常行为。

AI 遇到 Bug 时的本能反应是"我猜可能是 X 的原因"，然后开始改代码。systematic-debugging 强制走一个科学的排查流程：

观察现象 → 形成假设 → 设计验证实验 → 执行实验 → 确认根因 → 修复

在实现 ContextAssembler 时，有一个诡异的问题：token 预算计算在单测中通过，但在集成场景下总是差几十个 token。AI 一开始猜测是"字符串长度和 token 数的换算问题"，但 systematic-debugging 要求它先验证假设——打印实际的 prompt 字符串、用 tokenizer 精确计数——然后发现根本不是换算问题，而是 ConversationService 里多注入了一段 system prompt，导致可用预算比预期少。

没有这个 Skill 会怎样：AI 会沿着"字符串长度换算"这个错误方向反复修，浪费大量时间。

2.6 requesting-code-review — 让别人（或另一个 AI）看你的代码

触发时机：完成一个功能模块后、合并之前。

这个 Skill 让 AI 对当前分支的 diff 做一次全面的 Code Review，输出结构化的问题列表。我通常在每个 Phase 完成后跑一次。

它发现过的问题：

Skill Builder 的 parseLlmOutput 对空字符串没做防御，会抛 NPE
McpSkillExecutor 中的 HTTP 连接没有设置超时，理论上可能永久阻塞
前端 SkillBuilderDrawer 的 el-input 没有做 XSS 防御（虽然 Element Plus 默认会转义，但显式处理更安全）
几个 Service 类中 @Cacheable 注解的 key 表达式不一致

这些都是我自己 review 大概率会漏掉的问题。

2.7 dispatching-parallel-agents — 并行推进独立任务

触发时机：有 2 个以上互不依赖的任务。

当我说"同时改前端 SkillBuilderDrawer 组件和后端 SkillBuilderController 的路由配置"时，这个 Skill 会把任务拆成独立子任务，派发给并行 Agent 同时执行。

适合的场景：前后端独立改动、多个微服务各自的修改、不相关的文档更新。

不适合的场景：前后端共享 DTO 的修改（有依赖关系）。

实际体验：并行 Agent 确实快——两个独立改动从串行 8 分钟变成并行 4 分钟。但需要你在拆分任务时把依赖关系想清楚，不然一个 Agent 在等另一个的结果，跟串行没区别。

2.8 finishing-a-development-branch — 优雅收尾

触发时机：功能完成、测试全绿、准备合并。

这个 Skill 帮你做收尾决策：是直接 merge 到 main？还是 squash？还是创建 PR？它会自动检查当前分支状态、对比 main 的差异、检查是否有未推送的提交、然后给出建议选项。

实际体验：如果你和我一样经常忘记"这个分支是推上去创建 PR 还是直接 merge"，这个 Skill 能减少决策疲劳。特别是在同时维护多个 feature 分支时，它能帮你理清每个分支的状态——哪些已经合并了可以删掉，哪些还需要继续开发。

3. UI/UX Pro Max：让前端不再像"程序员写的界面"

wagent 的前端基于 Vue 3 + Element Plus，但我对 UI 设计一窍不通。UI/UX Pro Max 插件解决了这个问题。

3.1 ui-styling — 组件级别的样式精调

使用场景：按钮样式、表格间距、卡片阴影、暗色模式适配等。

举例：Skill 管理页面的 Skill 卡片原本是默认的 Element Plus 样式，看起来很"素"。我让 ui-styling 做了一次精调：

"给 SkillManager 页面的 Skill 卡片应用 glassmorphism 风格"

它输出了一套完整的 CSS，包括半透明背景、backdrop-filter 模糊、渐变边框等，最终效果比手写的好很多。它内置了 50+ 种视觉风格（glassmorphism、claymorphism、minimalism、brutalism、neumorphism 等），你可以直接按名字选。

3.2 design-system — 全局设计一致性

使用场景：需要统一色彩体系、间距规范、字体配对时。

这个 Skill 在项目早期帮了大忙。wagent 的管理后台有多个页面（Agent 管理、Skill 管理、MCP 管理、知识库管理），每个页面如果各自为政，颜色、间距、字号就会乱七八糟。design-system 帮我定义了一套设计 token：

主色、辅色、成功/警告/危险色
4 级字体大小阶梯
统一的间距 scale（4px / 8px / 16px / 24px / 32px）
深浅两套主题变量

这些 token 定义好后，后面所有页面开发都直接引用，保证了视觉一致性。

4. 内置 Skill：日常高频工具

除了两套插件，Claude Code 还有几个内置 Skill 我几乎每天用：

4.1 code-review / security-review

快速审查当前改动。code-review 偏代码质量和逻辑正确性，security-review 偏安全漏洞（SQL 注入、XSS、敏感信息泄露）。提交前各跑一次，花不了几分钟，但能避免很多低级错误。

4.2 run / verify

run 启动项目并截图确认 UI 效果，verify 确认某个代码改动真的生效。对于前端改动，光看代码不够——至少要在浏览器里点几下确认交互逻辑是对的。

4.3 fewer-permission-prompts

自动分析你的操作记录，把常用的只读操作加入权限白名单，减少"是否允许执行此命令"的弹窗。wagent 项目有大量 mvn compile、git status、ls 类操作，白名单化之后效率提升明显。

5. 我的日常工作流：Skill 编排全景

说了这么多，把它们串起来就是我日常的工作流：

用户需求： "给 Skill 管理加一个 AI Builder 功能"
                │
     ┌──────────▼──────────┐
     │  brainstorming      │  ← 探索代码、澄清需求、输出设计方案
     │  (30 min - 1 hour)  │
     └──────────┬──────────┘
                │ 设计文档确认
     ┌──────────▼──────────┐
     │  writing-plans       │  ← 拆解为 9 个 bite-sized task
     │  (15 min)            │
     └──────────┬──────────┘
                │
     ┌──────────▼──────────┐
     │  using-git-worktrees │  ← 创建隔离工作区
     └──────────┬──────────┘
                │
     ┌──────────▼──────────────────────────────────┐
     │  executing-plans + subagent-driven-dev       │
     │  对每个 task:                                │
     │    1. TDD: 先写测试 → 失败 → 写代码 → 通过    │
     │    2. dispatching-parallel-agents (独立 task) │
     │    3. verification: mvn compile, npm build    │
     │    4. git commit (每个 task 独立提交)         │
     └──────────┬──────────────────────────────────┘
                │
     ┌──────────▼──────────┐
     │  verification        │  ← 全量验证：编译 + 测试 + 启动 + 功能验证
     └──────────┬──────────┘
                │
     ┌──────────▼──────────┐
     │  code-review         │  ← 审查 diff，标记问题
     │  security-review     │  ← 安全检查
     └──────────┬──────────┘
                │
     ┌──────────▼──────────┐
     │  finishing-a-branch  │  ← 合并/PR/清理
     └─────────────────────┘

这个流程看起来重，但因为它由 AI 自己驱动（你只需要在每个阶段给 yes/no 的确认），实际人力投入很小——大部分时间是在看 AI 的输出和做决策，而不是自己写代码。

6. 哪些 Skill 不适合当前项目？

不是所有 Skill 都适合每个项目。以下是我装了但很少用的：

Skill	原因
slides	我不需要做 PPT
brand	个人项目不需要品牌指南
banner-design	没有营销需求
receiving-code-review	单人开发，没有外部 review 需要"翻译"的场景

7. 总结：Skill 改变了什么？

用 Skill 之前和之后的开发体验对比：

维度	没用 Skill	用了 Skill
代码一次性编译通过率	~60%	~95%
跨模块遗漏修改	经常	几乎没有
AI 说"完成"实际没完成	频繁	几乎没有
前端风格一致性	各页面各自为政	统一设计 token
需要人工干预的频率	每 2-3 轮对话	每 10-15 轮对话
Bug 修复时间（排查占比）	排查 80% 修复 20%	排查 30% 修复 70%