企业官网建设流程全解析

1. agent-skills 到底在解决什么问题

我在过去几个月里密集折腾过 agent-skills 这个方向，从最初只给智能体写一段提示词就跑，到后来把技能做成可注册、可复用、可组合的模块，整个过程的体验差距非常明显。说白了，agent-skills 要解决的并不是"让模型更聪明"，而是"让模型更听话、更能干活"——把一次性的对话式 AI，变成一套真正能接进业务流程的执行系统。

先解释一个容易混淆的点：skills 不是插件，也不是单纯的工具函数。插件通常是一段固定逻辑，工具函数关注的是"能被调用"；而一个 skill 的完整定义是：一组自然语言指令 + 必要的代码/配置 + 明确的输入输出约定 + 触发条件，告诉智能体"在什么场景下、用什么步骤、产出什么结果"。你可以把它理解成给实习生写的一份作业手册：不是告诉他"你会做报表"，而是告诉他"报表要按这个模板、数据从这几个表取、异常情况这样处理、交稿前先自查三遍"。

这个方向最近热度很高，核心原因是：当一个基于大语言模型的应用从 Demo 走向真实业务时，模型的随机性、窗口限制、知识截止日期会轮番折磨你。而技能化封装，是目前被验证过最稳的一层缓冲。我们团队在客服助手、数据分析、内部知识库三个场景里实际跑了 agent-skills 的方案，效果比纯提示词工程稳定得多——技能命中率、执行正确率、后期维护成本，这三个指标都明显改善。

说得直白一点：如果你只是拿智能体聊天、写文案，那 skills 对你可能有点杀鸡用牛刀；但如果你要让它去操作浏览器、处理报表、调用内部 API、按流程审批，或者做任何一件"错了要担责任"的事，那就必须技能化。这篇文章我会从设计原理讲到代码实现，再讲我踩过的坑，最后给出一套可以直接抄作业的技能定义模板。

适合看这篇文章的人：正在做 Agent 应用开发的工程师、想给团队落地智能体工作流的负责人，以及刚入门 LLM 应用开发、想知道 function calling 之外还有什么玩法的小伙伴。我会尽量避开空泛的架构图，直接讲怎么落地。

2. Skill 的结构设计与核心原理

2.1 SKILL.md 与技能描述：为什么自然语言比代码更重要

一个 skill 最容易被低估的部分，是它开头的自然语言描述。很多人写技能时喜欢一上来就写实现代码，这是最大的误区。模型决定"现在该不该用这个技能、怎么用"，靠的并不是代码逻辑，而是你写在 SKILL.md 里的那几段话。

我见过一份写得非常糟糕的技能描述，原文大意是"这是一个网页抓取工具，输入 URL 输出 HTML"。听起来没什么问题对吧？实际跑起来模型根本不会主动调用它。原因就在于：模型无法从这种描述里判断"什么情况下应该用这个技能"。它不知道网页抓取的典型场景是"用户让我查一下某个网站的价格/新闻/公告"，也不知道已经拿到文本之后就不需要再调用。于是真正需要抓取时它忘了用，不需要时它反而频繁调用。

我的经验是，技能描述至少要包含四层信息：

• 技能定位：一句话说清楚这个技能负责哪一类任务。
• 触发条件：什么场景下必须用，什么场景下不要用。这一条是最容易被忽略的，但恰恰是它决定了模型会不会乱用技能。
• 输入输出格式：不要写"输入一个 URL"，要写"第一个参数必须是完整的 http(s) 链接，如果用户只提供了域名，需要先拼接 https://"。
• 注意事项：例如"抓取前先确认站点是否允许爬取""输出前去掉脚本标签""如果页面是动态渲染的，改用无头浏览器"。

我把这些内容放在 SKILL.md 的头部，后面的代码只负责执行。当模型读到 SKILL.md 时，它实际上是在做一次"阅读理解"——描述写得越结构化、越接近模型的表达习惯，技能被正确触发的概率就越高。这个结论不是我猜的，是我们用同一套技能改了三版描述之后对比出来的：第一版触发准确率只有 51%，第二版加了触发条件后到了 73%，第三版把输入输出格式具象化之后稳定在 88% 左右。

2.2 技能调用机制：Function Calling 与提示注入，两条路线怎么选

agent-skills 在执行层面有两条主流路线：一条是 Function Calling（工具调用），另一条是提示注入（把技能内容拼进上下文）。这两条路我都在生产环境里用过，各有各的适用场景。

