企业官网建设流程全解析

1. 从零写一个 Agent Skill：SKILL.md 元数据到底怎么填

Agent Skills 是给智能体加装「专业技能包」的轻量格式，核心就是一个带SKILL.md的文件夹。它解决的问题很具体：模型本身很聪明，但不知道你团队的代码规范、不知道你司内部 API 怎么调、不知道某个报表的字段含义。技能就是把这些「程序性知识」按需喂给智能体。

它适合三类人：想让 Claude Code、Cursor 这类编码智能体记住自己项目套路的开发者；想把团队知识封装成可版本控制知识包的工程团队；以及想一次构建、多端复用的技能作者。你不需要改模型，也不需要写复杂的插件协议，只要会写 Markdown 加一点脚本，就能让智能体识别并调用你的技能。

我先把最容易踩坑的地方说清楚：SKILL.md顶部的 YAML 前置元数据不是装饰，它是智能体「发现」技能的唯一依据。启动时智能体只读name和description，判断这个任务要不要激活这个技能。所以description写得好不好，直接决定技能会不会被调用。很多人技能写完发现「智能体根本不用」，九成是 description 太笼统。

一个最小可用的技能目录长这样：

my-skill/ ├── SKILL.md # 必需：元数据 + 指令 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考资料 └── assets/ # 可选：模板、资源文件

SKILL.md的骨架：

--- name: pdf-processing description: 从 PDF 提取文本和表格，填写表单，合并文档。当用户需要处理 PDF 文件时使用。 --- # PDF Processing ## 什么时候用 用户提到 PDF、表单填写、文档合并时…… ## 怎么提取文本 1. 用 pdfplumber 打开文件……

元数据字段里，name和description必填，其余可选。name规则很严：1–64 字符，只能小写字母、数字、连字符，不能以连字符开头或结尾，不能有连续连字符，而且必须和父目录名一致。PDF-Processing、-pdf、pdf--processing都是无效的。description上限 1024 字符，要写清「做什么」和「什么时候用」，最好埋进用户可能说的关键词。

可选字段里，license写许可证名或路径，compatibility写环境要求（Python 版本、系统依赖），metadata是任意键值对（作者、版本），allowed-tools是实验性的预批准工具列表，空格分隔。这些字段智能体不一定全用，但对团队协作和版本管理很有价值。

技能的工作机制叫「渐进式披露」：发现阶段只加载 name 和 description；任务匹配时把完整SKILL.md读进上下文；执行阶段按指令干活，需要时才加载引用文件或跑脚本。这个设计让上下文不被一次性塞满，响应也快。理解这一点，你就知道为什么指令要分层写——高频步骤放正文，长参考资料放references/。

2. TaoToken 前置：给技能接一个稳定的模型入口

技能本身不产生智能，它需要挂在一个能读SKILL.md的智能体上。我实测下来，用 TaoToken 做统一入口比较省事：一个 Key 就能在多个兼容智能体产品之间切换，技能包不用改。

TaoToken 的定位是模型调用入口，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。它兼容 Anthropic 和 OpenAI 两种协议风格，所以 Claude Code、Cline、Codex 这类工具都能接。

先拿 Key。进控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面创建一个，复制出来。这个 Key 后面要填进各个工具的配置里。

如果你只是想先验证模型通不通，可以用模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 直接发一条消息，确认 Key 有效、额度正常。这一步能帮你排除掉后面「到底是技能写错了还是 Key 没配好」的扯皮。

对于长期写代码、跑 Agent 的场景，Coding Plan 更划算，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。技能开发本身是个反复调试的过程，会频繁触发模型调用，用套餐比按量更可控。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各工具的完整配置示例。Claude Code 的接入说明单独放在 https://taotoken.net/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite ，如果你用 Claude Code 跑技能，直接看这个。

这里要强调一个概念：TaoToken 是模型调用入口，不是编辑器，也不是技能运行时。技能的执行者是智能体本身，TaoToken 负责把请求送到模型。两者职责分清，排障时就不会乱。

3. 可复制配置：SKILL.md 模板 + 脚本挂载 + 工具接入

