Agent Skillsskill-base 2026年4月16日

Agent Skills 系列（1）：让 AI 从「能跑」到「符合团队约定」

系列说明

不少人听说过 Agent Skills，或在 OpenClaw 里装过几个，却说不清它是什么、适合什么问题、哪些该写成 Skill、怎么写、怎么在团队里分发；再往后才是多工具、多包下的碎片化，以及版本与协作。

本系列按这条线写：本篇只用写码里的一段摩擦当引子；接着依次讲 SKILL.md、skill-base（GitHub · 官网）与 skb、选题与触发；碎片化困局专讲触发冲突与「单一事实源」。主线路 1 → 2 → 3，第 4 篇与碎片化篇可按需穿插。

💔 先讲个很常见的场景

周三下午，你赶着把「客户列表页筛选」收尾，顺手让 AI 生成一段查询代码。

一分钟后，它给出一段语法没毛病、工程里也常见的代码：

// AI 生成的「看起来很专业」的代码
export async function listCustomers(params: {
  page: number;
  pageSize: number;
  keyword?: string;
}) {
  return db.customer.findMany({
    where: {
      name: params.keyword ? { contains: params.keyword } : undefined,
    },
    orderBy: { updatedAt: 'desc' },
    skip: (params.page - 1) * params.pageSize,
    take: params.pageSize,
  });
}

你对照一下团队的约定，清单立刻变长了——

❌ 你们是多租户系统，所有查询都必须带 tenantId 作用域；这段漏了
❌ 后台管理员有跨租户权限，但必须显式走 withTenantScope()，不能默认全表扫
❌ 导出接口和列表接口共享同一过滤器对象，避免「页面看见 50 条、导出 5 万条」的数据偏差
❌ 审计要求记录 actorId + 查询条件摘要，这段也没有挂审计钩子

你不会「被气哭」，但你会很熟这种感受：代码在 demo 里没问题，在真实系统里却不安全；接下来半小时，花在补作用域、补审计、补导出一致性。

「它不是在故意作对，它只是不知道我们默认怎么接。」

😤 比这更扎心的是：团队协作时

你以为个人使用 AI 已经够痛苦了？

试试让团队里 10 个人都用 AI 写代码：

三个月后，你的代码库很容易变成多套「各自合理」拼在一起：

谁写的	列表/表格方案	数据请求	表单与校验
A	手写 `table` + 分页	`fetch` 裸调	本地 `useState` 堆字段
B	`DataGrid` 企业版	`react-query` + 自建 key 规则	`react-hook-form` + `zod`
C	运营后台模板里的 `ProTable`	封装的 `useRequest`	`Form.Item` 规则散落各处

没人能在三分钟内说清：新页面到底该抄哪一套。Code review 里最常见的评论，从「这里有个 bug」变成「这里不像我们家的写法」。

工具费没少交，省下来的时间又贴回「对齐规范」和「改风格」里。

🤔 问题到底出在哪？

AI 不是不聪明。

恰恰相反，它太聪明了——它的聪明是通用的，而通用就意味着是「平均」的。

它不知道你们团队的：

🏢 业务黑话：什么叫「结转账单」？什么叫「绿通驱动」？什么叫「反关联」？
🎨 产品模板：弹窗统一用 DialogV2，列表统一用 ProTable
📐 代码规范：必须用 TypeScript、必须用 async/await、禁止用 var
🔧 技术选型与边界：查询必须走 withTenantScope()、金额必须用 Decimal、高风险操作必须挂审计

AI 没有你们团队的「记忆」。

每次对话，它就像面对一个全新项目的陌生人。

💡 那怎么办？

你可能会说：「那我每次都把所有规范告诉 AI 啊！」

可以，但你会累死

也有人会把规范写进 Cursor Rule、仓库根目录的 AGENTS.md / CLAUDE.md，或 README 里专门给 AI 看的章节：至少不用每次从零口述。麻烦在于：项目一多、规则一厚，这些文件很容易长成「短文合集」；如果你习惯每次对话都整份塞进上下文，窗口里先被规范占满，真正要改的代码和日志反而被挤出去。想省 token 就得手动挑片段贴——搬运成本还在，只是从聊天框搬到了文档框。

你：记住，任何查询都得带 tenantId
你：还要记住，管理员跨租户要显式 withTenantScope，不能偷懒
你：还要记住，导出和列表必须共用同一套过滤条件
你：还要记住，查敏感数据要记审计日志
你：还要记住...
你：算了，这段我手写吧

有没有一种方法，让 AI「天生就知道」你们团队的规范？

答案就是——Agent Skill。

🎯 什么是 Agent Skill？

简单来说，Agent Skill 就是一份结构化的团队规范，告诉 AI：

在我们公司/团队，遇到 X 场景时，应该用 Y 方式处理。

业界常见形态（如 Claude Skills）是一个技能目录：根目录必有 SKILL.md（含 YAML 头里的 name / description），还可以附带 references/、scripts/ 等按需加载的材料——比「每次聊天里粘贴一大段 prompt」更好维护，也更不占满上下文。

就像给 AI 一张你们团队的员工手册：有触发说明、有禁区、有能照抄的示例。

有了它，AI 更容易在第一轮就贴近你们规范，而不是等你一条条改。

📣 下一步

紧接阅读可从 概念实战篇 开始；其余姊妹篇见上表，官方字段与目录约定见文末。

skill-base： 官网 · GitHub — 团队 AI Agent Skill 私有化知识库。

系列导航（姊妹篇）

篇	文章	在讲什么
2	概念实战篇	`SKILL.md` 长什么样、怎么写
3	工具引入篇	用 skill-base / `skb` 分发与安装
4	什么值得做成 Skill	哪些内容值得做成 Skill、设计向补充
5	管理后台查询页案例	把项目隐性规范固化为可执行 Skill
6	运维手册	上线后治理触发、冲突与版本
延伸	碎片化困局	多工具、多 Skill 时的触发与治理