# 授agent以鱼，不如授以渔——写一个 0 依赖的 Skill 的感悟

**Published:** May 16, 2025

*从一个"往仓库写文件"的简单想法出发，造了一个任何环境都可以发博客的 Skill。教你快速落地Agent Skill...*

---
> 从今年AI Agent For Work 大爆发以来，投入了大量时间和精力去学习，去认知 Agent 的能力，写了很多 Skill 固化工作流程。其中收获到一些认知，想与你分享：
> 1. 授agent以鱼，不如授以渔。很简单，**[LLM](https://en.wikipedia.org/wiki/Large_language_model) 是 brain ，Skill 是 body**（有`Harness`的意味）。给agent 固定流程那他知识流水线/打螺丝的打工人，而把**思维方式**给到agent 那他就可以利用 LLM 去做一些创造性的事情，这一点是很有意思的。
> 2. 环境依赖最为痛苦。这主要来源于身边朋友在使用 AI 时，常常会遇到的一些**环境依赖**问题。对于非计算机专业的人，环境依赖0 认知。AI 方面优秀的工具或 skill，都是早期计算机出身的人整出来的。后来人在学习时，处理起来异常难，让 AI 去处理的话，AI 会不考虑其他代价帮你处理。那我们就在设计的过程中，最好把**环境依赖降到最低**。
> 
> 以下就是我的实践过程。

---

起因很简单——我想做一个 Skill：在任何项目里，跟 Agent 说一句"写篇博客"，它就能帮我把这个项目的经历写成文章，发到我的 [Astro](https://astro.build/) 博客上。

听起来不就是往仓库写一个 [Markdown](https://www.markdownguide.org/) 文件吗？能有多难？

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

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

## 环境是最大的诅咒

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

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

丝滑。完美。然后我把这个 Skill 拿给我的同事——一位**产品经理**。她没有 [Node.js](https://nodejs.org/)，没有 [pnpm](https://pnpm.io/)，git 也没装好。她只有**一台电脑、一个浏览器、和一个 [GitHub](https://github.com/) 账号**。

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

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

所以我们设计了**三层访问机制**——有本地仓库用本地仓库，有 git 用 git，什么都没有就用 [GitHub API](https://docs.github.com/en/rest)，只需要 `curl` 加一个 Token。**三层里最低的一层，只需要一台能打开浏览器的电脑。**

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

## 预览的困境

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

我们想了很多方案：

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

最后我们找到了一个有点"野路子"的方案——让 Agent 从 GitHub 仓库**读取博客的真实源码文件**，把文章 Markdown 转成 [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML)，套进博客的真实样式里，生成一个**独立的 `preview.html`**，然后用浏览器打开。

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

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

这是第二课：**当正规路径走不通的时候，退一步想——用户最终需要的不是工具本身，而是工具的结果。** 用户不需要 [Astro dev server](https://docs.astro.build/en/reference/cli-reference/#astro-dev)，用户需要的是"在浏览器里看到文章长什么样"。

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

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

在早期版本里，我把很多东西**写死**在 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，不妨问自己一个问题：

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

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