最近将之前一些沉淀的工具脚本整理成 Skill，以方便在 Agent 中使用。这个过程中，我越来越明显地感受到：一个 agent skill 和一个普通的 Python 项目，虽然表面上都可能包含脚本、配置、依赖和文档，但它们解决的问题并不一样。

Agent 和 Skill 出现之前，成熟的程序员本来就知道要整理可复用脚本、抽公共模块、维护自己的工具箱。 所以这里不是在讲“过去不会管理脚本，现在才会”，而是在讲一个新场景出现之后，原来那套工程习惯需要怎么自然延伸。

Python 项目沉淀能力，Skill 组织能力。

举个例子

这次整理的项目叫 mp-weixin-skill。它要做的事很具体：把博客内容整理成适合公众号发布的形式，再自动化地送进公众号编辑器。

这个 skill 不是从零写出来的。它从之前的一个完整的自动化项目里抽出一部分能力，再重新放进 skill 语境里。这个背景很关键，因为这里真正容易出问题的地方，不是“代码能不能跑”，而是“哪些东西应该继续作为通用能力沉淀，哪些东西只是为了让 agent 正确调用”。

如果这条线不清楚，就很容易一路复制，把历史项目里的内容原样搬过来，最后把旧项目的历史包袱和新场景的调用要求耦合在一起。

一个仓库，两类代码

项目一展开，就会发现里面天然混着两类内容。

一类明显偏 skill：

• SKILL.md
• main.py 里贴近命令入口和调用语义的部分
• scripts/install_skill.sh
• README.md、TODO.md 这类说明怎么安装、怎么使用、怎么演化的文档

这些内容回答的是：agent 什么时候该调用它，用户大概会怎么描述这个需求，这个能力如何安装到运行环境里，遇到登录或人工确认时应该怎么处理。

另一类更像可复用的 Python 能力：

• src/wechat_postprocess.py 里的 HTML 后处理
• src/blog_publish_pipeline.py 里的博客发布与公众号粘贴链路
• scripts/common.py 里的公众号接口调用和登录态处理

这些内容回答的是：内容怎么处理，流程怎么跑，接口怎么调，状态怎么管理。它们今天当然可以先放在 skill 仓库里，但未来如果我要做一个“博客转企微文档”的 skill，或者一个“内容审阅”的 skill，大概率不应该再复制一份。

也就是说，skill 仓库里可以暂时容纳这两类东西，但心里要知道它们不是一类东西。

这种逻辑上的两栖性，在物理层面的表现就是：安装目录和源码目录必须严格隔离。

如果直接在 ~/.agents/skills/... 下面改代码，短期很方便，长期几乎一定会乱。因为这个目录本质上是运行时安装位置，不应该承担源码源头的职责。一旦你在安装目录里修一点，在临时目录里再改一点，后面再换一台机器，很快就会失去一个明确的 source of truth。

所以这次我把工作副本放在 ~/work/mp-weixin-skill，再用 symlink 接到 ~/.agents/skills/mp-weixin-skill。这样做不是为了讲究目录整洁，而是为了明确：前者才是源码源头，后者只是安装位。

这个边界一旦清楚，后面无论是提交 git、换机器，还是把通用部分往外抽，都会顺很多。

怎么判断代码该放哪

如果说得更直接一点，Python 项目更像可复用核心层：关心模块抽象、函数边界、依赖管理和长期复用。Skill 更像Agent 接入层，关心使用语义、交互流程、任务编排和触发场景。前者主要负责“怎么做”，后者主要负责“怎么用”。

最实用的判断方法是：看这段代码服务的是“调用语义”，还是“复用语义”。

如果它主要负责告诉 agent 应该怎么调用、怎么提示用户、怎么串联步骤，那它更像 skill 的一部分。如果它脱离当前 skill 之后，未来仍然很可能被别的 skill 复用，比如 HTML 后处理、正文抓取、登录态管理、Markdown 到 HTML 的转换流程，那它就更像 Python 项目里的公共能力。

像 export_cookies.py 就很典型。它今天属于公众号 skill，因为它服务的是“这个 skill 如何拿到登录态”；但它底层那套浏览器自动化、cookie 导出、状态刷新的机制，未来又完全可能被别的微信系自动化场景复用。

所以 skill 真正新增的，不是“终于开始写可复用代码”这件事，而是在原有工程能力之上，又多了一层面向 agent 的组织要求。

新场景里别迷失方向

agent 和 skill 带来了新的调用方式、新的交互约束和新的组织形式，但一个成熟程序员原本就知道该如何整理脚本、抽公共能力、维护工具资产。现在要做的，不是否定那套经验，而是把它自然延伸到新的上下文里。

所以回到最开头那句话：Python 项目沉淀能力，Skill 组织能力。

如果这个边界始终是清楚的，skill 就不会随着一次次临时迭代而失控，反而会越来越像一个真正可复用、可迁移、可进化的个人工具体系。