企业官网建设流程全解析

1. 从一次 Skill 改造说起：为什么需要统一 Key

12 月中旬开始，身边做 Agent 的团队几乎都在聊 Claude Skill。我接到的任务是把内部几个零散的 Python 工具改造成 Skill 形态，让 Claude Code 能按需加载。Skill 的本质是让模型通过读取文件系统来获得上下文，一个 Skill 目录里通常包含SKILL.md、scripts/、references/、assets/四部分。SKILL.md每次都会被读取，里面写清楚这个 Skill 能做什么、该读哪些文件、该执行哪些脚本。

问题出在调用环节。Claude Code 只定义了 Skill 的规范，并没有提供执行器实现。也就是说，list_file、read_file、execute_python、execute_mcp这些函数需要我们自己写，而它们最终都要落到模型 API 上。我一开始用多个平台的 Key 分别测试，结果环境变量互相覆盖，日志里分不清哪次请求走了哪个通道，排查成本很高。两周实践下来，最省事的做法是用 TaoToken 统一管理 Key，一个 Key 覆盖 Claude 系列模型的调用，Skill 执行器只认一个base_url和一个api_key，配置和验证都变得干净。

这篇内容适合正在把 Claude Skill 落地到 Claude Code 的开发者，也适合想用 Python Agent 跑通 Skill 机制的读者。我会从SKILL.md骨架、settings.json配置到 Python 调用逐步给出可复制的片段，并说明每一步怎么验证成功。

2. TaoToken 前置：把 Key 和接入地址准备好

在写 Skill 执行器之前，先把模型调用这一层固定下来。TaoToken 提供统一的 API 入口，Claude 系列模型可以通过同一个 Key 访问，这样 Skill 执行器里的execute_python和对话请求都走同一套凭证，不用在多个平台之间切换。

你需要准备两样东西：一个 API Key，以及接入地址。接入地址是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为base_url使用。Key 在控制台的 API Keys 页面创建，创建后复制保存，后面会写进环境变量。

注意：Key 只显示一次，建议创建后立即写入本地.env文件，不要提交到 Git 仓库。

环境变量建议这样组织，把模型调用和 Skill 目录分开：

# .env TAOTOKEN_API_KEY=sk-你的key TAOTOKEN_BASE_URL=https://taotoken.net/api SKILL_ROOT=./skills

如果你还没创建 Key，可以先去控制台页面操作：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。创建完成后回到这里继续。

这一步的验证很简单，用 curl 发一个最小请求，确认 Key 和地址能通：

curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: $TAOTOKEN_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 ok"}] }'

返回里能看到content字段就说明通道正常。这一步不通，后面 Skill 执行器一定跑不起来，所以先把它确认掉。

3. Skill.md 骨架与 settings.json 配置

3.1 目录结构

先建一个最小 Skill，目录名用my-skill，结构如下：

my-skill/ ├── SKILL.md ├── scripts/ │ └── calc.py ├── references/ │ └── notes.md └── assets/ └── template.txt

SKILL.md是核心文件，每次都会被读取。它的头部是 YAML front matter，必须包含name和description，下面正文可以自由发挥，写执行流程、写要读取哪些文件都行。

--- name: my-skill description: 当用户需要做简单数值计算或查询内部说明时使用，会调用 scripts/calc.py 并读取 references/notes.md --- # my-skill ## 使用场景 用户提出加减乘除、百分比换算等计算需求时触发。 ## 执行步骤 1. 读取 references/notes.md 了解计算约定。 2. 调用 scripts/calc.py，传入表达式。 3. 把脚本返回结果整理成自然语言回复。 ## 约束 - 不处理涉及外部网络的请求。 - 结果保留两位小数。

description很关键，Claude Code 靠它判断该不该选这个 Skill。写得太泛会导致误触发，写得太窄又选不中，建议把触发场景和依赖文件都写进去。

3.2 settings.json 配置

Claude Code 通过settings.json加载 Skill 目录。在项目根目录建.claude/settings.json：

{ "skills": { "directory": "./skills", "autoLoad": true }, "env": { "TAOTOKEN_API_KEY": "${TAOTOKEN_API_KEY}", "TAOTOKEN_BASE_URL": "https://taotoken.net/api" } }

directory指向 Skill 根目录，autoLoad打开后 Claude Code 会扫描子目录里的SKILL.md。env里把 Key 透传进去，执行器读环境变量即可，不用硬编码。

3.3 脚本示例

scripts/calc.py保持纯粹，只做计算，不碰网络：

import sys import json def calc(expr: str) -> float: allowed = set("0123456789+-*/(). ") if not set(expr) <= allowed: raise ValueError("表达式包含不允许的字符") return eval(expr, {"__builtins__": {}}, {}) if __name__ == "__main__": expr = sys.argv[1] result = calc(expr) print(json.dumps({"expr": expr, "result": round(result, 2)}))

