企业官网建设流程全解析

1. 从一次 Agent 卡顿说起：为什么需要 QDKT-Skill

如果你用过 Cursor、Claude Code 这类带 Agent 能力的工具，大概率遇到过这种情况：装了三五个 MCP 之后，Agent 响应越来越慢，一个简单任务要等十几秒才出结果。我试过在一个项目里同时挂了文件系统、数据库、浏览器三个 MCP，结果光是工具描述就塞进去几万 Token，模型还没开始干活，上下文已经快满了。

QDKT-Skill（后文简称 Skill）就是冲着这个痛点来的。它是一套围绕文件系统加终端系统打造的技能封装体系，让 Agent 按需读取文档、运行脚本、调用资料，而不是把所有工具的参数结构一次性灌进上下文。简单说，Skill 让 Agent 从“背着一整柜工具出门”变成“先看目录，用到哪个再取哪个”。

它适合谁？三类人：一是想让 Agent 稳定复用自己工作流的产品和运营；二是想给团队沉淀最佳实践的工程师；三是刚接触 Agent 开发、想跑通一个最小闭环的新手。本文会从概念原理讲到可复制的目录骨架和 config.toml 配置，最后用 TaoToken 统一 Key 通道做一次真实验证，让你跑通“Skill Creator 生成 Skill → Agent 调用 Skill”的完整链路。

2. Skill、Function Calling、MCP 到底什么关系

先把三个概念摆在一起看，不然后面配置容易懵。

Function Calling 是 2023 年之后成为主流的工具调用方式。它的逻辑是：你提前把每个工具的参数结构（schema）写好，模型收到任务后从这些 schema 里挑一个，生成调用参数，程序执行后把结果返回模型。问题在于，不管这个工具这次用不用，它的 schema 都得塞进上下文。工具一多，上下文就拥堵。

MCP 想解决的是“各家工具调用标准不统一”的问题，本意是好的，但它完全继承了 Function Calling 的上下文冗余，还多了个新麻烦：MCP 是外挂程序，用户可以在客户端随意安装，装得越多，塞进上下文的描述越多。有实测数据显示，某些 MCP 叠加后单次请求的上下文能到 5 万 Token 以上，Agent 响应延迟直接飙到 10 秒开外。

Skill 的思路完全不同。它把每个技能封装成一个独立文件夹，Agent 启动时只加载所有技能的 name 和 description（相当于论文的标题加摘要），占用极少 Token。等用户下发任务，Agent 从摘要里匹配到对应技能，才打开那个文件夹里的 skill.md 读详细说明，再通过终端运行脚本。用哪个加载哪个，不用不占上下文。

一句话总结：Skill 凝练了 Function Calling 和 MCP 的流程，同时把“按需加载”这件事做透了。

3. 前置准备：用 TaoToken 统一 Key 与 API 通道

在动手写 Skill 之前，得先解决模型调用通道的问题。Skill 本身不绑定模型，但 Agent 执行脚本、生成内容时都要调模型。如果你同时用 Cursor、Claude Code 和自建脚本，每个工具配一套 Key 会很乱。我的做法是用 TaoToken 做统一入口，一个 Key 走通所有工具。

TaoToken 的定位是 AI 工具的 API 聚合通道，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。它不替代编辑器，也不碰你的生产数据库，只负责把模型请求转发出去，所以拿它做 Skill 开发期的验证通道很合适。

具体操作分三步。第一步，去控制台创建 Key：

控制台地址：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

第二步，在环境变量里配置，避免 Key 硬编码进脚本：

# Linux / macOS export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api" # Windows PowerShell $env:TAOTOKEN_API_KEY="sk-你的key" $env:TAOTOKEN_BASE_URL="https://taotoken.net/api"

第三步，如果你用 Claude Code 或 Cursor 的 Agent 功能，把 base_url 指向 TaoToken 的端点即可，模型对话能力可以在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 先验证一下通不通。长期跑编码和 Agent 任务的话，Coding Plan 会更划算，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

注意：Key 只放在环境变量或本地 config 文件里，不要提交到 Git。Skill 的 scripts 目录里如果需要读 Key，统一从环境变量取。

4. 可复制的 Skill 目录骨架与 config.toml

前置通道通了，现在搭 Skill 的物理结构。一个标准 Skill 就是一个文件夹，Agent 只认文件夹里的指定文件。核心是 skill.md，其余都是可选扩展。

write-weekly-report/ ├─ skill.md # 核心：技能说明，Agent 唯一必读 ├─ config.toml # 可选：技能级配置，声明模型通道与参数 ├─ scripts/ # 可选：Python/Node 脚本 │ └─ fetch-data.py ├─ docs/ # 可选：说明文档、手册 │ └─ report-template.md └─ assets/ # 可选：模板、图片、底图 └─ cover.png

命名规范必须遵守：禁止中文、空格、特殊符号，多个单词用连字符连接。skill.md 里写“运行 fetch-data.py”，scripts 目录下就必须有这个名字的文件，大小写也要对上，否则终端执行会报找不到文件。

skill.md 分两部分。上面是 YML 元数据，Agent 启动时只加载这块：

--- name: write-weekly-report description: 当用户需要生成周报、整理本周工作产出、汇总项目进展时使用。支持从指定数据源拉取记录并套用模板生成结构化周报。 ---

下面是详细说明，讲清什么时候跑哪个脚本、读哪份文档：