Function Calling 的原理是：模型在生成最终回复之前，先输出一个结构化的"调用意图"，包含函数名和参数。然后由你的代码去执行真实逻辑，再把执行结果拼回给模型，让模型基于结果继续生成。Claude 的 tool use、GPT 的 function calling、以及各大开源模型的 tool call 能力走的都是这条路。

它的优势是精准：模型已经明确表示"我要调用这个函数"，参数也被严格约束了，不容易跑偏。劣势是：每多一把工具，推理的 attention 负担就会增加；而且如果工具太多，模型选错工具的概率也会上升。这就是为什么很多人发现"工具列表超过 10 个之后，准确率开始下滑"。

提示注入则是把整个技能的指令和示例直接拼到系统提示词里。这种做法的上限取决于上下文窗口，但好处是模型对技能的理解更"通透"——它见过技能里所有的细节，而不只是函数名加一句描述。我们团队在实际项目中用的混合策略是：高频且确定的功能走 Function Calling，低频但复杂、需要模型"理解"的技能走提示注入；对于一批和核心业务强相关的技能，两者同时上——先靠提示注入让模型理解全局，再靠 Function Calling 兜底执行。

这里有一个非常关键的实现细节：无论走哪条路线，技能的执行结果要格式化得足够干净。模型最怕的不是没有结果，而是结果里有大量无关信息。比如抓取网页时，如果直接把整个 HTML 扔回去，模型的注意力会被导航栏、脚本、样式表淹没。正确的做法是先本地做一轮清洗，把正文、标题、关键字段抽出来，用紧凑的文本结构返回。很多 agent-skills 项目做到最后，花在"结果清洗"上的时间比写技能本身还多。

2.3 参数设计与上下文窗口的权衡：技能不是越多越好

关于参数设计，我的原则是"少参数、短描述、分层注册"。很多人写技能时恨不得把十几个可选项全部暴露出来，结果模型每次调用都只填了最前面两个参数，后面的全部留空。这不是模型笨，是你给的认知负担太大了。一个设计良好的技能，参数尽量控制在 3 到 5 个以内，并且要给每个参数一个"默认行为"。

举一个实际问题：我有一个数据筛选技能，一开始定义了 8 个参数，包括数据源、过滤条件、排序规则、聚合方式、时间范围、输出格式、是否去重、异常处理方式。跑起来之后发现模型经常漏传参数，或者把一个参数的值填到另一个参数里。后来我把它拆成两个技能——"基础筛选"只管过滤和排序，"聚合统计"专门处理分组和汇总，每个技能只有 3 个参数，准确率一下就上来了。

上下文窗口的问题同样要重视。每个技能的描述、示例代码、指令规则都会占用 token。如果你注册了 30 个技能，哪怕每个技能平均只有 300 token，单是一次"技能清单"就要吃掉近一万 token——这个成本在长对话场景里会被反复放大。所以我在生产环境里做了两件事：第一，按业务场景分组，只加载当前场景相关的技能，而不是全部加载；第二，技能描述严格限制在 600 token 以内，能压缩的尽量压缩。实践经验是：一个场景下挂载 5 到 8 个技能是体验比较好、准确率也比较高的区间，超过这个数量，收益就开始递减了。

提示：如果你发现某个技能长期没有被触发，大概率不是模型的问题，而是它的描述太泛了。给它补上"必须用"的场景举例，准确率会明显提升。

3. 从零构建一个 Skill：目录规范、注册机制与依赖管理

3.1 技能目录的结构规范

我参考了不少开源项目的习惯做法，最终沉淀了一套自己的目录规范。一个完整的 skill 通常包含以下几个部分：

skills/ └── web-fetch/ ├── SKILL.md # 技能的"身份证"，模型主要读它 ├── run.py # 主执行脚本 ├── requirements.txt # Python 依赖 ├── examples/ │ ├── basic.json # 一个最简单的调用示例 │ └── edge-case.json └── assets/ # 静态资源、模板文件

SKILL.md 的头部有一个 YAML front-matter，用来声明元信息。这个设计思路跟很多文档生成工具类似，好处是便于程序化加载和索引：

--- name: web-fetch description: 抓取指定网页的正文内容，提取标题和正文文本，用于市场调研、信息查询等场景。 when_to_use: 当用户需要查看某个网页的信息、文章、公告、价格时。 when_not_to_use: 当用户已经提供了一段完整的文字，不需要再次获取网页内容时。 parameters: - name: url type: string required: true description: 需要抓取的完整网页地址，必须以 http:// 或 https:// 开头。 - name: output_format type: string enum: [text, markdown, json] default: text description: 输出格式，text 为纯文本，markdown 保留基本排版，json 输出结构化字段。 ---

