1. 先搞清楚 AI Skill 到底解决什么问题AI Skill 不是插件也不是提示词模板它更像给 AI 装了一个「可调用的技能包」。你写一个SKILL.md告诉模型这个技能是干什么的、什么时候该用再配一个scripts/目录放确定性的 Python 脚本模型负责判断和调度脚本负责干活。适合谁适合每天有重复性工作、又不想每次都手写一大段提示词的人比如写周报、审代码、清洗 CSV、生成 commit message。我试过最直接的对比同样一句「帮我把这周的日志整理成周报」纯对话模式下模型每次输出格式都不一样还得手动补规则封装成 Skill 之后触发词、输出结构、边界条件全写死在SKILL.md里结果稳定得多。这篇就按「从零建目录 → 写 SKILL.md → 配 scripts → 用 TaoToken 统一 Key 跑通验证」的顺序走一遍每一步都给可复制的代码和配置。核心检索词先摆出来AI Skill 是什么、SKILL.md 怎么写、scripts 目录怎么组织、Python 脚本怎么接、TaoToken 统一 Key 怎么接入。下面全部围绕这几个点展开不绕概念。2. TaoToken 前置统一 Key 与 API 通道准备Skill 开发完之后要验证调用最省事的方式是走一个统一的 API 通道而不是每个模型单独配一套 Key。TaoToken 在这里的角色就是统一入口一个 Key 覆盖多种模型调用config.toml里改base_url和model就能切换不用动业务代码。你需要先拿到两样东西官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 Key。API 基地址https://taotoken.net/api 注意这个地址不带任何查询参数直接作为base_url使用。控制台里创建 Key 的路径是 API Keys 页面生成后复制保存后面config.toml要用。如果你后面要做长期编码或 Agent 类任务可以看 Coding Plan 页面只是验证模型对话能力用模型对话入口就够。文档在 doc 页面接入细节以文档为准。注意Key 只存在本地配置文件或环境变量里不要写进SKILL.md正文也不要提交到 git。SKILL.md是给模型看的指令文件不是密钥仓库。3. 可复制配置目录结构 SKILL.md scripts config.toml3.1 标准目录结构别自己瞎建直接抄这个结构文件夹名用 kebab-caseweekly-report-generator/ ├── SKILL.md # 核心指令文件唯一入口 ├── scripts/ # 确定性逻辑Python 脚本 │ ├── __init__.py │ └── clean_logs.py ├── references/ # API 文档、few-shot 示例 │ └── examples.md └── assets/ # 模板、静态资源 └── report_template.md三条硬规则文件夹名 SKILL.md里的name字段 调用时用的标识三处必须一致命名统一 kebab-case一个 Skill 只干一件事别把周报和代码审查塞进同一个。3.2 SKILL.md 骨架SKILL.md分两部分YAML frontmatter 是身份证Markdown 正文是执行指令。description是最关键的字段模型靠它判断什么时候触发必须写清「做什么 什么时候触发」。--- name: weekly-report-generator description: 根据工作日志自动生成结构化周报。当用户说写周报、总结本周工作、生成 weekly report时触发。 allowed-tools: Read, Write, Bash version: 1.0.0 license: MIT --- ## 角色 你是一名资深项目经理擅长从杂乱日志中提炼工作重点。 ## 执行步骤 1. 调用 scripts/clean_logs.py 清洗原始日志 2. 提取本周已完成的任务列表 3. 识别阻塞项和风险点 4. 生成下周计划建议 5. 按 assets/report_template.md 输出 ## 输入校验 - 如果用户未提供日志文本主动询问 - 如果日志少于 3 条提示补充 - 不要擅自补全业务规则不要编造数据 ## 输出格式 使用三级标题### 本周进展 / ### 存在问题 / ### 下周计划正文里明确写「不要编造数据」「不要擅自补全业务规则」比你想的有用这是防幻觉最便宜的手段。3.3 scripts 目录里的 Python 脚本确定性逻辑别让模型推理写成脚本放scripts/。数据清洗、格式转换、文件重命名这类活脚本执行快且不会出错。下面这个clean_logs.py负责把原始日志按行去重、去空、截断超长行# scripts/clean_logs.py import sys import json def clean(raw_text: str, max_len: int 200) - list[str]: seen set() result [] for line in raw_text.splitlines(): line line.strip() if not line or line in seen: continue seen.add(line) result.append(line[:max_len]) return result if __name__ __main__: raw sys.stdin.read() cleaned clean(raw) print(json.dumps(cleaned, ensure_asciiFalse, indent2))调用方式就是echo 日志内容 | python scripts/clean_logs.py输出 JSON 数组模型拿到结构化结果再组织语言。这样分工模型只做它擅长的归纳脚本做它擅长的确定性处理。3.4 config.toml 配置片段统一 Key 接入的配置长这样base_url指向 TaoToken 的 API 地址api_key从环境变量读别硬编码[llm] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model claude-sonnet-4-20250514 timeout 60 max_retries 2 [skill] name weekly-report-generator skill_dir ~/.config/skills/weekly-report-generator scripts_dir scripts环境变量在 shell 里设置export TAOTOKEN_API_KEY你的Keytimeout建议按链路段 P95 的 1.5 倍设max_retries用 2 次加指数退避避免偶发超时直接失败。4. 验证请求一次端到端跑通配置齐了跑一次完整验证。先确认脚本能独立工作echo 周一完成登录模块重构 周三修复3个P2 bug 周五评审新需求 | python scripts/clean_logs.py预期输出是清洗后的 JSON 数组。脚本通了再验证模型调用链路。用 Python 发一次请求确认 Key 和base_url生效# verify_skill.py import os import httpx resp httpx.post( https://taotoken.net/api/v1/messages, headers{ x-api-key: os.environ[TAOTOKEN_API_KEY], anthropic-version: 2023-06-01, content-type: application/json, }, json{ model: claude-sonnet-4-20250514, max_tokens: 512, messages: [{role: user, content: 写周报}], }, timeout60, ) print(resp.status_code) print(resp.json())成功结果是返回 200body 里能看到模型按SKILL.md定义的结构输出「本周进展 / 存在问题 / 下周计划」三段。如果返回 401检查 Key 是否设置正确返回 404检查base_url有没有多写路径。这一步跑通说明 Skill 的指令层和 API 通道都通了。5. 本篇常见错排查Skill 无响应九成是命名不一致。文件夹名、SKILL.md的name、调用标识三处必须完全一样kebab-case别混下划线。脚本报ModuleNotFoundErrorscripts/下加__init__.py调用时用python -m scripts.clean_logs而不是直接跑文件路径避免相对导入失败。模型不触发 Skilldescription写得太模糊。好的写法是「做什么 触发词」比如「当用户说写周报、总结本周工作时触发」差的只写一句「生成周报」。请求被限流并行请求太多。加指数退避第一次等 1s第二次等 3s别硬重试。输出格式每次不一样正文里没写死输出结构。把「使用三级标题### 本周进展 / ### 存在问题 / ### 下周计划」这种约束写进SKILL.md模型才会稳定遵守。Token 消耗大把所有内容塞进一个文件。用三层分工——name description常驻约 100 词SKILL.md正文触发后加载scripts/和references/按需调用。初始加载能从数万 Token 降到约 100 词。6. 接入与后续按场景选入口验证模型对话能力走模型对话入口最快要长期做编码或 Agent 类任务看 Coding Plan接入细节和参数说明以接入文档为准Key 管理在 API Keys 页面。这几个入口按你的实际场景选别只停在首页。常用 Skill 推荐按场景分效率类有 weekly-report-generator、meeting-notes-summarizer开发类有 go-http-reviewer、commit-message-generator数据类有 data-cleaning-pipeline、csv-to-chart安全类有 secret-scanner、dependency-auditor。选型优先挑窄任务 Skill「审查 Go HTTP 代码」比「做全栈开发」好用得多有scripts/目录的优先说明作者把确定性逻辑脚本化了执行更稳。别想太多找一个你每天重复做的事花 30 分钟封装成 Skill。第一次可能粗糙跑起来之后你会发现问题然后迭代这比看十篇教程有用。
