从今年AI Agent For Work 大爆发以来，投入了大量时间和精力去学习，去认知 Agent 的能力，写了很多 Skill 固化工作流程。其中收获到一些认知，想与你分享：

  1. 授agent以鱼，不如授以渔。很简单，LLM 是 brain ，Skill 是 body（有Harness的意味）。给agent 固定流程那他知识流水线/打螺丝的打工人，而把思维方式给到agent 那他就可以利用 LLM 去做一些创造性的事情，这一点是很有意思的。
  2. 环境依赖最为痛苦。这主要来源于身边朋友在使用 AI 时，常常会遇到的一些环境依赖问题。对于非计算机专业的人，环境依赖0 认知。AI 方面优秀的工具或 skill，都是早期计算机出身的人整出来的。后来人在学习时，处理起来异常难，让 AI 去处理的话，AI 会不考虑其他代价帮你处理。那我们就在设计的过程中，最好把环境依赖降到最低。

以下就是我的实践过程。

起因很简单——我想做一个 Skill：在任何项目里，跟 Agent 说一句”写篇博客”，它就能帮我把这个项目的经历写成文章，发到我的 Astro 博客上。

听起来不就是往仓库写一个 Markdown 文件吗？能有多难？

结果我们从 v1.0 做到了 v1.8，中间推翻了六次。

这篇不是技术文档，是我在这个过程中的一些感悟。如果你也在写 Agent Skill，或者在设计 AI 工具，也许会有共鸣。

环境是最大的诅咒

作为一个开发者，我的第一反应是理所当然的：

  1. Clone 仓库
  2. pnpm install
  3. 写文章
  4. pnpm dev 预览
  5. git push

丝滑。完美。然后我把这个 Skill 拿给我的同事——一位产品经理。她没有 Node.js，没有 pnpm，git 也没装好。她只有一台电脑、一个浏览器、和一个 GitHub 账号。

然后我意识到一件事情：我习以为常的开发环境，恰恰是普通人使用 AI 工具最大的门槛。

这个问题其实不只存在于 AI 工具。回想一下，多少技术教程的第一步就是”先装个 XXX”？多少优秀的开源项目，用户在安装这一步就放弃了？只不过以前门槛在用户和软件之间，现在门槛在用户和 Agent 之间。Agent 替用户省掉了”学怎么用”的时间，但没省掉”先装好环境”的痛苦。

所以我们设计了三层访问机制——有本地仓库用本地仓库，有 git 用 git，什么都没有就用 GitHub API，只需要 curl 加一个 Token。三层里最低的一层，只需要一台能打开浏览器的电脑。

这是第一课：设计 Skill 的时候，不要假设用户和你一样是开发者。 你觉得”这也要装？“的东西，可能是别人放弃的最后一个理由。

预览的困境

写完文章总得预览一下效果吧？Astro 的预览需要 pnpm dev，又回到了 Node.js 的问题。

我们想了很多方案：

  • 让用户装 Node.js？太重了，违背零依赖的初衷
  • 用 npx 临时跑？前提还是有 Node.js
  • 不预览直接发？太草率了

最后我们找到了一个有点”野路子”的方案——让 Agent 从 GitHub 仓库读取博客的真实源码文件，把文章 Markdown 转成 HTML，套进博客的真实样式里，生成一个独立的 preview.html，然后用浏览器打开。

不需要 Astro，不需要 Node.js，不需要任何构建工具。只要有浏览器就行。

而且这个预览是动态的——每次都从仓库读最新的源码。所以博客改了样式，预览自动跟上，永远不会过时。

这是第二课：当正规路径走不通的时候，退一步想——用户最终需要的不是工具本身，而是工具的结果。 用户不需要 Astro dev server，用户需要的是”在浏览器里看到文章长什么样”。

最重要的一课：不要授以鱼，而要授以渔

这个教训花了我最长时间才想明白。

在早期版本里，我把很多东西写死在 Skill 里：

  • CSS 样式快照 → 嵌入在 Skill 文件里
  • 分类列表 → 硬编码 极客/geek、创造力/creativity
  • 本地仓库路径 → 硬编码绝对路径
  • Frontmatter schema → 写死在文档里

看起来没问题，对吧？该有的信息都有了。

但问题是：

  • 博客样式改了，Skill 里的快照就过时了
  • 新增了分类，Skill 不知道
  • 换一台电脑，路径就不对了
  • Schema 加了新字段，Skill 还在用旧的

我把”答案”写给了 Agent，但没有教它”怎么找答案”。