这个名字和 description 会被模型直接读到，所以我反复强调：description 里要包含"当用户需要……时"这样的触发语义，而不是干巴巴地写"这个函数做什么"。这套写法参考了 Anthropic 关于 skill 设计的最佳实践，实测效果显著。

3.2 技能注册与加载：做一个轻量注册器

有了目录结构，接下来需要一套注册机制。我见过不少人把技能列表直接硬编码在系统提示词里，这种做法在技能数量少的时候可以，但一旦技能栈膨胀，维护成本就不可控了。我的做法是写一个简单的注册器，扫描 skills 目录下所有子文件夹，读取 SKILL.md 的元信息，生成统一的技能清单。

注册器的核心逻辑并不复杂，关键是要处理好两个问题：一是技能的排序，二是重复名称的冲突检测。

# registry.py import os import yaml from pathlib import Path SKILLS_ROOT = Path(__file__).parent / "skills" class SkillRegistry: def __init__(self, root: Path = SKILLS_ROOT): self.root = root self.skills = {} self._load() def _load(self): for skill_dir in self.root.iterdir(): if not skill_dir.is_dir(): continue manifest_path = skill_dir / "SKILL.md" if not manifest_path.exists(): continue with open(manifest_path, "r", encoding="utf-8") as f: content = f.read() # 简单的 front-matter 解析，生产环境建议用 python-frontmatter 库 meta = self._parse_front_matter(content) if meta.get("name") in self.skills: raise ValueError(f"duplicated skill name: {meta['name']}") self.skills[meta["name"]] = { "meta": meta, "dir": skill_dir, "content": content, } def _parse_front_matter(self, content: str): # 解析 YAML front-matter，略 pass def list_skills(self): return [s["meta"]["name"] for s in self.skills.values()] def get_skill(self, name: str): return self.skills.get(name) registry = SkillRegistry()

这个注册器还有一种很实用的进阶玩法：根据用户输入的问题，先用一个轻量模型（或者基于关键字规则）选出候选技能，只把候选技能的完整描述加载进上下文。这样就不需要把全部技能都塞给主模型了。这一步看似简单，但对成本和准确率的提升非常明显。

3.3 依赖隔离：每个 skill 单独一套环境

技能多了之后，一个很现实的问题是依赖冲突。技能 A 需要 requests 的某个版本，技能 B 需要 httpx 的另一个版本，如果全部装在同一个 Python 环境里，迟早要炸。我在真实项目里就遇到过：装了技能 B 之后，技能 A 的请求突然开始超时，排查了半天发现是 urllib3 版本被顶掉了。

后来我采用的方案是：每个技能使用独立的虚拟环境，或者至少用容器去跑技能脚本。具体到代码层面，主进程通过 subprocess 调用技能脚本，而不是直接 import 技能模块。这样虽然会有一定的进程间通信开销，但换来了极强的隔离性。

一个折中方案是：把技能按"域"分组，比如网络抓取类共享一个环境，数据分析类共享另一个环境。实际运维下来，两到三个隔离环境足够覆盖大多数场景，也不需要为每个技能都开一个虚拟环境那么重。

3.4 技能描述的质量检查：先用模板，再凝练

在我把这些经验整理成文档之后，团队里新来的同事最常问的一个问题是："我到底应该怎么写 skill 里的自然语言部分，才能让模型正确触发？"

我给的回答是：先写啰嗦版，再浓缩。不要一上来就追求精炼——精炼的前提是把所有该有的信息都覆盖完整，如果你本身就写不全，那精炼只是把残缺变得更好看而已。我总结了一套最少内容清单：

• 这个技能解决什么问题，以及它在业务流程里的位置。
• 什么信号出现时，模型必须主动调用它。
• 什么信号出现时，模型不应该调用它。
• 每个参数的合法取值，以及不传时的默认行为。
• 一个最小可跑通的输入/输出示例。
• 输出结果的格式要求，以及返回给模型前应该做的清理。

写完这六项之后，再根据自己的经验把冗余的修饰词删掉，把不必要的铺垫砍掉。等到模型实测触发准确率上去了，再考虑压缩 token 的问题。记住：准确率永远优先于 token 成本，在准确率还没达标时谈优化，是本末倒置。

