企业官网建设流程全解析

刚看到“agent-skills”这个词的时候，我第一反应是又一个概念包装。毕竟从“Prompt工程”到“Agent工作流”，这两年AI圈造词速度比代码迭代还快。但实际用下来，我得承认这个词背后确实是AI Agent开发绕不开的一个环节，甚至可以说它把Agent从“会聊天的百科全书”往前推了一大步——让Agent真正具备“可复用、可组合、可沉淀”的专业技能。

如果你也在做AI Agent相关开发，尤其是不满足于简单对话、想让Claude这类模型替你完成具体工作流的开发者，那这篇东西就是写给你看的。我会用实际踩坑经历，把Agent Skills是什么、它的核心机制长什么样、怎么在Claude Code里跑通一套自己的技能，以及我在实际使用中遇到的坑和解决办法，一次讲透。不整那些虚头巴脑的概念，全是能直接落地的经验。

1. Agent Skills到底是什么：一个没有新语言的“技能包机制”

1.1 先厘清几个名字，别被概念绕晕

先说点背景。Anthropic在2025年10月发布了Agent Skills，严格说它不是一个新的独立产品，而是Claude系列模型和Claude Code这个开发环境的一项原生能力扩展。你可以把它理解成：给Agent装上一套“可拔插的专业技能包”，每个技能包是一个带SKILL.md说明文件的文件夹，里面包含了完成某项任务所需的指令、参考代码、说明文档甚至一个小型脚本工具。

举个例子你就懂了。假设你经常需要Claude帮你处理PDF文件，传统做法是在System Prompt里塞一大段“你是一个PDF处理助手，遇到PDF要调用xxx工具，处理步骤是……”。这个做法的问题在于：提示词会越堆越长，模型注意力被稀释，遇到复杂的、多步骤的任务，效果直线下降。Agent Skills的做法是：你预先写一个“PDF处理技能包”，里面明确写好“这个技能负责什么、处理的步骤是什么、有哪些注意事项”。当用户提出“帮我处理这个PDF”的需求时，Claude会自动加载这个技能包，在对话上下文中注入对应的指令和知识，再按里面的流程执行任务。

所以Agent Skills本质上解决的是Agent“什么都会一点，但什么都不精”的问题。它不是教模型新的通用能力，而是给模型一本“针对特定场景的操作手册”，需要用的时候翻开来，用完了合上，不占用平时的上下文空间。

1.2 为什么Agent开发会卡在“什么都行、什么都不精”

我最早做Agent的时候，特别迷信大模型的“泛化能力”：觉得Claude知识面那么广，啥任务都能干，那我只需要把System Prompt写好，把工具挂上，就完事了。实际做上两周就发现根本不是这么回事。

举一个我自己的真实例子。有段时间我做了一个财务对账Agent，需要读取银行流水、分类账本，然后按规则生成对账报告。我把所有对账规则直接写在System Prompt里，为了让模型能准确识别各种业务场景，我写了将近3000字的提示词。最开始测着还行，但随着规则越来越多，模型开始“忘事”：有时候记住了汇率换算是怎么处理的，却忘了日期格式校验怎么写的；有时候前后矛盾，明明同一个规则，换个场景表述就执行错了。

后来我才明白，这背后有一个很现实的技术限制：上下文窗口虽然越来越大，但模型对超长提示词的注意力容易分散，而且所有指令都混在一起，优先级完全拉不开。MCP（Model Context Protocol）解决了“模型怎么调用外部工具”的问题，但它管不着“调完工具之后，一整套复杂工作流该怎么做”这件事。Agent Skills恰恰补上了这一层：把复杂的专业流程从冗长的提示词里抽离出来，做成独立的、按需加载的知识包。

当然，Agent Skills并不是要取代System Prompt或者MCP，三者是配合关系。System Prompt定义Agent的“人设和基本行为准则”，MCP负责“触达外部世界”，Skills负责“局部专业领域的深度操作流程”。这就像一个人，System Prompt是他的性格，MCP是他的手和脚，Skills是他的职业资格证书和操作手册。