这一节给你能直接抄的东西。先写一个真实可用的技能：查天气。目录结构：

weather-skill/ ├── SKILL.md └── scripts/ └── weather.py

SKILL.md全文：

--- name: weather-skill description: 通过高德地图 API 查询指定城市的实时天气，包括温度、天气状况、风力风向、湿度。当用户询问某城市天气、气温、是否下雨时使用。 license: Apache-2.0 compatibility: Python 3.8+, 需要 requests 库，需要网络访问 metadata: author: your-name version: "1.0.0" --- # 城市天气查询技能 ## 功能描述 查询指定城市的实时天气信息。 ## 使用方式 用户直接描述要查的天气，例如： - "北京天气怎么样" - "上海今天多少度" ## 环境变量 使用前设置高德 API Key： ```bash export AMAP_MAPS_API_KEY=your_api_key

安装依赖

pip install requests

调用脚本

python scripts/weather.py 北京

输出格式

城市、天气、温度、风力、湿度、发布时间。

注意 `name` 是 `weather-skill`，和父目录名一致。`description` 里埋了「天气、气温、是否下雨」这些用户可能说的词。 脚本 `scripts/weather.py`： ```python #!/usr/bin/env python3 """城市天气查询 - 使用高德 API""" import os import sys import requests def get_city_code(city_name: str, api_key: str): url = "https://restapi.amap.com/v3/config/district" params = {"key": api_key, "keywords": city_name, "subdistrict": 0} resp = requests.get(url, params=params, timeout=5) resp.raise_for_status() data = resp.json() if data.get("status") == "1" and data.get("districts"): return data["districts"][0]["adcode"] return None def query_weather(city_code: str, api_key: str): url = "https://restapi.amap.com/v3/weather/weatherInfo" params = {"key": api_key, "city": city_code, "extensions": "base"} resp = requests.get(url, params=params, timeout=5) resp.raise_for_status() data = resp.json() if data.get("status") == "1" and data.get("lives"): return data["lives"][0] return None def main(): if len(sys.argv) < 2: print("用法：python weather.py <城市名>") sys.exit(1) city_name = sys.argv[1] api_key = os.environ.get("AMAP_MAPS_API_KEY") if not api_key: print("错误：请设置环境变量 AMAP_MAPS_API_KEY") sys.exit(1) city_code = get_city_code(city_name, api_key) if not city_code: print(f"未找到城市：{city_name}") sys.exit(1) weather = query_weather(city_code, api_key) if not weather: print(f"无法获取 {city_name} 的天气") sys.exit(1) print(f"{weather['city']}天气：{weather['weather']}") print(f"温度：{weather['temperature']}°C") print(f"风力：{weather['windpower']} {weather['winddirection']}风") print(f"湿度：{weather['humidity']}%") print(f"发布时间：{weather['reporttime']}") if __name__ == "__main__": main()

脚本接口设计的关键：让智能体能从SKILL.md里知道怎么调用、传什么参数。所以指令里必须写清python scripts/weather.py 北京这种调用形式。

接下来把技能挂到智能体上。以 Claude Code 为例，配置文件在~/.claude/settings.json，接入 TaoToken 的片段：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "你的_TaoToken_Key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }

三件套齐了：Base URL、Key、Model ID。技能目录放到 Claude Code 能扫描的位置（通常是项目下的.claude/skills/或用户级技能目录），它启动时会读每个技能的 name 和 description。

如果你用 Cline，配置走 MCP 或自定义 provider，同样填 Base URL、Key、Model ID 三项。Codex 则写进auth.json：

{ "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "你的_TaoToken_Key", "model": "gpt-4o" }

不同工具字段名不一样，但本质都是这三样。填错任何一项，技能都不会被激活。

4. 验证请求：本地加载一次，看技能是否被识别

写完不等于能用，必须验证。分两步：先单独跑脚本，再让智能体加载技能。

第一步，本地跑脚本，确认逻辑没问题：

export AMAP_MAPS_API_KEY=你的高德Key python scripts/weather.py 北京

期望输出：

北京天气：晴 温度：15°C 风力：3 北风 湿度：45% 发布时间：2026-03-03 10:00:00

如果这一步就报错，别急着怪智能体，先把脚本调通。常见的是 Key 没设、requests 没装、城市名查不到 adcode。

第二步，验证智能体能否发现技能。启动 Claude Code，问一句「北京天气怎么样」。观察它的行为：如果技能被正确加载，它会先读SKILL.md，然后按指令调用scripts/weather.py 北京，最后把结果整理给你。如果它直接瞎编一个天气，说明技能没被识别。

你也可以主动触发技能列表。在 Claude Code 里输入/skills或类似命令（不同版本命令名可能不同），看weather-skill在不在列表里。不在的话，检查三件事：目录名和name是否一致、SKILL.md是否在技能根目录、YAML 前置元数据格式是否正确（---必须顶格）。

验证模型入口是否通，可以单独发一条请求：

curl https://taotoken.net/api/v1/messages \ -H "x-api-key: 你的_TaoToken_Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "max_tokens": 100, "messages": [{"role": "user", "content": "说一句话证明你在"}] }'

返回里有content字段就说明入口通了。这一步能把「模型不通」和「技能没加载」两个问题分开。

实测下来，技能加载失败最常见的原因是 description 写得太泛，比如只写「处理文档」。智能体判断不出什么时候该用，就永远不激活。把使用场景和关键词写进去，命中率会明显提升。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

排障时先看报错，别猜。下面几个是我踩过的坑。

401 Unauthorized。九成是 Key 问题。检查ANTHROPIC_AUTH_TOKEN或OPENAI_API_KEY有没有填错、有没有多余空格、Key 是不是被删了。如果用的是 Claude Code，注意它读的是ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY，填错字段名会直接 401。去控制台 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 重新生成一个对比。

local proxy failed。这个报错通常出现在工具试图走本地代理但代理没起来。检查你的配置里有没有残留的HTTP_PROXY、HTTPS_PROXY环境变量，或者工具自带的代理开关。清掉这些，让请求直连 Base URL。另外确认 Base URL 写的是https://taotoken.net/api，不要多加路径。

reading choices 相关报错。这类多半是响应格式和工具预期不匹配。比如工具按 OpenAI 格式解析，但你填的模型走的是 Anthropic 协议。检查 Model ID 和协议是否配套：Claude 系列走 Anthropic 格式，GPT 系列走 OpenAI 格式。混用会解析失败。

OAuth 报错。有些工具默认走 OAuth 登录流程，但你用的是 API Key 模式。在配置里关掉 OAuth 或选择 API Key 认证方式。Claude Code 如果提示登录，检查 settings.json 里的 env 是否生效，必要时重启终端。

技能不被调用。不是报错但很烦。按顺序查：name和目录名是否一致；description是否包含用户会说的关键词；SKILL.md是否在技能根目录；YAML 前置元数据是否被正确解析（用---包裹，顶格写）。还有一个隐蔽问题：技能目录层级放错了，工具扫描不到。确认你放的是工具文档里指定的技能目录。

脚本执行失败。智能体调用脚本时报「command not found」或权限错误。检查脚本有没有执行权限（chmod +x scripts/weather.py），以及SKILL.md里写的调用路径是否和实际一致。相对路径是相对技能根目录，不是相对当前工作目录。

排障时建议开工具的详细日志，能看到它到底加载了哪些技能、发了什么请求。日志里搜技能名，能快速定位是发现阶段还是执行阶段出的问题。

6. 语义一致 CTA：把技能接进你的工作流

技能写完之后，真正的价值在于它被反复调用。如果你主要做编码和 Agent 任务，建议用 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，技能调试会频繁触发模型，套餐更稳。

需要新建或轮换 Key，去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。各工具的完整接入步骤看文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Claude Code 用户直接看 https://taotoken.net/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。想先验证模型响应，用模型对话 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 发一条就行。

最后给个实用建议：技能不要一次写太大。一个技能解决一类任务，description 精准，脚本接口清晰。我见过有人把所有内部工具塞进一个技能，结果智能体判断不出什么时候用，反而一个都不触发。拆小、写准、勤验证，比堆功能有用得多。