8.0
热点
AI SCORE
编程提效2026-09-23 15:21
为 AI 编程 Agent 构建可复用技能系统的实践
dev.to · AI#AI 编程#工作流#工程实践
Editor brief · 编辑速览
通过结构化技能库（项目规范、CI 配置、部署规则等）让 AI Agent 在项目中保持一致工作方式，减少重复配置。
AI 编程代理在写代码这件事上已经越来越厉害了。
但让它们稳定地工作，才是更难解决的问题。
一个能力强的代理可以搭建应用骨架、写功能、创建 GitHub Actions 工作流、配置部署，还能做代码审查。
然而如果没有项目专属的规则，结果很快就会变得不一致。
一个代理创建一种结构，另一个代理用的是另一种。有的记得跑测试，有的说"应该能跑通"。有的加了不必要的依赖，有的重复造了已有的工具。
我想要一种不同的方式。
于是我为 AI 编程代理构建了一套可复用的技能集合。
这个项目是开源的：
GitHub: https://github.com/bkoimett/agent-skills
在与 AI 编程代理协作时，我注意到实际上存在两种不同类型的指令。
"实现这个功能。"
"这是这个代码库应该遵循的工作方式。"
第二类指令通常散落在：
这使得每个新的代理会话都要花时间重新发现同样的信息。
我想把这些重复的工作流迁移到可复用的技能中。
这个系统围绕一个简单生命周期组织：
Idea
↓
Scaffold
↓
Build
↓
Review
↓
CI
↓
Deploy
↓
Verify
不再创建一个庞大的"软件工程"技能，而是让每个阶段各司其职。
当前集合包含：
agent-skills/
│
├── project-scaffolder/
├── code-conventions/
├── cicd-consistency/
├── deployment-consistency/
└── app-review/
每个技能都可以独立使用。
这是基础。
"生成一个 React 应用。"
"理解需要构建什么，把重要的决策显式化，然后创建最小的合适项目。"
Requirements
↓
Clarify ambiguity
↓
Architecture
↓
Stack selection
↓
Project structure
↓
Scaffold
↓
Documentation
↓
Install
↓
Verify
一条特别重要的规则是：
不要因为模板里包含了某项技术就添加它。
如果应用不需要数据库，就不要加。
如果不需要认证，就不要生成认证系统。
如果不需要微服务，就不要创建微服务。
脚手架应该来自需求，而不是来自代理的想象。
一旦一个项目存在了，另一个问题就出现了：
一个项目起始时可能是：
TypeScript
strict typing
tests beside components
pnpm
ESLint
Prettier
六个月后，你可能会发现：
不同的包管理器
不一致的测试位置
到处都是 `any`
未使用的抽象层
文档和代码不再匹配
code-conventions 技能会对代码库进行审计，检查是否符合已建立的约定。
包括：
重要的区别在于，它不会因为代理偏好某种风格就去发明一种新风格。
已有的项目约定优先。
CI 往往是本地开发和自动化开始分道扬镳的地方。
例如，README 写着：
pnpm lint
pnpm typecheck
pnpm test
pnpm build
但 GitHub Actions 可能还在跑：
npm test
或者项目已经从 Node 20 迁移到了 Node 22，而 CI 还在用旧的运行时。
CI 技能在生成或修改工作流之前会先检查实际的代码库。
对于 Node/TypeScript 项目，典型生命周期是：
Install
↓
Lint
↓
Typecheck
↓
Test
↓
Build
对于 Go 则是：
gofmt
↓
go vet
↓
go test
↓
go build
对于混合仓库，工作流可以围绕实际的包结构组合。
重要的规则是：
永远不要发明项目中根本不存在的 CI 命令。
部署存在同样的问题。
不同项目最终会对以下内容产生完全不同的假设：
所以 deployment consistency 将通用部署原则和特定云服务商的知识分离。
deployment-consistency/
│
├── SKILL.md
│
└── references/
├── deployment-principles.md
├── vercel.md
├── render.md
├── docker.md
├── environment-variables.md
├── database.md
├── rollback.md
└── verification.md
这意味着主技能不需要了解每个云服务商的每个细节。
它可以在需要时加载相关的参考文档。
最后一块是 review 技能。
我不想再做一个泛泛的：
"审查这个代码库。"
相反，review 有具体的检查领域。
这一个技能特别有用。
它对比项目声称的内容和实际做的事。
README:
"Authentication is required."
Application:
Public route bypasses authentication.
README:
"Run pnpm dev."
package.json:
No dev script exists.
目标是找出具体的不一致，而不是生成一篇冗长主观的代码审查报告。
这可能是最大的架构决策。
创建一个类似：
AI_ENGINEERING_RULES.md
包含数千行覆盖所有内容的文件是很诱人的。
我不认为这是正确的抽象方式。
AGENT
│
▼
┌──────────────┐
│ Skill │
└──────┬───────┘
│
┌──────────┴──────────┐
▼ ▼
SKILL.md references/
workflow detailed knowledge
技能知道要做什么。
references 解释特定技术或云服务商的工作方式。
这保持了上下文更小，也让系统更易于维护。
有一件事我特别想解决的是：脚手架之后会发生什么。
创建初始源代码是不够的。
一个新项目还需要告诉未来的代理如何工作。
所以 scaffolder 会创建：
AGENTS.md
DESIGN.md
WORKFLOW.md
README.md
每个文件有不同的职责：
重要的一点是避免重复。
代理不应该需要在四个不同地方读同一段 500 行的解释。
我开始把这个当作技能系统来思考的最大原因之一是上下文。
AI 编程代理不需要为每个任务加载整个代码库。
如果我在修复一个 Go session 生命周期 bug，代理不应该需要加载：
PWA 组件
部署配置
SEO 文档
GitHub Actions
Task
↓
Determine scope
↓
Load relevant skill
↓
Load relevant references
↓
Inspect relevant package
↓
Implement
↓
Verify
对于跨包任务，系统可以使用一个共享契约：
docs/shared-contract.md
这允许不同的代理在不同的包上工作，而不需要强制每个代理都理解整个代码库。
目前为止最大的教训是：AI 代理不仅仅需要更好的模型。
它们还需要更好的环境。
一个模型可能非常强大，但当以下情况发生时仍然会产生不一致的结果：
技能把这些期望转化为可复用的工作流。
与其反复告诉代理：
"记得跑测试。"
不如让技能把验证定义为工作流的一部分。
与其说：
"请不要加不必要的依赖。"
不如让 scaffolder 把这作为一个明确的决策规则。
与其说：
"检查 README 是否还准确。"
不如让 review 技能系统地检查文档漂移。
目标不是创建 100 个技能。
而是创建一小套可组合的技能，覆盖重复出现的工程工作流。
一些可能未来加入的方向包括：
但每个新技能都需要证明其存在的合理性。
如果它能被现有技能干净地处理，那它可能就不应该成为另一个独立的技能。
仓库是开源的：
GitHub: https://github.com/bkoimett/agent-skills skills.sh: https://skills.sh/bkoimett/agent-skills
如果你在使用 OpenCode 或其他 AI 编程代理构建产品，我很想知道你是如何组织自己的代理指令和可复用工作流的。
对我来说真正有趣的问题不是：
"AI 能写代码吗？"
而是：
"我们能构建出让 AI 始终写出我们真正想要的那种代码的环境吗？"
这正是这个项目在探索的方向。