2. 核心机制拆解：从组织形态到运行原理

2.1 Skills的三层组织形态，先搞清楚你玩的是哪个

官方对Agent Skills的说明里，技能分为三个层面：系统级技能、隐藏技能和用户代码级技能。这三个层面的区别在于技能存放的位置和是否在Claude Code仓库中包含。

系统级技能是Claude Code自带的那些技能包，你不需要额外安装，直接就能用。比如Claude内置的文档撰写能力、PDF处理能力等。隐藏技能是经过性能验证的依赖缓存技能，在上下文窗口的某些部分自动加载，不需要用户手动触发。用户代码级技能就是你自己创建的技能包，存放在项目目录的.skills文件夹里，这是大家用得最多的一种，也是我下面要重点讲的。

这里面最值得理解的点是：Agent Skills的组织方式和传统编程里的“模块化”非常像。它没有发明一套新语言，就是用标准的文件系统结构来组织能力。一个技能就是一个目录，目录里必须有一个SKILL.md文件作为入口说明，其他辅助文件可以随意放，比如scripts文件夹放脚本、references文件夹放参考文档、assets文件夹放模板资源。这种设计最大的好处是低学习成本——任何一个Git仓库都能直接变成技能包，版本管理也是现成的。

2.2 一块技能怎么运转：三种加载方式都意味着什么

我刚接触时最困惑的一点是：技能到底是什么时候、怎么样被模型“知道”的？后来我用自己的技能测试了几十次，才完全摸清它的脾性。

技能加载主要有三种方式。第一种是隐藏上下文（hidden context），也就是说技能一直在上下文窗口的“暗处”待命，不占用用户可见的上下文空间，但模型始终知道它们在。这种机制特别适合放那种“你随时可能用但不用时不想被干扰”的技能。第二种是自动触发，这是最关键的一种：Claude接受到用户消息后，会先走一个“技能匹配”的过程，它看到用户的需求和某个技能的描述吻合，就会自动把该技能加载进上下文。第三种是用户手动指定，用户直接在回复中指定要使用哪个技能，强制加载。

我实测下来的感受是，“自动触发”这个环节做得比较克制，Claude不会一下子把所有技能全加载进去，而是像一个聪明的图书管理员，先看你问什么，再去书架取对应的书。但它也有限制条件：在你的回复中，它会尝试将你的需求与所有可用技能描述进行语义匹配，如果你的技能描述写得词不达意，它就可能该触发的时候不触发。这一点在后面实操部分我会详细展开。

2.3 Skills真正改变的东西：权限设计和失败机制

说完了加载方式，再来看一个我认为Agent开发中最容易忽视、但也最关键的机制：权限。做过Agent的人都知道，让模型自主干活，最怕的就是它乱操作。Agent Skills在这块做了一个很聪明的设计：你可以在技能目录中声明“这个技能需要哪些权限”，这些权限细粒度到麦克风、相机、文件系统、代码执行等。

我当时实际体验最明显的一个点是：如果你没有给Claude配置tools权限，技能运行时遇到需要工具的场景，就像“拿着菜谱进了没有锅的厨房”，根本跑不起来。反过来如果你给了过大的权限，技能可能自作主张执行不该执行的代码。所以我的原则是：技能能不用权限就不用权限，必须要用的，尽量限制在技能目录自身范围内。

另外还要提一点，很值得玩味的设计是Agent Skills在出错时不会默默吞掉错误。我跑技能的时候，偶尔会故意制造一些异常情况测试它的“自觉性”，发现如果某个步骤和预期结果不符，Claude会主动停下来告诉用户“这一步结果异常，我建议中止”。这种“Fail loudly”的设计哲学，在一堆追求“静默成功”的AI框架里，我觉得是更负责任的一种做法。做Agent开发，最怕的不是出错，而是错了还不知道，最后给用户端出一份“看起来正常其实一塌糊涂”的结果。

3. 一把梭实操：在Claude Code里跑通一份自己的技能

3.1 环境准备与目录结构

