一个 Skill 里规定了哪些东西?—— 新手入门指南(TaoToken 版) 1. 从一次“Skill 没触发”说起SKILL.md 到底规定了什么你写完一个 Skill放进目录重启 Claude然后输入一句自认为“绝对该命中”的话——结果它毫无反应像没装过一样。这种场景我见过太多次问题往往不在正文写得好不好而在于你没搞清楚一个 Skill 到底规定了哪些东西。先把概念说清楚Skill 是给 Claude 写的“专业说明书”它规定了三件事——什么情况下翻开它、翻开后按什么步骤干、干活时有哪些规则和边界。承载这份说明书的文件叫SKILL.md它分成两个部分头顶的 YAML 配置区决定规则和下面的正文指令区决定流程。配置区里那些字段才是决定 Skill 能不能被“看见”、能不能被安全调用的关键。这篇面向刚接触 Claude 生态的新手把SKILL.md的组成结构逐层拆开YAML 元数据每一项管什么、hooks 触发和 description 触发有什么本质区别、文件该怎么组织。中间会给出可直接复制的SKILL.md模板和 YAML 片段并用 TaoToken 统一 Key 与 API 通道完整跑一次 Skill 调用验证。适合谁适合已经会写 prompt、但被 Skill 的字段和触发机制绕晕的人。核心检索词先记住SKILL.md 的 YAML 元数据规定了 Skill 的身份、触发条件、权限边界和运行方式而正文只规定“被加载后怎么做”。搞反这两者的权重就会写出“内容很全但永远不触发”的 Skill。2. TaoToken 前置把 Key 和 API 通道统一起来在拆字段之前先把调用通道铺好。Skill 本身是本地文件但你要验证它是否真的被加载、是否真的调用了模型就需要一个稳定的 API 入口。TaoToken 在这里的作用是用一个 Key、一个 Base URL 统一管理模型调用省得你在多个平台之间来回切换配置。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。你需要准备的东西只有两样一个 API Key一个模型 ID。先到控制台创建 Key路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面生成形如sk-开头的一串字符。生成后立刻复制保存页面刷新后不再完整显示。模型 ID 则根据你的任务选机械活选快的架构审查选强的。这里有个新手最容易踩的坑把 Base URL 写成带/v1或带具体路径的形式。TaoToken 的 API 根地址就是https://taotoken.net/api客户端一般会自己拼接后续路径。你多写一段请求就会 404。我试过在某个客户端里手滑加了斜杠排查了十几分钟才发现是地址问题。配置方式取决于你用什么客户端。如果你用 Claude Code 这类工具通常通过环境变量注入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key如果你用支持settings.json的编辑器插件就写进配置文件。下面这段是通用结构路径按你实际客户端的约定放{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意三件套必须齐全Base URL Key Model ID。少任何一个请求都会失败而且报错信息各不相同——少 Key 报 401少 Model 可能报模型不存在地址错则连接失败。把这三样固定下来后面验证 Skill 时就不会被环境问题干扰。配好之后先别急着写 Skill用一次最简单的对话确认通道是通的。打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 发一句“你好”能正常回复就说明 Key 和地址没问题。这一步花两分钟能省掉后面半小时的无效排查。3. 可复制配置SKILL.md 的 YAML 元数据逐项拆解现在进入正题。一个 Skill 的目录结构通常长这样.claude/skills/ └── code-reviewer/ ├── SKILL.md ├── hooks/ │ └── pre-tool-use.sh └── audit.log文件夹名code-reviewer必须和SKILL.md里的name字段完全一致这是硬性要求。下面是一份可直接复制的SKILL.md模板YAML 配置区覆盖了主要字段--- name: code-reviewer description: 该 skill 应在用户要求审查代码、检查潜在 bug、评估代码质量或提到 code review 时使用。支持 Python、JavaScript、Go 等语言输出结构化审查意见。 argument-hint: [文件路径或代码片段] disable-model-invocation: false user-invocable: true allowed-tools: - Read - Grep - Bash(git diff:*) model: sonnet context: fork agent: Explore --- ## 审查流程 1. 读取目标文件或代码片段 2. 检查命名规范、错误处理、边界条件 3. 按严重程度分级输出问题 4. 给出可执行的修改建议逐项说清楚每个字段规定了什么。name是身份证。只能用小写字母和短横线最长 64 字符且必须和文件夹同名。它决定了系统怎么找到它、用户怎么手动调用输入/code-reviewer、会不会撞名。description是整个 Skill 的灵魂决定 Claude 会不会在合适时机自动加载。原理是Claude 启动时扫描所有 Skill 的 name 和 description装进“能力目录”每个约占用 100 token 常驻空间。你提任务时它靠语义理解去匹配——不是关键词、不是正则所以同一 prompt 在不同 session 下触发结果可能不同。description 最长 1024 字符但主要看前 250 字符做决策触发关键词必须前置。系统最多同时管理 30 个 Skill超出的会被静默丢弃。写法上要用第三人称客观陈述并把用户可能说出的各种说法都列进去因为 AI 天然有欠触发倾向。argument-hint是参数提示牌只做提醒不做校验。用人话写清参数名别写arg1。disable-model-invocation是防 AI 手贱的安全锁。设为true后 Claude 完全不知道它存在只有用户手动敲命令才能唤醒。部署生产、删库、发版这类操作必须加这把锁。user-invocable跟上面相反。设为false后从菜单消失但 Claude 仍能自动加载适合团队编码规范这类“后台知识”。这两条组合出三种模式默认都能触发、纯手动危险操作、纯自动后台知识。千万不要两条都禁掉那样 Skill 就废了。allowed-tools是工具白名单列表里的工具自动跳过权限弹窗。可以细化到只允许特定 bash 命令比如Bash(git diff:*)。没列出的工具不是不能用只是需要逐次手动批准。model选模型haiku 快而便宜适合格式化sonnet 均衡opus 最强最慢。一般不用填切换模型会清空上下文缓存有额外成本。context设为fork后 Skill 在独立子代理中运行与主对话隔离。好处是不撑爆主上下文且给 Skill 一张白纸。适合代码审计、大规模文件分析。agent配合上一条使用。Explore 型只有只读工具适合快速搜索Plan 型适合先研究再规划general-purpose 型什么都能干。hooks不属于SKILL.md字段而是目录里一套独立配置。它在关键时刻插入检查工具调用前校验参数、调用后格式化或记日志、结束时清理临时文件。hooks 和 description 触发的本质区别是description 靠 AI 智能判断hooks 靠确定性规则。安全要求高的场景优先用 hooks。audit.log也是通过 hooks 实现每次工具调用后追加一条记录。绝对不要把密码、API Key 写进日志必须脱敏。一张表对照配置项作用必填/可选name叫什么、怎么找到必填description什么时候用灵魂必填argument-hint用户传什么参数可选disable-model-invocation防 AI 自调用可选user-invocable控制用户手动调可选allowed-tools权限边界可选model用哪个模型可选context是否隔离运行可选agent子代理类型可选hooks关键节点安全检查可选audit.log操作留痕可选前两项是基本盘中间七项是按需开启的开关最后两项属于工程质量。4. 验证请求用 TaoToken 跑一次 Skill 调用配置写完必须验证它真的能被加载和调用。这一步用 TaoToken 的通道来跑确保环境变量已经按第 2 节配好。先确认 Skill 文件被正确识别。在 Claude Code 里输入斜杠看菜单里有没有出现code-reviewer。如果user-invocable是true它应该出现在列表里。没出现先检查文件夹名和name是否一致。然后做一次手动调用验证。准备一个待审查的小文件def divide(a, b): return a / b在对话里输入/code-reviewer 请审查这段代码如果 Skill 被正确加载Claude 会按正文里的流程走读取、检查、分级输出。你会看到它指出“未处理除零”这类问题。这一步验证的是手动调用链路。接着验证自动触发。新开一个 session输入一句自然语言帮我看看这段代码有没有潜在 bug如果description写得够宽Claude 应该自动加载code-reviewer。这里要注意自动触发有概率性同一句话多试几次可能结果不同。如果连续多次都不触发问题几乎一定出在description上——把触发关键词往前提把用户可能说的口语变体补进去。验证 hooks 是否生效可以在hooks/pre-tool-use.sh里写一段简单逻辑比如拦截包含rm -rf的命令#!/bin/bash if echo $TOOL_INPUT | grep -q rm -rf; then echo 危险命令已拦截 exit 1 fi exit 0然后让 Claude 尝试执行一个删除命令观察是否被拦下。这一步验证的是确定性规则跟 description 的智能判断是两套机制。最后看audit.log有没有内容。如果 hooks 配好了每次工具调用后应该追加一条记录。用tail -f audit.log实时观察能清楚看到时间、工具名、操作内容。出问题时这就是回溯依据。整个验证流程跑通说明你的 Skill 从身份、触发、权限到审计都正常。任何一环断了回到对应字段排查。5. 本篇常见错排查401、local proxy failed 与 OAuth验证过程中最常见的几类报错逐个对照。401 Unauthorized。这是 Key 问题。检查三处Key 是否复制完整有没有漏掉尾部字符、环境变量名是否写对ANTHROPIC_API_KEY不是ANTHROPIC_KEY、Key 是否已过期或被删除。到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 重新生成一个对比测试。local proxy failed / connection refused。这是地址问题。确认ANTHROPIC_BASE_URL是https://taotoken.net/api没有多余斜杠、没有/v1后缀。如果你本地开了其他网络工具占用端口也可能导致连接失败先关掉再试。reading choices of undefined。这个报错通常出现在响应结构不符合预期时根因往往是模型 ID 写错或该模型不可用。检查ANTHROPIC_MODEL是否拼写正确换一个模型 ID 再试。OAuth 相关报错。如果你用的是 Claude Code它可能尝试走 OAuth 登录流程而不是 API Key。这时要确认配置里走的是 API Key 模式环境变量优先级要高于登录态。必要时清理本地登录缓存重新配置。Skill 不触发。回到description前 250 字符有没有包含核心触发词是不是用了第一人称对话口吻Skill 总数有没有超过 30 个这三点是最常见原因。hooks 不执行。检查脚本有没有可执行权限chmod x路径是否写对以及 hooks 配置文件的格式是否符合客户端要求。hooks 是确定性机制不执行一定是配置问题不会是“概率没命中”。排查时记住一个原则先确认通道Key/地址/模型再确认 Skill 本身。通道不通Skill 写得再好也验证不了。6. 把 Skill 用起来从验证到长期编码字段拆完、验证跑通接下来就是把它用进日常。如果你只是偶尔审查代码手动调用/code-reviewer就够了。但如果你想让 Skill 参与长期编码流程——比如每次提交前自动审查、每次生成代码后自动格式化——那就需要一个稳定的调用通道和足够的额度支撑。TaoToken 的 Coding Plan 适合这种长期编码和 Agent 场景入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它解决的是“频繁调用下的通道稳定性”问题让你不用每次手动配 Key。如果你更想先深入理解 Skill 与模型的交互细节可以到接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 看完整的参数说明。Claude Code 相关的接入细节在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。回到最初的问题一个 Skill 规定了什么它规定了身份name、触发条件description、参数提示argument-hint、调用权限disable-model-invocation / user-invocable、工具边界allowed-tools、运行方式model / context / agent以及通过 hooks 和 audit.log 实现的安全检查与可追溯性。正文只负责“被加载后怎么做”而上面这些字段决定了它“能不能被看见、能不能被安全调用”。新手最容易犯的错是把精力全花在正文上却让 description 写得含糊、权限字段乱设。记住一句话正文决定 Skill 被加载后能不能做对description 决定 Skill 能不能被看见。先把这两项打磨好再去优化流程细节。