企业官网建设流程全解析

Agent Skills 这套标准刚出来的时候，我第一反应是「又一个提示词模板包装」。直到我把同一个 Dashboard 需求分别用裸提示词和挂载 frontend-design 技能的方式各跑了一遍，输出质量的差距才让我认真对待这件事。裸提示词版本给我的是白底紫渐变、圆角卡片堆叠的典型「AI 味」界面；挂载技能之后，同样的模型给出了深色工业风、字号层级分明、配色克制的方案。差别不在模型，而在于 Agent 有没有拿到一份明确的「这个场景下什么算做对」的判断依据。

Agent Skills 本质是一套可复用的指令集标准，核心是一个叫 SKILL.md 的 Markdown 文件，放在约定目录下，Agent 启动时扫描名称与描述，任务匹配时按需加载，用完即走。它适合三类人：一是反复写长提示词写到烦的开发者，二是想让多个工具共用同一套能力规范的团队，三是希望把「老师傅的判断」固化成流程的工程负责人。本文会从目录结构讲起，给出 frontend-design 技能的可复制配置，再演示一次完整的技能挂载与调用验证，最后把常见的报错逐个拆开。

1. 为什么提示词越写越长，Agent 还是不稳定

先说清楚原问题。我见过太多项目把系统提示词写到三四千字，里面塞满「你要专业」「注意配色」「不要用渐变」这类要求。结果呢，同一个需求跑三次，三次风格都不一样。原因很朴素：提示词是临场指挥，它描述的是「我希望你怎样」，而不是「在这个场景下，判断标准是什么、步骤是什么、什么算交付合格」。

Agent Skills 换了个思路。它把能力拆成一个个独立文件夹，每个文件夹里有一个 SKILL.md，写清楚这个技能解决什么问题、什么时候该被触发、执行时按什么步骤走、产出要满足哪些硬性条件。Agent 启动时只读每个技能的 name 和 description，这两项很轻，几乎不占上下文；只有当你的任务和某个技能描述匹配上，完整内容才会被加载进来。

这个机制解决的是上下文浪费和判断缺失两个痛点。举个具体对比：你要 Agent 生成一份 Excel 报表，裸提示词你得每次交代「用 openpyxl、表头加粗、数字右对齐、冻结首行」；而一个 xlsx 技能把这些写死在 SKILL.md 里，你只说「生成季度销售报表」，它自己就知道该怎么做。前者是每次重新教，后者是入职发手册。

我实测下来，一个中等复杂度的前端页面任务，裸提示词大约要 600 到 900 token 的额外约束，而且经常漏项；挂载技能后，主对话里只需要一句业务描述，技能内容按需注入，主上下文反而更干净。更关键的是稳定性：技能里的判断是写死的，不会因为对话轮次变多而被模型「遗忘」或「稀释」。

还有一个容易被忽略的点：可组合。一个任务可能同时命中 frontend-design 和某个图表技能，Agent 会自动把两者都加载进来协同工作。这种能力链是提示词很难做到的，因为提示词是一整块，你没法按需拼装。技能是模块，模块才能组合。

所以这一章的核心结论是：不稳定的根源不是模型不够强，而是判断没有被工程化。SKILL.md 就是那个把判断写进系统的载体。下面讲怎么把它接进实际工作流。

2. TaoToken 前置准备：把模型通道和技能目录先理顺

在挂载技能之前，得先保证 Agent 能稳定调到模型。技能只是「怎么做」的说明书，模型才是「谁来做」的执行者，两条链路要分开准备。我习惯用 TaoToken 作为统一的模型接入层，原因是它的 Base URL 和 Key 管理比较集中，切换模型时不用改一堆配置文件。

第一步，拿 API Key。打开 https://taotoken.net/api 对应的控制台入口，在 API Keys 页面创建一个新 Key，命名建议带上用途，比如agent-skills-dev，方便后面排查是哪个环境在调用。创建后立刻复制保存，页面刷新后就不再完整显示。

第二步，确认模型 ID。不同工具对模型名的写法略有差异，但核心是同一个标识。你可以在模型对话页面先做一次最简单的连通性测试，确认 Key 有效、额度正常，再去配 Agent 工具。这一步别省，我踩过的坑就是直接去配 Claude Code，结果报 401，回头查了半天才发现是 Key 复制时多了个空格。

第三步，规划技能目录。这是很多人卡住的地方。不同工具读的技能路径不一样，但好消息是 Claude Code 的~/.claude/skills/被多数工具兼容。我的做法是统一放在这个目录，然后给其他工具做软链接或直接配置指向它，避免同一份技能维护多份副本。