后来我们把所有这些都改成了动态的：

  • 样式 → Agent 去读仓库最新的源码文件
  • 分类 → Agent 去扫仓库里所有文章的 frontmatter
  • 路径 → 自动检测，有环境变量就用，没有就搜索
  • Schema → Agent 运行时读 content.config.ts

好的 Skill 不存储答案，而是教 Agent 如何获取答案。

这其实是一个很深刻的原则。你给 Agent 的不是一份菜谱，而是一个厨房的地图。菜谱会过期，地图不会。食材会换季，但厨房的布局不变。

我想这可能是写好 Agent Skill 最重要的一个心法了。

Agent 比你想的更”固执”

有一件事让我挺意外的。

Skill 写好了，Agent 也装上了，我让同事试试。她的 Agent 回复是：

“不装不行，这三个都是必须的：Git、Node.js、pnpm”

它完全忽略了 Skill 里写的零依赖方案。

为什么？因为 Agent “知道” Astro 需要 Node.js。它的训练数据里有无数篇 Astro 教程，每篇的第一步都是 npm install。所以当它看到”Astro 博客”这个词，就自动跳到了结论——必须装 Node.js。Skill 里的 Tier 3 纯 API 方案？它根本没注意到。

Agent 的固有知识有时候比你的 Skill 指令更强。

这就像你给一个聪明的实习生写了一份详细的操作手册，但他干了三年类似的工作，所以翻了两页就觉得”这我懂”，然后按自己的经验来——结果搞错了。

解决方案是在 Skill 最显眼的位置反复强调关键信息。我们在文档最顶部加了一个 blockquote 警告，description 第一行写 ZERO DEPENDENCIES，Tier 3 标题加 ZERO DEPENDENCIES，Error Handling 里写 NEVER ask the user to install git/Node/pnpm。

把关键的事情重复三遍，放在 Agent 第一眼就能看到的地方。

这不是啰嗦，这是必要的。Agent 不像人，它不会”注意到”文档中间某一句”其实也可以不用装”。你得把重要的信息推到它注意力最高的位置。

格式校验：人眼看漏的，机器不会

一篇博客文章看起来简单，但出问题的点太多了：

  • Frontmatter 的 --- 围栏漏了闭合，Astro 直接报错
  • date 写成了 2024-13-45，渲染炸了
  • 图片路径用了相对路径，线上 404
  • 正文只有 100 字就结束了
  • 代码块忘了关 ```，下面的内容全变成了代码字体

这些事情人眼扫一遍很容易漏掉，但机器检查非常可靠。所以我们加了一个格式校验 Phase，25 项检查，分三个级别：Block（必须通过）、Auto-fix（自动修复）、Warn（提醒但不阻断）。

文章在到达浏览器预览之前，格式问题已经被清零了。

这让我想到一个更广泛的道理：Agent 不只是帮你写东西的工具，它也可以是你发布流程的守门人。 让 Agent 做它擅长的事——精确、重复、不带感情的检查——把人从这种工作中解放出来。

从 v1.0 到 v1.8

最后贴一下版本演进，每一次迭代背后都是一次认知的升级：

版本关键变化认知升级
v1.0硬编码路径和依赖”能用就行”
v1.1加入纯 REST API 方案”不是所有人都是开发者”
v1.2浅克隆 + 本地预览”能少下就少下”
v1.3零依赖预览：读源码拼 HTML”要的是结果，不是工具”
v1.4动态模板：每次从仓库读取”不要授以鱼，而要授以渔”
v1.4.1加强零依赖提示”Agent 比你想的更固执”
v1.5加入格式校验”Agent 是好的守门人”
v1.6动态 schema、编辑工作流”覆盖完整生命周期”
v1.7文章暂存位置按 Tier 分”每个环节都要想清楚文件在哪”
v1.8跨平台写作规范、SEO/GEO”发布不是终点，传播才是”

写在最后

我在工作中遇到很多人，他们不是计算机出身，但随着 AI 逐渐通用化，他们开始用 AI 工具来辅助工作。但每次碰到”依赖环境”的问题——装个 Node.js、配个环境变量、搞个 SSH key——他们就卡住了。

这些不是他们的问题，是我们这些工具设计者的问题。

好的工具应该适应人，而不是要求人适应工具。好的 Skill 应该在任何环境下都能跑，而不是只在开发者的电脑上能跑。

如果你也在写 Agent Skill，不妨问自己一个问题：

“如果用户只有一台刚买的电脑，他能不能用？”

这个问题改变了我们整个设计方向。也许它也能改变你的。