注意：不要为了节省 token 把技能描述写得太"诗意"。模型不是人类读者，它需要的是结构清晰、语义明确的指令。那些看似高深的抽象描述，只会让模型不知所措。

4. 实战：让 Agent 学会三个高频技能

4.1 技能一：网页正文提取

这个技能几乎是每个 agent 应用都会用到的。我需要它做的是：给定一个 URL，抓取网页并提取正文，返回干净的文本信息。以下是 run.py 的核心逻辑：

# run.py import requests from bs4 import BeautifulSoup import sys def fetch_text(url: str, output_format: str = "text") -> dict: headers = { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", } resp = requests.get(url, headers=headers, timeout=15) resp.raise_for_status() soup = BeautifulSoup(resp.text, "html.parser") # 移除无关标签 for tag in soup(["script", "style", "nav", "footer", "iframe"]): tag.decompose() title = soup.title.get_text(strip=True) if soup.title else "" main = soup.find("article") or soup.find("main") or soup.body text = main.get_text(separator="\n", strip=True) # 清理过长的空白行 lines = [line for line in text.split("\n") if line.strip()] if output_format == "markdown": # 这里可以做简单的 html->markdown 转换，略 pass if output_format == "json": return {"title": title, "text": "\n".join(lines)} return f"# {title}\n\n" + "\n".join(lines) if __name__ == "__main__": url = sys.argv[1] fmt = sys.argv[2] if len(sys.argv) > 2 else "text" print(fetch_text(url, fmt))

这里有一个我踩过很深的坑：直接抓取 HTML 的时候，如果目标网站做了 UA 校验，requests 默认的 UA 会被 403。所以上面代码里我显式添加了一个浏览器 UA 头。但是不要过度伪装成真实浏览器——有些站的反爬策略会检测 TLS 指纹，requests 在 TLS 指纹层面跟真实浏览器还有差异，这种站就别硬刚了，换无头浏览器或者官方 API 更靠谱。

执行完抓取之后，我会明确要求技能在返回结果前做一次"是否为空正文"的检查。很多新闻站的正文是动态渲染的，静态抓取只能拿到空壳。这时候应该返回一个标志位empty_page: true，而不是强行输出一堆无意义内容。模型看到这个标记，就知道需要换策略，比如提醒用户该页面是动态加载的。

4.2 技能二：CSV 数据分析与摘要生成

数据分析技能是另一个高频刚需。当用户丢给智能体一个 CSV 文件，要求做统计、分组、计算时，模型如果直接读原始数据，几乎必然被绕晕。我的做法是：先让一个子程序对 CSV 做预处理，生成摘要信息，再把这些摘要信息交给模型做进一步判断。

# run.py import pandas as pd import sys def summarize_csv(path: str, max_rows: int = 100) -> str: df = pd.read_csv(path) desc = df.describe(include="all").to_string() head = df.head(max_rows).to_string() shape = f"总共有 {df.shape[0]} 行，{df.shape[1]} 列\n" columns = "列名: " + ", ".join(df.columns) return f"{shape}{columns}\n\n数据统计摘要:\n{desc}\n\n前{max_rows}行数据:\n{head}" if __name__ == "__main__": # 参数: csv路径, 最大预览行数 print(summarize_csv(sys.argv[1], int(sys.argv[2]) if len(sys.argv) > 2 else 100))

这个技能的价值在于：它不让模型直接面对原始数据，而是先把数据压缩成"模型能快速理解"的格式。要知道，一个几百兆的 CSV 全量塞进上下文，代价非常高；但如果你只需要做统计判断，df.describe()生成的摘要信息已经覆盖了绝大多数情况。

我在写这个技能时踩过一个认知坑：一开始我以为用户需要的是"模型直接读取 CSV 并回答问题"，但实际跑下来发现，当数据超过 20 行时，模型对数据中具体数值的记忆就开始模糊了。后来我把技能拆成两步——先让技能脚本生成摘要，模型基于摘要回答宏观问题；如果涉及具体行级过滤，则通过技能脚本执行查询后把结果返回。这套"摘要 + 按需查询"的组合非常稳定。

4.3 技能三：本地文件批量重命名

这个技能看起来简单，但非常考验参数设计。用户的需求往往是模糊的，比如"把文件夹里所有图片改成日期格式"。模型必须把这种模糊需求翻译成一组明确的操作指令，然后交给技能脚本执行。