第四步，准备一个测试项目目录。技能挂载验证不要在生产项目里做，新建一个空目录，放一个index.html占位即可。这样出问题时能快速判断是技能问题还是项目配置问题。

这里要提醒一句：技能目录的权限要确认。Linux 或 macOS 下如果目录属主不对，Agent 读不到 SKILL.md，表现就是「技能明明放了却不生效」，而且不报错，非常隐蔽。用ls -la ~/.claude/skills/看一眼权限位，确保当前用户可读。

前置准备做完，你应该有三个东西：一个可用的 API Key、一个确认可调通的模型 ID、一个干净的技能目录。接下来才是真正的配置环节。

3. 可复制配置：SKILL.md 目录结构与 frontend-design 落地

这一章是全文的技术核心，所有片段都可以直接复制。先讲目录结构，再给 frontend-design 的 SKILL.md 骨架，最后给工具侧的 settings 配置。

一个标准技能文件夹长这样：

~/.claude/skills/ └── frontend-design/ ├── SKILL.md ├── scripts/ │ └── check_contrast.py └── resources/ └── palette-reference.md

SKILL.md 是必需项，scripts 和 resources 都是可选项。SKILL.md 的开头必须有 frontmatter，用三个短横线包起来，里面至少写 name 和 description。description 决定了技能会不会被触发，所以要写清楚「做什么」和「什么时候用」，别写成一句空泛的口号。

下面是我在用的 frontend-design 技能骨架，你可以直接存成~/.claude/skills/frontend-design/SKILL.md：

--- name: frontend-design description: 生成具有明确视觉主张的前端界面。当任务涉及 Dashboard、落地页、数据看板、管理后台等需要视觉设计的页面时使用。避免通用 AI 风格，强调字体层级、配色克制与信息密度。 --- # Frontend Design ## 何时使用 当用户要求设计或实现一个界面，且该界面需要视觉判断而非纯功能堆砌时，加载本技能。 ## 设计原则 1. 先定视觉基调，再写代码。基调从三个方向选一个：工业深色、极简浅色、高对比编辑风。 2. 字体层级不超过四级，正文与标题的字号比不低于 1.4。 3. 配色不超过三个主色，禁止使用紫蓝渐变作为主视觉。 4. 信息密度优先，卡片间距统一使用 8 的倍数。 ## 执行步骤 1. 输出一段 50 字以内的视觉基调说明。 2. 给出配色与字体方案，用表格列出。 3. 生成完整 HTML，内联 CSS，不引入外部 UI 框架。 4. 自查：对比度是否达标、层级是否清晰、是否有无意义的装饰元素。 ## 交付标准 - 页面在 1280px 宽度下无横向滚动。 - 所有交互元素有 hover 态。 - 不使用 emoji 作为图标。

注意 description 的写法，它同时包含了能力描述和触发条件，这是技能能被正确匹配的关键。我见过有人把 description 写成「一个前端技能」，结果 Agent 永远不触发它，因为匹配不上任何具体任务。

工具侧的配置，以 Claude Code 的 settings 为例，放在~/.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "你的模型ID" }, "skills": { "directory": "~/.claude/skills", "autoLoad": true } }

三件套必须齐全：Base URL 指向https://taotoken.net/api，Key 填你刚创建的，Model ID 填确认可用的那个。少任何一个都会在启动时报错。如果你用的是 Codex CLI，对应的是auth.json，结构不同但字段含义一致：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "你的模型ID" }

Cline 这类走 MCP 配置的工具，则是在 MCP servers 配置里把模型通道指向同一个 Base URL。不管哪个工具，记住一个原则：Base URL、Key、Model ID 三者必须来自同一个通道，混用是最常见的 401 来源。

配置写完，重启工具。重启后不要急着跑复杂任务，先做下一章的验证。

4. 验证请求：一次完整的技能挂载与调用验证

验证分两层：先验证模型通道通不通，再验证技能有没有被加载。两层分开测，出问题才能定位。

第一层，通道验证。在项目目录下用命令行发一个最小请求：

curl https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "你的模型ID", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK 两个字母"}] }'

返回体里content数组第一项的text是 OK，说明通道正常。如果这里就失败，别往下走，先解决 Key 或 Base URL 问题。

第二层，技能加载验证。启动 Claude Code，输入一句能触发技能的话，比如「帮我设计一个 API 调用监控的 Dashboard」。观察两个信号：一是 Agent 是否在回复里提到它参考了 frontend-design 的规范，二是产出是否符合 SKILL.md 里写的交付标准，比如有没有用紫蓝渐变、字号层级是否清晰。

我实测的验证话术是这样的：

