1. “agent-skills”到底是什么先说一个我最近复盘项目时经常想起的场景。接手某跨平台系统的时候代码库里有一个叫skills的目录。当时团队里没人能说清楚它是干嘛的有人说是放文档的有人说是给测试脚本留的还有人直接说“不知道反正不能删”。直到后来我拆开看了一遍才发现这个目录里装的不是脚本不是配置而是一整套“让 AI 助手知道该怎么做事情”的描述文件。这个目录就是“agent-skills”。如果你接触过 LLM Agent 或者最近在折腾 AI 工作流你大概率已经遇到过类似的概念。把agent-skills拆开看它就是“给 Agent 用的技能说明书”。里面往往是一组 Markdown 文档配上少量示例代码或 JSON 结构告诉模型某个任务该怎么做、有哪些边界条件、输出格式是什么、失败了怎么重试。换句话说它不是让 AI“会写代码”而是让 AI“知道在哪个场景下调用哪段代码、按什么规则执行”。这东西能解决的问题很实际大模型记住了很多知识但它不知道你项目的约定、不知道你数据文件放在哪、不知道你接口返回的错误码含义。你可以在系统提示词里塞一大堆说明但很快就会被长度限制打回原形。而agent-skills这种方式等于把知识外置了——要用的时候再告诉模型用完再收回来干净利落。适合谁来参考我建议三类人认真看一下一类是正在把大模型接入业务系统的开发者另一类是负责项目知识沉淀的技术负责人还有一类是纯粹想优化自己 AI 工作流效率的进阶玩家。这篇文章我会从目录结构、文件设计、实操流程到避坑经验挨个讲清楚尽量做到看完就能照着改、照着建。2. 从目录结构到设计意图为什么是“技能”而不是“工具”2.1 skill 目录通常长什么样先给一个典型的agent-skills目录结构参考这是我从一个模拟项目 X 里整理出来的简化版agent-skills/ ├── README.md ├── web-scraper/ │ ├── SKILL.md │ ├── examples/ │ │ └── demo_input.json │ └── scripts/ │ └── fetch_page.py ├──>--- name: web-scraper description: 适用于静态页面数据抓取支持登录态与非登录态场景 version: 1.2.0 tags: [scraping, html,>