你有没有想过，为什么同一个模型，换个用法效果天差地别？我之前在接一个自动化项目时，让agent去做数据分析、出报告、再画图表，结果它老是卡在中间环节，要么步骤缺失，要么输出格式不对。后来我把整套流程拆成一个个可复用的skills，问题当场解决，整个开发周期缩短了大概四成。
如果你也在折腾agent开发，或者正在研究前端开发skills、Claude agent skills这类东西，那你应该能理解我说的痛点：光有工具和模型不够，真正让agent“干活靠谱”的，是把你脑子里的方法论，变成它能照做的技能包。这篇内容我不打算讲太多虚的，就围绕“agent-skills”这件事，从底层逻辑、架构设计、实操落地到常见的坑，完整拆一遍。不管你是刚接触agent的新手，还是在找skills推荐、想搞明白harness和agent区别的老手，这篇应该都能给你一些实在的参考。
1. 内容整体设计与思路拆解
1.1 从工具到技能：agent能力的演进
先说一个最基础的问题：agent和普通的自动化脚本到底差在哪？我自己的理解是，脚本是写死的“如果A就做B”，而agent是带着目标和约束，自己决定“怎么从A到B”的个体。但问题随之而来——如果什么都让它自由发挥，它大概率会在路上走偏。你给它一个目标“分析这个月的销售数据”，它可能先花半天构造一个根本不需要的函数，或者把结论写成一篇散文而不是结构化报告。
这时候就要用到skills了。简单说，skills是把一类高频率、有固定套路的工作，预先封装成agent能理解的“操作手册”。它告诉agent：遇到这类任务时，不要自由发挥，按这个步骤来，每一步用什么工具、输出什么格式、注意什么边界条件。用生活里的话讲，agent本身就像一个刚毕业的新人，能力不差但没经验，skills就是你把老师傅几十年的作业流程写成了SOP，新人照着干，能少走很多弯路。
从行业趋势看，整个AI应用开发圈子里，对skills的重视程度越来越高。很多人一开始盯着模型参数量、上下文窗口大小，后来发现真正决定业务落地效果的，恰恰是这些外围的结构化能力。毕竟你不可能每次都把几百页的操作规范写进prompt里，那样既浪费token又容易信息混乱。把套路沉淀下来，让agent在需要时主动调用，这才是一个工程化的思路。
1.2 Skills的核心构成：元数据、指令与工作流
我自己在做skills开发时，习惯把一个skill拆成几个固定部分。第一个是元数据，类似身份证信息，包括这个技能叫什么、用来干什么、在什么场景下触发、依赖哪些工具或前置条件。元数据写不好，后面agent匹配技能时大概率会选错，或者压根不选。
第二个是指令主体，这是核心中的核心。它不是一两条命令，而是一套完整的执行逻辑：先做什么、后做什么、中间如果出现某种情况该怎么分支处理、最终输出要达到什么标准。我会尽量在里面写清楚“输出格式”和“边界条件”。比如做一个“生成项目周报”的skill，我会写明：必须包含本周完成事项、数据对比、风险点、下周计划四个模块，每个模块控制在多少字以内，数据来源字段是哪些。指令越明确，agent的执行结果越可控。
第三个是参考工作流或示例。有时候光说“按规范输出”，agent不一定理解“规范”长什么样。给一个或几个具体的输入输出范例，它会学得快很多。我通常会在skill里内置一个小型的example，尤其是那种格式要求严格的输出，比如JSON结构、markdown模板、API请求报文，效果立竿见影。
1.3 Skills与Tools、Prompts的边界划分
网上关于agent的工具、提示词、技能的讨论特别多，很多初学者容易混淆。我简单说一下我的理解。Tools是最底层的原子能力，就是一个函数或接口，agent可以调用它去执行一个具体动作，比如“发一封邮件”“查询数据库”“调用某个API”。它是“手”，负责执行。
Prompts是对话层面的引导，告诉agent“你现在是什么角色”“这次任务的目标是什么”。它是“大脑”的短期指令，每轮对话都可以不同，灵活但缺乏沉淀。
Skills则介于两者之间，它是“一套完整的肌肉记忆”。它可能描述：什么时候该用哪个tool、用完之后怎么判断结果、下一步又该做什么。它甚至可以包含多个tools的组合编排。我见过很多团队把prompt越写越长，最后几千字塞进上下文，效果却越来越差，就是因为没有把可复用的流程抽象成skills。prompt每次重新讲一遍，自然不稳定；skill只需要被引用一次，agent就按章办事。
所以我的建议是：凡是稳定、高频、有明确步骤的任务，一律沉淀为skill；凡是临时、需要灵活应变的对话引导，才放在prompt层。这个边界划清楚了，你的agent项目才有扩展性。
2. 核心细节解析与实操要点
2.1 一个典型的Skills目录结构
我不会一上来就讲什么高深理论，直接展示一个我实际在用、也推荐大家参考的skills目录结构。这不是唯一标准，但经过多个项目验证，适配度很高。假设你的agent项目根目录下有个skills/文件夹，里面按命名清晰的方式组织每个技能：
skills/ ├── weekly-report/ # 技能目录名，建议用kebab-case │ ├── SKILL.md # 核心指令文件，agent会先读这个 │ ├── examples/ │ │ ├── input-sample.md │ │ └── output-sample.md │ └── scripts/ │ └── analyze.py # 可选，技能内附带的辅助脚本 ├── code-review/ │ ├── SKILL.md │ └── examples/ └──>