空谈机制没有意义，直接上手才是最快的理解方式。我这里以Claude Code为例，实际操作一遍如何创建一个自定义技能。

首先你需要在本地准备好Claude Code，我用的是Claude Code 2.0.19及以上版本，官方要求的最低版本是2.0.19。安装方式不复杂，官方终端命令装一下就行，具体命令我就不铺开写了，安装完成之后确认一下版本号，确保版本够新，因为低版本根本不识别.skills目录。

装好之后，在项目根目录创建一个文件夹，命名为.skills，注意前面有个点，是隐藏文件夹。然后在里面为你的每一个技能单独建一个子文件夹，比如我要做一个“PDF处理技能”，就建.skills/pdf-tool/。这个文件夹本身就是技能的安装单位，整个文件夹连同里面所有文件一起，就是一份完整的Agent Skill。你也可以把技能文件夹放到用户级目录的全局位置，实现跨项目共享，但在项目里测试时建议先放项目目录，迭代速度快。

3.2 SKILL.md怎么写才能被Agent“看懂”

一个技能能不能发挥作用，90%取决于SKILL.md写得怎么样。SKILL.md是这个技能的说明书，Claude会基于这份说明书来判断“什么场景触发它”以及“触发后按什么流程执行”。我踩了很长时间的坑，总结下来SKILL.md有四个核心写作要点。

第一，技能描述（description）要写在YAML frontmatter里。frontmatter格式就是每个SKILL.md文件最开头的两行，被---包起来。描述要通俗、准确，直指用户意图，别写得太技术化。比如描述“用于将PDF文件转换为txt文本文件”，就比“包含PDF处理相关函数的工具包”更容易被正确触发。理由很简单：Claude是通过对比“你的描述”和“用户输入的意图”来做语义匹配的，描述写得越贴近用户口语，命中率越高。

第二，触发指令和参数要写明确。你在这个技能里要完成什么任务，需要哪些输入参数，参数格式是什么，都要写清楚。我的经验是参数越具体越好，比如“输入：PDF文件路径（必填），输出格式（可选，默认为txt）”，这样Claude就不用在执行时猜测你要什么。

第三，工作流要拆解到可执行的步骤。技能的正文通常包含一段清晰的操作步骤，告诉Claude用什么工具、按什么顺序、处理什么。我在实际写的时候，深切体会到文档中提到的“把技能拆成具体的步骤，而不是笼统的目标”这句话有多重要：“把PDF文件转换为文本”和“用工具A提取第2页内容，用工具B重排文本格式，用工具C压缩文件”完全是两种效果。前者的执行结果不可控，后者基本能稳定复现。

第四，每个技能只负责一个小任务，别贪多。我一开始犯的错是把“PDF转文本”“PDF提取表格”“PDF合并拆分”全塞进一个技能里，结果就是Claude经常加载了技能却“不知道该用哪一段”。后来我把它们拆成三个独立技能，一切清爽了。这也和官方提倡的粒度一致：按任务或动作划分，而不是按工具或对象划分。

3.3 一个完整示例：使用Qwen进行摘要的个人技能包

光说规则不过瘾，我直接贴一个我当时写的技能例子，正好可以看到一个实际运行的技能长什么样。这个技能做的是“使用Qwen进行摘要”，整个技能打包进一个叫qwen-summarizer的文件夹。

文件夹结构是这样的：

.skills/ ├── qwen-summarizer/ │ ├── SKILL.md │ ├── scripts/ │ │ └── qwen_summarize.py │ └── references/ │ └── user_manual.md

SKILL.md里面，frontmatter加上核心指令，我是这样写的：

--- name: qwen-summarizer description: 使用Qwen模型对文本内容进行摘要提取，输入一段文本，返回简洁的摘要结果。 ---

然后在正文部分，我会写清楚触发条件：“当用户要求对给定的文本或文档进行摘要时，使用此技能”，以及详细步骤：先读取用户提供的文本内容，再调用scripts/qwen_summarize.py脚本，该脚本使用Qwen模型对文本进行摘要，最后将生成的摘要呈现在回复中，并显示摘要所基于的原始文本长度和摘要率。