# run.py import os import re import sys def rename_files(folder: str, pattern: str, dry_run: bool = True) -> list: changes = [] for name in os.listdir(folder): source = os.path.join(folder, name) if os.path.isfile(source): # pattern 中的 {name} 表示原文件名，{ext} 表示扩展名 new_name = pattern.replace("{name}", os.path.splitext(name)[0]) new_name = new_name.replace("{ext}", os.path.splitext(name)[1].lstrip(".")) changes.append((source, os.path.join(folder, new_name))) if dry_run: return changes # 只返回变更计划，不执行 return execute_changes(changes)

我把dry_run参数设计成默认开启。这意味着模型会先给用户展示一份"将要执行的操作清单"，等用户确认后再实际执行。这个设计极其重要——因为批量重命名是不可逆操作，一旦改错，找回来非常痛苦。通过 dry-run 机制把"执行"和"预览"分离，是我从一次数据损坏事故里学到的教训。那次有同事让智能体直接批量改名，结果某个正则写错，几百个文件全部乱了，最后靠备份才恢复。

这个案例想说明的是：在设计 skill 时，凡是涉及"不可逆操作"的能力，都要默认走"预览—确认—执行"三步。即便投入更多交互成本，也比出事故后的维护成本低得多。

4.4 技能组合：让 Agent 学会编排而不是从头执行

单一技能解决单一问题，组合技能才是 agent-skills 真正的价值所在。我的意思是：当你有了网页抓取、数据清洗、JSON 格式化这几个技能之后，一个更复杂的任务——比如"抓取三个竞品网站的价格并整理成表格"——就不再需要写新的技能，而是让模型编排现有技能依次执行。

组合能力的实现依赖两个前提：一是每个技能的输入输出格式足够规范，能够直接对接；二是模型对技能的边界有清晰理解。我在 SKILL.md 里会明确标注每个技能的"上游依赖"和"下游输出"。比如网页抓取技能的说明里会写"输出适合作为数据清洗技能的输入"，数据清洗技能里则写"接受网页抓取技能或 CSV 读取技能的输出"。

这个做法的好处是：技能的复用率大幅提升，新增需求时往往只需要调整编排逻辑而不是写新代码。我在实际项目中有一次需求变更，只改了一段编排配置就上线了新的处理流程，整个开发时间从预估的两天缩短到了半天。这就是技能化的杠杆效应。

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

5.1 技能"假死"：模型不调用技能怎么办

现象：你写得明明白白，用户也明确提出了需求，但智能体就是不用技能，而是自己凭记忆回答。这种情况在技能上线初期出现频率很高。

排查步骤我一般按顺序走：

• 第一步：检查技能描述里有没有触发条件。如果没有，先补上。比如"当用户需要查询实时数据、网页信息、最新公告时，必须调用 web-fetch 技能"。
• 第二步：检查技能的 description 与用户问题之间的语义距离。模型判断是否调用工具，靠的是语义相似度，不是纯规则匹配。如果描述写得过于专业、术语化，而用户问题很口语化，命中率就会下降。我的办法是：在描述里主动加上若干同义表达，比如"查一下""搜一下看看""这个网站写着……"。
• 第三步：检查是不是工具列表太长导致混淆。真正生产环境里，一次会话同时加载超过 10 个技能时，模型对每个技能的注意力会被稀释。解决办法是按场景动态加载。
• 第四步：把技能的示例（examples）写得更具体。一个"输入 URL 得到正文"的示例，远比一段复杂的解释更有说服力。

还有一个容易被忽略的细节：模型的 system prompt 中如果写了"你是一个助手，可以使用工具"，这个表述太弱了。应该写成"你具备以下技能：……，当任务涉及……时必须调用对应技能"。指令的强制语气差异，在实测中会造成 10% 到 20% 的调用率差距。

5.2 上下文被撑爆：技能加载了但没生效

现象：技能注册成功、描述也正确，但调用时感觉模型"忘记了"技能的存在。这个问题的常见原因是上下文窗口被无关内容占据了。

举个例子：一个长对话进行了 20 轮之后，前面 15 轮的聊天记录可能已经占了几千 token。如果技能清单是拼在系统提示词里的，而系统提示词又排在最前端，模型仍然应该能读到——但实测中，过长的历史对话会分散模型注意力，让它对系统提示词末尾的技能列表"视而不见"。

我的解决方案：使用消息级剪枝策略，把技能清单的完整信息放在"最近一次用户消息之后"的位置，而不是固定放在 system prompt 里。具体做法是在每次请求前，将技能描述注入到最后一条用户消息的上方，确保它在注意力窗口中的距离更近。如果使用的框架不支持这种灵活的注入方式，退而求其次的做法是：在用户新消息前插入一条系统消息，内容为"用户刚刚提到了……请优先考虑使用以下技能……"。

