QDKT-Skill 概念与原理拆解：从 Skill Creator 到 Agent 的 Skill 开发实践

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 读详细说明再通过终端运行脚本。用哪个加载哪个不用不占上下文。维度Function CallingMCPSkill上下文占用全量 schema 常驻全量描述常驻叠加严重仅摘要常驻按需读取加载时机启动即全量启动即全量匹配后才读详情扩展形态代码内定义外挂程序文件系统文件夹能否复用文档资料弱弱强可读 PPT/图片/手册开发门槛中中高低会写 Markdown 即可一句话总结Skill 凝练了 Function Calling 和 MCP 的流程同时把“按需加载”这件事做透了。3. 前置准备用 TaoToken 统一 Key 与 API 通道在动手写 Skill 之前得先解决模型调用通道的问题。Skill 本身不绑定模型但 Agent 执行脚本、生成内容时都要调模型。如果你同时用 Cursor、Claude Code 和自建脚本每个工具配一套 Key 会很乱。我的做法是用 TaoToken 做统一入口一个 Key 走通所有工具。TaoToken 的定位是 AI 工具的 API 聚合通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它不替代编辑器也不碰你的生产数据库只负责把模型请求转发出去所以拿它做 Skill 开发期的验证通道很合适。具体操作分三步。第一步去控制台创建 Key控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content第二步在环境变量里配置避免 Key 硬编码进脚本# Linux / macOS export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api第三步如果你用 Claude Code 或 Cursor 的 Agent 功能把 base_url 指向 TaoToken 的端点即可模型对话能力可以在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 先验证一下通不通。长期跑编码和 Agent 任务的话Coding Plan 会更划算地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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 本身就是一个 SkillAnthropic 官方提供Cursor 在子 Agent 选项下自带Claude Code 也能加载。它的作用是你用自然语言描述需求它自动生成符合规范的文件夹、skill.md 和脚本。向 Skill Creator 描述需求时必须讲清三件事触发条件、作业流程、能力边界。以“把文档保存到飞书知识库”为例描述可以这样写开发一个技能触发条件当用户需要将产出物保存到飞书知识库时使用。 作业流程1. 验证飞书 API 授权2. 将文档转为 Markdown3. 查询目标知识库 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: fBearer {api_key}, Content-Type: application/json, }, json{ model: claude-sonnet, max_tokens: 256, messages: [ {role: user, content: 用一句话说明 Skill 和 MCP 的区别} ], }, timeout30, ) 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 试不同模型在 Skill 场景下的表现想深入接入细节接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 如果你打算长期用 Agent 跑编码和自动化任务Coding Plan 的通道更稳地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。入门练习建议从无脚本技能开始比如“生成周报框架”只在 skill.md 里写清模块结构让 Agent 匹配后直接生成。熟练了再加脚本、加 API 调用。Skill 开发的核心不是写代码而是把最佳实践梳理成清晰的 SOP——这件事想明白了剩下的交给 Skill Creator 就行。