这个技能用起来的效果是：当我给Claude一段长文本并说“用qwen-summarizer给我总结一下”，它就会加载这个技能，然后到scripts文件夹去调用Python脚本，最终输出一段结构化的摘要。整个流程完全在项目目录内闭环，不需要额外配置API密钥之外的东西。

顺带说一句，技能里面的文件不一定非得是脚本，你也可以放模板、放参考文档、放业务规则清单。有一次我做一个行业报告自动生成技能，往references文件夹里放了三个PDF范本和一套撰写规范，效果比我在SKILL.md里写上千字还管用。原因很简单：Claude处理长文档的能力远强于在Prompt里塞长指令，而且文档可以按需读取，不占常驻上下文。

3.4 我的一些通用经验：怎么写技能才顺手

写多了之后，我强烈建议先看官方文档中的“Rules for good skills”部分，它提到的几个要点我在实践中几乎全部验证过：

• 在技能中提供高质量的工作流程，并分解为具体步骤。
• 大多数技能不应该询问用户过多的细节，而是要尽力推断和智能默认。该做调查就做调查，该求助就求助，但别让用户当“配置向导”。我发现新手写技能特喜欢开场就问“请提供文件路径、输出格式、页码范围……”，体验很差。Agent自己能判断的事情，别抢用户的活。
• 从最少的上下文内容开始，根据错误日志再逐步增加或修正，不要一上来就堆一大堆指令。
• 每个技能应该独立于其他技能，专注于一个明确的意图。
• 交互式工具（如逐字确认、等待用户输入的脚本）要谨慎使用。我在一个自动外呼技能里放了个需要人工按Y确认的脚本，结果每次跑都卡住，后来改成超时自动跳过才好。

你也可以直接把技能视为一个小的“API接口”，输入输出清晰定义好，细节实现都藏在scripts和references里。这样技能的可维护性、可复用性都会提升不少。

4. 常见问题与排查技巧实录

4.1 技能不生效，八成是这三个原因

我自己在开发和使用技能的时候，遇到的问题不少，但最典型的就三类，基本覆盖了绝大多数“技能不生效”的场景。

第一类，目录结构不对。技能必须放在.skills/技能名/SKILL.md，有些人习惯性地把SKILL.md直接放.skills根目录下，或者技能名里带了中文和特殊字符，Claude解析不出来。我遇到过明明文件都建好了，但模型完全“看不见”这个技能，一查发现是技能目录名带了个空格，解析直接失败。目录命名建议全小写、用连字符连接，别带空格和特殊字符。

第二类，技能描述和用户意图对不上。前面说过，自动触发依赖语义匹配。如果你的description写的和用户说话的方式差太远，模型就不知道什么时候该加载它。比如你把一个“发票信息提取”技能描述成“基于OCR技术的文档结构化信息抽取服务”，用户说“帮我把发票上的金额抬头和税号提取出来”，匹配难度就会大很多。当然这不是绝对不触发，而是触发的概率和稳定性会降低。

第三类，技能参数缺失或不完整。技能正文里写了“要调用脚本”，但没写清楚脚本需要的参数是什么，模型就只能在运行时自己猜，效果自然不可控。我修复方式是在SKILL.md里给每个脚本写清“调用格式”和“参数说明”，能用示例尽量给示例，Claude照猫画虎的能力比你想象中强很多。

4.2 排查思路：先把稳定性抓死，再谈效果优化

遇到技能不工作时，我的排查顺序基本是固定的，分享给你们直接抄作业。

第一步，确认技能有没有被加载。这是最容易被忽略的环节。我的做法是在对话里直接问Claude“你现在加载了哪些技能”，它能回答出来就说明加载成功。如果它压根不接这个茬，多半是技能组织或描述有问题，得回头查目录结构和SKILL.md的写法。