5.3 技能执行结果不可信

这里是重灾区。技能执行返回了一堆数据，但这些数据可能是错的。模型并不知道对错，它只会拿这些数据继续加工，最终给用户的答案就是错的。

我最常遇到的两类问题：

一是源数据本身就不对。网页抓取技能把验证码页面当成正常页面抓了回来，解析出的"正文"是一堆验证提示。这种问题很难靠模型自查发现，需要在技能脚本里加更多校验。比如抓取结果如果长度异常短（比如少于 200 字符），或者标题包含 "access denied""captcha" 等关键词，就返回错误标志。我在技能脚本里写了一个validate_result()方法，专门做这一步，实测能拦截掉大约 70% 的无效结果。

二是模型把旧数据当新数据用。数据分析技能在第一次请求时生成了摘要并缓存了结果，第二次、第三次对话时模型可能还记得这些数字，但用户已经换了新数据源。这是非常隐蔽的错误：模型上下文里还残留着旧数据信息，新技能的结果反而被它当成补充材料，优先采信了更"熟悉"的旧数据。

我的对策：每次技能执行结果返回时，除了结果内容本身，还附带一个时间戳和数据源 MD5 值。模型在生成回复前，先判断当前数据源与上次是否一致，不一致则明确提示"该数据为旧数据，不可使用"。虽然这给技能增加了一点复杂度，但换来的是回答可信度的大幅提升。

5.4 技能互相干扰

技能多了以后，脚本之间会互相影响。我在生产环境遇到过：

• 两个技能都用了同一个临时文件路径，导致数据被覆盖。
• 一个技能修改了环境变量，影响到另一个技能运行。
• 两个技能返回的 JSON 结构里有相同的字段名，导致模型混淆。

解决手段有两个。第一个是命名空间隔离：每个技能的所有临时文件都放在自己目录下的 tmp 文件夹里，环境变量前缀带上技能名。第二个是输出契约统一：我在技能注册器里加了一个校验，每次执行返回结果必须是固定结构，比如{"success": bool, "data": ..., "meta": {...}}。如果技能脚本返回结构不符合这个契，注册器直接拒绝结果并返回错误提示。这套约束看起来简单，但它让模型在多技能协同的场景下始终知道"每个结果是谁给的、格式是什么"。

5.5 技巧清单：你应该提前知道的五件事

最后整理一份我在多次项目里沉淀下来的操作技巧，这些在官方文档里通常找不到：

• 技能描述中使用"必须"而非"可以"。模型对语气强度很敏感，弱的语气会让它在犹豫时选择不调用工具。
• 给每个技能至少写两个示例：一个标准场景，一个边界场景。边界场景能教会模型"这种情况虽然看起来像，但不要用这个技能"。
• 在开发阶段，给技能脚本加上完整日志。别嫌麻烦，生产环境里的诡异问题，九成要靠日志定位。
• 版本管理技能脚本。一个技能改了参数之后，之前的老调用方会受影响，最好在 SKILL.md 里标注版本号，并在注册器里做兼容。
• 优先让技能抛出"确定性错误"，不要让模型猜。比如"抓取失败，原因是 HTTP 403"比"无法获取网页内容"有用得多——模型可以根据具体错误调整策略，而不是只能含糊地向用户道歉。

我在实际项目里的体会是：agent-skills 的技术门槛并不高，真正难的是那些"看起来不起眼但决定成败"的细节。技能描述的一个措辞、返回值的一个字段、加载时机的一次调整，都可能让整体效果产生质变。如果你正准备在项目里引入技能化设计，不用一上来就追求大而全，先挑两三个高频场景做深做透，把这一套流程跑通之后，再横向扩展。

另外想提醒一句：每个技能都要像对待产品功能一样对待它的生命周期。上线、监控、迭代、下线，一个都不能少。没有监控的技能，就像没有仪表盘的飞机——飞得起来，但你不知道什么时候会出事。我自己会把技能的调用次数、成功率、平均耗时全部记录下来，每周复盘一次。某个技能连续两周调用率低于 1%，就考虑合并或下线；某个技能成功率跌破 80%，就要重点排查，而不是等用户投诉。

这套玩法跑顺了之后，你会发现 agent 开发的核心矛盾已经不再是"模型不够聪明"，而是"你有没有把场景拆成足够清晰的技能单元"。拆得越细，边界越明确，模型的表现就越稳定。