企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api （这个不加 UTM）。你需要准备的东西只有两样：一个 API Key，一个模型 ID。

先到控制台创建 Key，路径是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面生成，形如sk-开头的一串字符。生成后立刻复制保存，页面刷新后不再完整显示。模型 ID 则根据你的任务选：机械活选快的，架构审查选强的。

这里有个新手最容易踩的坑：把 Base URL 写成带/v1或带具体路径的形式。TaoToken 的 API 根地址就是https://taotoken.net/api，客户端一般会自己拼接后续路径。你多写一段，请求就会 404。我试过在某个客户端里手滑加了斜杠，排查了十几分钟才发现是地址问题。

配置方式取决于你用什么客户端。如果你用 Claude Code 这类工具，通常通过环境变量注入：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的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_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，发一句“你好”，能正常回复就说明 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 写进日志，必须脱敏。

一张表对照：

前两项是基本盘，中间七项是按需开启的开关，最后两项属于工程质量。

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_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 重新生成一个对比测试。

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_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它解决的是“频繁调用下的通道稳定性”问题，让你不用每次手动配 Key。

如果你更想先深入理解 Skill 与模型的交互细节，可以到接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 看完整的参数说明。Claude Code 相关的接入细节在 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。

回到最初的问题：一个 Skill 规定了什么？它规定了身份（name）、触发条件（description）、参数提示（argument-hint）、调用权限（disable-model-invocation / user-invocable）、工具边界（allowed-tools）、运行方式（model / context / agent），以及通过 hooks 和 audit.log 实现的安全检查与可追溯性。正文只负责“被加载后怎么做”，而上面这些字段决定了它“能不能被看见、能不能被安全调用”。

新手最容易犯的错，是把精力全花在正文上，却让 description 写得含糊、权限字段乱设。记住一句话：正文决定 Skill 被加载后能不能做对，description 决定 Skill 能不能被看见。先把这两项打磨好，再去优化流程细节。