设计一个 AI 产品的数据分析 Dashboard。左侧导航栏，顶部四个数据卡片显示今日概览（用户数、调用次数、收入、增长率），中间是 7 天趋势折线图，右侧是最近的 API 调用记录列表。

挂载技能前，输出是白底、紫色渐变按钮、圆角大卡片。挂载后，输出是深色底、黄青点缀、等宽字体做数字、卡片间距统一。这个对比就是技能生效的直接证据。

如果你想确认技能确实被读取了，可以在对话里直接问「你现在加载了哪些技能」，Agent 会列出当前可用的技能名称。这一步能排除「文件放了但没被扫描到」的情况。

验证通过后，建议把这次成功的配置和话术记下来，作为团队内的基线。后面新人接入时，用同一套话术跑一遍，输出风格一致就说明环境配对了。这比写一堆文档管用。

5. 常见错排查：401、local proxy failed 与技能不触发

这一章按真实报错来拆，每条都给定位方法和修复动作。

401 Unauthorized。最常见，九成是 Key 问题。先确认 Key 没有多余空格或换行，再确认这个 Key 属于当前 Base URL 对应的通道。有个隐蔽情况：你在 A 环境创建的 Key 拿去配 B 环境的 Base URL，两边不互通，必然 401。修复动作是把 Base URL、Key、Model ID 三件套对齐到同一来源，重新写一遍配置再重启。

local proxy failed。这个报错通常出现在工具尝试走本地转发但转发进程没起来的时候。先检查是否有残留的代理配置指向了一个不存在的本地端口。修复动作是清空工具配置里的 proxy 相关字段，让请求直连 Base URL。如果工具本身有「使用系统代理」的开关，关掉它再试。

reading choices 相关报错。这类错误一般出现在响应解析阶段，说明请求发出去了但返回结构不符合预期。常见原因是 Model ID 写错，通道返回了一个错误结构，工具却按正常响应去解析choices字段。修复动作是回到模型对话页面确认准确的 Model ID，逐字符比对，别凭记忆写。

OAuth 相关报错。部分工具首次启动会走 OAuth 流程，如果环境里没有浏览器或回调端口被占用，就会卡住。修复动作是改用 API Key 方式认证，跳过 OAuth；或者在配置里显式指定认证方式为 key。

技能放了但不触发。这个不报错，最难查。三个排查方向：一是 SKILL.md 的 frontmatter 格式不对，三个短横线必须是文件前三行，中间不能有空行；二是 description 写得太泛，匹配不上具体任务，改成「做什么 + 什么时候用」的结构；三是目录权限或路径不对，用ls确认文件真实存在且可读。

技能触发了但输出不符合预期。这通常是 SKILL.md 里的交付标准写得太软，比如只写「注意配色」而不写「禁止紫蓝渐变」。把判断标准写成可验证的硬条件，Agent 的执行才会收敛。

排查的顺序建议固定：先通道后技能，先配置后内容。每次只改一个变量，改完立刻验证，别一次改三处，否则问题解决了也不知道是哪处起的作用。

6. 把技能接进日常工作流：从单次验证到长期复用

验证通过只是起点，真正有价值的是把技能变成团队资产。我的做法分三步。

第一步，建立技能清单。在项目仓库里放一个skills-manifest.md，列出当前依赖的技能名、版本、来源和用途。技能是会迭代的，没有清单，半年后没人说得清某个输出风格是哪来的。

第二步，把高频判断沉淀成技能。哪些值得沉淀？判断标准是：这个要求你在提示词里重复写过三次以上。比如「生成的 SQL 必须带注释」「接口文档必须包含错误码」「图表必须标注数据来源」，这些都是技能的好素材。写进 SKILL.md 之后，主对话就干净了。

第三步，做技能的组合验证。单个技能跑通后，试一个需要两个技能协同的任务，比如「生成一个带数据看板的接口文档页面」，同时命中 frontend-design 和文档类技能。观察 Agent 是否能正确加载两者并协调。这一步能暴露技能之间的冲突，比如两个技能对字体方案的要求打架，提前发现比上线后发现好。

长期编码和 Agent 场景，如果调用量上来，可以考虑 Coding Plan 这类按周期计费的方式，比按次调用更可控。模型对话页面适合做单次验证和效果对比，接入文档则在你换工具或换环境时查参数用。这三个入口分工清楚，日常就不会乱。

最后说一个我踩过的坑：技能目录不要放在会被 git 忽略的路径下，否则团队同步时技能丢失，新人拉代码后 Agent 行为完全不一样，排查起来非常费劲。把技能目录纳入版本管理，或者至少用一个独立的同步脚本维护，这是让技能真正可复用的前提。技能标准的价值不在于单个文件写得多漂亮，而在于它能不能被稳定地装配、组合、传承。