这样设计的好处是脚本可单独测试，Skill 执行器只负责调度，职责清晰。

4. Python Agent 调用与逐步验证

4.1 执行器骨架

Skill 执行器需要四个函数：list_file、read_file、execute_python、execute_mcp。下面是一个最小实现，模型调用统一走 TaoToken。

import os import json import subprocess from pathlib import Path import anthropic SKILL_ROOT = Path(os.environ.get("SKILL_ROOT", "./skills")) client = anthropic.Anthropic( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], ) def list_file(folder: str): target = SKILL_ROOT / folder return [p.name for p in target.iterdir()] def read_file(name: str): target = SKILL_ROOT / name return target.read_text(encoding="utf-8") def execute_python(script: str, arg: str): path = SKILL_ROOT / script out = subprocess.run( ["python", str(path), arg], capture_output=True, text=True, timeout=30, ) return out.stdout or out.stderr def execute_mcp(func_name: str, params: dict): # 按需接入你的 MCP 实现，这里先返回占位 return {"func": func_name, "params": params, "status": "not_implemented"}

4.2 把 Skill 描述注入 system prompt

执行器启动时，先扫描所有SKILL.md的 front matter，把name和description拼进 system prompt，并告知模型可以调用文件读取函数。

def load_skill_meta(): metas = [] for skill_md in SKILL_ROOT.glob("*/SKILL.md"): text = skill_md.read_text(encoding="utf-8") if text.startswith("---"): _, front, _ = text.split("---", 2) meta = {} for line in front.strip().splitlines(): if ":" in line: k, v = line.split(":", 1) meta[k.strip()] = v.strip() metas.append(meta) return metas def build_system_prompt(): metas = load_skill_meta() lines = ["你可以使用以下 Skill，需要时先读取对应 SKILL.md："] for m in metas: lines.append(f"- {m.get('name')}: {m.get('description')}") lines.append("可用函数：list_file(folder), read_file(name), execute_python(script, arg)") return "\n".join(lines)

4.3 发起一次完整请求

def run(user_input: str): resp = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=1024, system=build_system_prompt(), messages=[{"role": "user", "content": user_input}], ) return resp.content if __name__ == "__main__": print(run("帮我算一下 (12+8)*3 等于多少"))

4.4 验证成功的标志

运行后，如果模型先请求读取my-skill/SKILL.md，再请求执行scripts/calc.py，最后返回60.0这样的结果，说明 Skill 的发现、读取、执行三段链路都通了。我实测下来，第一次跑通时日志里能看到两次工具调用，顺序和SKILL.md里写的步骤一致，这就是渐进式加载在起作用。

如果你想单独验证模型对话是否正常，可以先用模型对话页面发一条消息确认：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。如果打算长期跑编码类 Agent，Coding Plan 更适合持续调用：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

5. 本篇常见错排查

报错一：401 Unauthorized。多数是 Key 没读到。检查.env是否被加载，TAOTOKEN_API_KEY是否有多余空格。用echo $TAOTOKEN_API_KEY确认。

报错二：base_url拼接错误。有人把https://taotoken.net/api写成带/v1的地址，导致路径重复。SDK 会自动补/v1/messages，所以base_url只写到/api。

报错三：Skill 没被选中。检查SKILL.md的 front matter 是否以---开头和结尾，description是否为空。Claude Code 只读 front matter 里的字段，正文不参与选择。

报错四：execute_python超时。脚本里有阻塞操作。给subprocess.run加timeout，并在SKILL.md里写明脚本不应访问网络。

报错五：list_file返回空。SKILL_ROOT路径不对。用绝对路径或确认工作目录，Path拼接时注意不要多一层斜杠。

报错六：模型反复读同一个文件。system prompt 里没限制读取次数。可以在提示里加一句「同一文件最多读取一次」，或在执行器里做去重缓存。

排查顺序建议从 Key 到地址再到 Skill 目录，逐层确认。接入相关的细节可以对照接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，Key 管理在 API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

6. 两周实践后的几点经验

Skill 相比 MultiAgent 的优势在于上下文都在主 Agent 里，主 Agent 对全局理解更完整；相比固定 workflow，它又能在中间过程用自然语言插入判断，泛化性更好。我踩过的坑是早期把太多逻辑塞进SKILL.md正文，导致每次读取 token 消耗偏高，后来把细节挪到references/里按需读取，成本明显下降。

另一个经验是脚本要可独立运行。execute_python只是调度层，脚本本身用命令行就能测，这样出问题时能快速定位是脚本错还是调度错。Key 统一走 TaoToken 之后，环境变量只有一个，日志里也不会再出现多通道混淆的情况。

如果你也在做 Claude Skill 改造，建议先用一个最小 Skill 跑通发现、读取、执行三段，再逐步加复杂度。跑通之后再接 ClaudeCodeAnthropic 相关的编码场景：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude-code-anthropic&utm_campaign=rewrite ，整体链路会更顺。