## 使用步骤 1. 确认用户提供了数据源路径，未提供则询问。 2. 运行 scripts/fetch-data.py，传入数据源路径，输出 JSON 到临时目录。 3. 读取 docs/report-template.md，按模板结构组织内容。 4. 生成周报正文，输出为 Markdown。 ## 能力边界 - 仅支持 Markdown 和 TXT 数据源，不支持二进制文件。 - 单次处理数据不超过 5MB。 - 脚本报错时终止，不修改 scripts 目录下任何代码。

config.toml 是技能级配置，声明这个技能走哪个模型通道、用什么参数。这样不同技能可以走不同模型，互不干扰：

[model] provider = "taotoken" base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" model_name = "claude-sonnet" temperature = 0.3 max_tokens = 4096 [skill] name = "write-weekly-report" version = "0.1.0" timeout_seconds = 60 [limits] max_input_mb = 5 allowed_formats = ["md", "txt"]

把 api_key_env 写成环境变量名而不是 Key 本身，是为了让 config.toml 可以安全地进版本库。脚本里读配置时，用os.environ[config["model"]["api_key_env"]]取真实 Key。

5. 用 Skill Creator 生成技能并验证调用

目录骨架有了，接下来让 Skill Creator 帮你填内容。Skill Creator 本身就是一个 Skill，Anthropic 官方提供，Cursor 在子 Agent 选项下自带，Claude Code 也能加载。它的作用是：你用自然语言描述需求，它自动生成符合规范的文件夹、skill.md 和脚本。

向 Skill Creator 描述需求时，必须讲清三件事：触发条件、作业流程、能力边界。以“把文档保存到飞书知识库”为例，描述可以这样写：

开发一个技能，触发条件：当用户需要将产出物保存到飞书知识库时使用。 作业流程：1. 验证飞书 API 授权；2. 将文档转为 Markdown；3. 查询目标知识库 ID； 4. 无对应文档则创建，有则追加；5. 分块写入。 能力边界：仅支持 Markdown/TXT，不支持大于 10M 的文件；需要用户提供 API key 和 secret， 存放在 scripts/config.py 中。 背景信息：飞书知识库 API 的 POST 地址为 xxx，参数为 xxx。

Skill Creator 收到后会创建文件夹、写 skill.md、在 scripts 下生成调用脚本。生成完，把文件夹放进 Agent 的技能目录。Claude Code 的路径是根目录下的.claude-code/claude/skills/，Cursor 直接在子 Agent 选项里创建即可。

现在做一次真实验证。写一个最小脚本，用 TaoToken 通道调模型，确认 Skill 里的脚本能跑通：

import os import requests api_key = os.environ["TAOTOKEN_API_KEY"] base_url = os.environ["TAOTOKEN_BASE_URL"] resp = requests.post( f"{base_url}/v1/messages", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "model": "claude-sonnet", "max_tokens": 256, "messages": [ {"role": "user", "content": "用一句话说明 Skill 和 MCP 的区别"} ], }, timeout=30, ) print(resp.status_code) print(resp.json())

跑通的话，你会看到 200 状态码和一段模型返回。这一步验证了两件事：TaoToken 通道可用，Skill 脚本里的模型调用逻辑正确。接着在 Agent 里下发一个匹配技能的任务，观察它是否先匹配到 description、再打开 skill.md、最后运行脚本。整个链路走通，最小闭环就成了。

6. 本篇常见错误排查

开发过程中踩的坑基本集中在几类，对照排查能省不少时间。

报错一：Agent 匹配不到技能。九成是 description 写得太模糊。description 是 Agent 匹配的唯一依据，要写清“什么时候用”，而不是“这个技能是什么”。把触发条件直接写进 description，比如“当用户需要生成周报时使用”，比“周报生成工具”匹配率高得多。

报错二：终端执行报文件找不到。检查命名规范。中文、空格、特殊符号都会导致终端解析失败。skill.md 里写的文件名和 scripts 目录下的实际文件名必须完全一致，包括大小写。

报错三：脚本运行报 401 或鉴权失败。多半是 Key 没从环境变量读到。确认TAOTOKEN_API_KEY已 export，且脚本里用的是os.environ而不是硬编码。如果 config.toml 里 api_key_env 写错了变量名，也会出现这个问题。

报错四：Agent 乱改脚本。这是能力边界没写清。在 skill.md 的终止条件里明确写“脚本报错时终止运行，不修改 scripts 目录下任何代码”，能挡住大部分乱操作。

报错五：上下文还是很大。检查是不是把详细说明写进了元数据。元数据只放 name 和 description，详细步骤放在元数据下方，Agent 匹配后才读。

提示：调试阶段可以在 Agent 里让它先输出“我匹配到了哪个技能、准备读哪个文件”，这样能直观看到按需加载的过程。

7. 下一步：从最小闭环到长期编码

跑通最小闭环后，方向就清晰了。想继续验证模型对话能力，可以去 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 试不同模型在 Skill 场景下的表现；想深入接入细节，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ；如果你打算长期用 Agent 跑编码和自动化任务，Coding Plan 的通道更稳，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

入门练习建议从无脚本技能开始，比如“生成周报框架”，只在 skill.md 里写清模块结构，让 Agent 匹配后直接生成。熟练了再加脚本、加 API 调用。Skill 开发的核心不是写代码，而是把最佳实践梳理成清晰的 SOP——这件事想明白了，剩下的交给 Skill Creator 就行。