第二步，确认执行环境是否正常。看技能依赖的脚本有没有权限、路径对不对、外部依赖装了没有。比如我要拿脚本调一个外部模型接口，但是API环境变量只配置在系统的~/.bashrc里，而技能是子进程运行的，很多情况下它读不到这个环境变量，所以最好在技能里写清楚“请先通过python-dotenv加载.env文件，再读取API密钥”。

第三步，做最小化测试。把技能缩减到只剩最核心的一步，跑通了再逐步增加复杂度。我经常用这种“二分法”定位问题：拿一个最简单的输入测，如果失败了，说明基础流程有问题；如果成功了，再一步步添加边界条件和异常处理。这个思路放在Agent技能调试上依然好用，别一上来就测完整流程，那样出了问题根本不知道是技能描述的问题还是脚本的问题还是权限的问题。

4.3 常见问题速查表

我把这段时间遇到的典型问题和对应的解决思路整理成了一张表，遇到问题可以先从里面找找答案。

这个表格不算完整，但覆盖了我见过的大多数问题。如果你遇到不在表里的情况，建议回退到“最小化测试”，往往很快就能定位。

5. 技能之外：你也可以写出属于自己的“技能书”

5.1 两个我亲测好用的落地方向

理论讲完了，实践也说了一堆，最后我想分享两个你可能马上就能上手的应用方向。

第一个方向是把重复性工作写成内部审批技能。我们团队每周都要整理项目进度、汇总风险项、形成周报。以前用提示词临时让Claude总结，每次都要重新交代背景和格式。现在我把“周报生成”做成了一个技能，里面写清楚了周报的章节结构、数据来源表格、以及可能遇到的报表复盘格式要求。每次只需要把本周的散碎记录丢给它，技能自动按规则产出初稿。这本质上就是把工作方法论沉淀进了技能里，换谁来都能输出统一风格的结果。

第二个方向是个人自动化技能。我自己做了一个“邮件分诊”技能，它读取收件箱里未读邮件的主题和正文，按照我设定的几个维度（是否紧急、是否需要会议、是否可归档）进行分类，再按我的语气模板草拟回复。这个技能的SKILL.md只有一百多行，但效果比我以前挂在System Prompt里的几十行规则稳定得多，细节处理都在scripts里，规则想改就改，不用每次对话都重新“教”它一遍。

这两个例子背后是同一个逻辑：技能的本质，是把“你心里那套默会知识”显性化。你天天做的工作，你最清楚里面的门道和步骤，把那些“我知道但我从没写下来”的流程，写成Agent能读懂的说明书，它才能真正帮你省时间。

5.2 到底该用Skills，还是继续用MCP和Prompt

很多朋友会纠结Agent Skills、MCP、System Prompt之间的边界。我给个简单的选择标准，可能不完全严谨，但足够日常使用：

还是拿我那个财务对账Agent举例，身份设定、输出语气在System Prompt里写；金融机构API的接入走MCP；而“怎么把流水、账本一步步变成对账报告”这段最复杂的流程，则做成了独立技能。三者配合默契，职责边界清晰，调试起来也顺——哪里出问题就改哪里，不会牵一发动全身。

5.3 一点心态上的建议

最后想多聊两句。我见过一些人一接触Agent Skills就觉得“又一个新东西，学不动了”。但说实话，Agent Skills学习的成本和收益比，比我见过的绝大多数新工具都划算。它不引入新语言、不需要新框架，就是文件夹和Markdown文件，你在AI Agent开发中积累的大部分知识都能直接迁移过来。与其把它当成一门新技能去学，不如把它当成一种“整理自己工作方法”的契机。

我自己的感受是，每次写一个技能，对我本职工作的理解也会加深一层——因为要写清楚一个流程，我必须先想清楚每个环节的输入、输出和判断逻辑。这本身就是一种对自身工作的复盘和提炼，Agent Skills给了我一个绝佳的理由去做这件事。

所以我的建议是：别急着追新概念，先把你最常做的那件重复性工作，认认真真写成一份技能，哪怕只有一百行。等它跑通了，你就真正理解Agent Skills到底是怎么一回事了。之后的所有扩展，都是在这个基础上的自然生长。