| 版本 | 内容 | 时间 | | ---- | ---- | ------------------- | | V1 | 新建 | 2026-07-10 10:00:23 | ## SKILL 基本介绍 ### 什么是 SKILL Skills 用于扩展 Claude 的任务执行能力。通过创建 `SKILL.md` 文件，可以为 Claude 定义一套可复用的操作流程、执行规范和辅助资源。 Claude 会在需要时加载对应 Skill，使其具备特定场景下的处理能力。支持两种触发方式 | 触发方式 | 说明 | 示例 | | --------------- | ------------------------------------------------------------ | ---------------------------- | | 用户显示触发 | 输出 `/SKILL名称` | /code-reviewer | | Claude 自动识别 | Claude 读取 description，语义匹配后自动加载 SKILL
LLM 语义推理，而非精确匹配 | 用户说：帮我 CR 一下这段代码 | ### 从 Agent 系统设计角度看 SKILL Skills 并不是简单的“能力扩展机制”，它本质上是一种**按需加载的认知结构**。与其把所有知识常驻在上下文中，不如把它们封装成可独立触发的能力单元。当模型判断当前任务涉及某个特定领域时，再加载对应的知识与操作流程。如果从 Agent 系统设计角度展开来看，Skills 并不是孤立存在的。一个完整的 Agent 生态通常包含四类核心能力，它们分别解决不同的问题： - **Tools：行动能力**。它表示的是能做什么，例如读文件、改代码、搜索内容、执行 bash 命令。但是 Tools 本身不知道为什么执行、什么时候执行、应该采取什么策略； - **Subagents：任务分工和上下文隔离**。它表示复杂任务如何拆解和隔离。当任务复杂，需要不同角色或者独立推理空间时，可以拆分给不同 Agent。每个 Subagent 都有自己的任务目标、独立的上下文、负责特定领域。 - **Hooks：事件驱动的流程规则**。它表示流程控制机制，例如：修改代码前自动检查；执行命令前进行验证；完成任务后运行测试；提交前执行质量检查。它解决是如何让流程自动受到约束。 - **Skills：可复用的方法和知识**。它表示面对某类任务，应该采取什么方法？是一种可操作的知识结构，是完成某类任务的方法论和流程模板。 | Agent 能力 | 类比 | | ---------- | -------------- | | Tools | 双手：执行动作 | | SubAgents | 同事：承担职责 | | Hooks | 制度：控制流程 | | Skills | 经验：指导方法 | ### SKILL 和 CLAUDE.md 的区别 | | 作用 | 适用场景 | 加载规则 | | --------- | ------------------ | ------------------------------------------------------------ | ------------------------------------------------ | | CLAUDE.md | 全局规则 | 技术栈约束；
编码规范；
架构说明；
项目约定。 | 通常每次会话都需要生效 | | Skill | 按需加载的执行流程 | 发布流程；
调试流程；
代码审查流程；
数据处理流程；
自动化任务步骤。 | 完整内容只会在需要时加载，避免长期占用上下文空间 | ### 自定义 Command 兼容升级旧版自定义 Command 已经逐步整合到 Skills 体系。旧结构： ``` .claude/commands/deploy.md ``` 推荐新结构： ``` .claude/skills/deploy/SKILL.md ``` 两种方式通常都可以生成：`/deploy`调用入口。如果存在同名定义，Skills 目录中的 Skill 通常具有更高优先级。相比旧版单文件命令，Skills 新增可选增强能力： - 配套资源目录：存放执行脚本、模板、示例文档； - 头部 YAML 配置：控制仅允许用户手动唤起，或允许 AI 自动触发； - 智能自动加载：对话匹配对应业务场景时自动读取SKILL内容。 ## Claude Code 内置 Skills ### 内置 Bundled Skills 基础说明 Claude Code 内置了一组开箱即用的 **Bundled Skills（内置SKILL）**，默认情况下可直接使用。如需关闭内置SKILL，可通过配置项：`disableBundledSkills` 进行禁用。内置SKILL包含：`/code-review`、`/batch`、`/debug`、`/loop`、`/claude-api`。与传统固定逻辑的内置命令不同，Skills 基于提示词驱动的执行体系实现。它不会预先固化所有操作逻辑，而是向 Claude 提供完整的任务说明、执行规范和处理流程，由 Claude 根据当前上下文自主选择工具并完成整个工作流。调用方式与自定义 Skills 完全一致：直接输入 `/SKILL名` 即可触发。所有内置 Skills 会与基础命令统一展示在命令参考列表中，并通过 **Skill** 标识进行区分。 ### 应用启动与校验配套三件套SKILL Claude Code 提供三项配套SKILL，用于启动项目并通过真实运行环境验证代码修改效果。 | SKILL命令 | 核心作用 | | ---------------------- | ------------------------------------------------ | | `/run` | 启动项目并运行应用，直观验证代码修改是否生效 | | `/verify` | 构建并启动项目，通过实际运行状态验证代码变更效果 | | `/run-skill-generator` | 根据当前项目环境生成专属运行流程 Skill | > 使用要求：相关SKILL需要较新的 Claude Code 版本支持，具体以当前版本能力为准。 --- ① **无配置自动推断模式（/run/verify 原生能力）** `/run`、`/verify` 开箱即用，无需提前配置。执行时，Claude 会自动分析项目结构，例如： - 项目类型； - 构建工具； - 启动脚本； - 项目说明文档。同时读取常见配置文件：README、package.json、Makefile 等内容，推断项目启动方式。局限：仅适用于标准化项目、一键安装依赖、一条命令即可启动；如果项目依赖额外环境（数据库、环境变量文件、图形会话、多步骤链式构建），自动推断很容易出错、执行失败。这类项目建议使用 `/run-skill-generator` 固化流程。 --- ② **固化项目启动流程：/run-skill-generator 生成专属启动脚本** 针对复杂项目，使用 `/run-skill-generator` 生成适配当前项目的专属运行 Skill。： - 在完整环境中验证项目启动流程； - 工具自动记录所有有效步骤：依赖安装命令、所需环境变量、启动脚本、前置准备操作； - 自动在项目内生成专属 SKILL 目录：`.claude/skills/run-<项目名>/` 固化完成后，后续调用 `/run`、`/verify`、项目内所有子代理都会直接复用这套记录好的启动流程，不再重复自动推断。使用建议：每个项目执行一次生成；如果后续构建、启动流程发生改动，重新运行一次该命令更新对应的 SKILL。 ## 快速开始一个 SKILL ### 示例需求我们创建一个 Git 变更汇总 Skill：目标： - 自动读取仓库当前未提交代码差异； - 总结代码改动内容； - 识别潜在高风险修改。该 Skill 会通过动态上下文注入机制执行 `git diff`，将实时工作区变化提供给 Claude，使其基于当前代码状态进行分析。支持两种调用方式： 1. Claude 根据 Skill 描述和当前任务上下文自动判断是否加载； 2. 用户手动输入：`/summarize-changes`直接执行。 ### 步骤 1：创建SKILL目录（全局个人SKILL）存放路径 `~/.claude/skills/` 下的 SKILL 对本机**所有项目全局生效**。执行命令创建 SKILL 文件夹，文件夹名称就是后续调用的斜杠命令名： ``` mkdir -p ~/.claude/skills/summarize-changes ``` ### 步骤 2：编写 SKILL.md 核心文件每个 SKILL 必须包含 `SKILL.md`，分为两部分： 1. YAML 头部元配置（`---` 包裹）：定义功能说明、使用场景、自动调用权限等信息； 2. Markdown 正文：定义 Claude 加载该 Skill 后需要遵循的任务流程。将以下内容保存至 `~/.claude/skills/summarize-changes/SKILL.md` ```markdown --- description: 汇总Git未提交代码变更，识别代码风险。适用于用户询问改动、生成提交信息、评审代码差异场景。 --- # 当前代码变更 !`git status --short && git diff HEAD` # 执行规则 1. 用2-3条简短要点总结上述代码改动； 2. 列出所有潜在风险：缺失异常捕获、硬编码常量、未同步更新测试用例等； 3. 若无任何未提交变更，直接告知无改动。 ``` 动态上下文注入说明 Skill 中： ``` !`git status --short && git diff HEAD` ``` 属于 Claude Code 的动态上下文注入语法。当 Claude 加载该 Skill 时： 1. 执行对应 Shell 命令； 2. 获取命令输出； 3. **将 Shell 命令的结果作为 Skill 上下文提供给 Claude；** 4. Claude 根据实时数据执行后续分析。这样可以避免手动复制 Git Diff，让 Skill 始终基于最新工作区状态运行。区分： - **@文件路径**：引用已有文件内容，为 Claude 提供静态上下文 - **!\`终端命令\`**：执行 Shell 命令，将实时输出动态注入上下文 ### 步骤 3：测试 SKILL - 打开任意 Git 代码仓库，修改文件产生未提交变更； - 启动 Claude Code 会话，两种测试方式： **方式 ①：自动匹配触发（依赖 description 描述）** 直接自然提问：`我刚才改了哪些代码？`AI 识别场景后自动加载并运行该SKILL。 **方式 ②：手动斜杠命令直接执行** 在 cluade CLI 中输入斜杠，你将会看到 /summarize-changes 的 skill 选项。 ``` /summarize-changes 汇总Git未提交代码变更，识别代码风险。适用于用户询问改动、生成提交信息、评审代码差异场景。 (user) ``` 输入： ``` /summarize-changes ``` 两种方式都会输出代码改动摘要与风险提示。 ## SKILL 完整加载规则 ### 标准 SKILL 目录结构每个 Skill 必须包含 `SKILL.md` 作为入口文件，其余资源根据需求按需添加。也就是“**导航页 + 详情页**”模式 ``` my-skill/ ├── SKILL.md # 导航页：概述 + 引用（< 500 行） ├── reference.md # 详情页：详细 API 文档 ├── template.md # 可选：输出模板 ├── examples/ │ └── sample.md # 可选：示例输出，规范结果格式 └── scripts/ └── validate.sh # 可选：辅助脚本 ``` Skill 可以通过 `SKILL.md` 引用同目录下的模板、示例、脚本等资源，以扩展 Claude 的处理能力。 `.claude/commands/` 仍然兼容使用；但对于需要组合指令、上下文资源和辅助文件的复杂工作流，推荐使用 Skill。 > [!warning] > > **渐进式加载：SKILL.md 应该被控制在 500 行以内。如果过于复杂，应该将详细参考资料移到独立文件，并在 SKILL.md 中进行引用** ### SKILL 存放位置、生效范围与加载优先级 Claude Code 支持在不同作用域存放 Skill。Skill 所在位置决定了它的生效范围，同时同名 Skill 会根据加载规则进行优先级处理。 | 层级 | 存放路径 | 生效范围 | 版本控制 | | -------------- | ---------------------------------------------- | -------------------------------- | ---------- | | 企业级 | 企业管理后台托管配置 | 组织内所有用户、所有项目统一生效 | 集中管理 | | 个人全局 | `~/.claude/skills//SKILL.md` | 当前用户所有项目可用 | 个人本地 | | 项目级 | 项目根目录 `.claude/skills//SKILL.md` | 当前项目生效，可随代码仓库共享 | git | | 插件内置 SKILL | `<插件目录>/skills//SKILL.md` | 启用对应插件时可用 | 随插件分发 | **覆盖规则（优先级从高到低）** 1. 企业级 > 个人全局 > 项目本地；任意层级自定义 SKILL，都会覆盖 Claude 官方内置同名 SKILL； 2. 插件 SKILL 采用 `plugin名:skill名` 独立命名空间，不会和企业 / 个人 / 项目 SKILL 产生命名冲突 3. 旧版 COMMAND 目录 `.claude/commands/` 加载逻辑和 SKILL 一致；若 SKILL 和 COMMAND 重名，**SKILL 优先执行** ### 单仓库嵌套子目录 SKILL Claude Code 会加载工作目录及其子目录中的 `.claude/skills/`，支持在 monorepo 场景下为不同业务包配置独立的专属 Skills。 - 在子目录中处理代码时，该目录下的 Skills 会自动参与匹配，无需手动指定完整路径。适合多包单仓结构，让每个业务包维护自己的开发规范、部署流程或自动化能力。 - 根目录与子目录存在同名 SKILL 不会互相覆盖，两者共存： - 根目录 `deploy`：直接输入 `/deploy` 调用 - `apps/web` 下同名 `deploy`：完整限定名 `/apps/web:deploy` 手动调用 - 当 Claude Code 在子目录文件上工作时，会识别对应目录下的限定 Skill，并根据当前处理的文件位置选择适用的版本。 > 该能力最低要求：Claude Code v2.1.203 ### SKILL 打包为独立插件将 Skills 打包为插件时，需要在插件根目录新增 `.claude-plugin/plugin.json` 作为插件清单。插件可以作为独立扩展加载，并通过插件 namespace 区分 Skill 名称。插件内的 Skill 会以：`/plugin-name:skill-name`形式调用，例如：`/my-plugin:deploy` 插件除了 Skills，还可以组合： - Agent - Hooks（生命周期钩子） - MCP Server - LSP 配置 - Commands 等扩展能力适用于团队共享、跨项目复用以及版本化分发。 ### SKILL 的渐进式加载 ```mermaid flowchart LR A["用户输入"]:::purple --> B["读取可用 Skills 的元数据
(name + description)"]:::blue B --> C["模型判断当前任务
是否需要某个 Skill"]:::blue C --> D{是否需要 Skill?}:::blue D -- 是 --> E["加载对应 Skill 的 SKILL.md
获取详细执行指导"]:::green E --> G["结合 Skill 指令执行任务"]:::green D -- 否 --> F["按照默认能力处理请求"]:::pink classDef purple fill:#f3e8f8,stroke:#c9b0d8 classDef blue fill:#d0e8f8,stroke:#80b8e0 classDef green fill:#e0f4e8,stroke:#88ccaa classDef pink fill:#fff2e8,stroke:#f2c8a8 ``` 假设你有 5 个 Skills，每个 SKILL.md 约 1000 tokens。那么： | 加载策略 | 用户请求代码审查 | 用户请求普通问题 | | ------------------- | -------------------------------------- | --------------------- | | 全量加载所有 Skills | 5000 tokens | 5000 tokens | | 渐进式加载 Skills | 元数据 + 匹配 Skill 内容 ≈ 1100 tokens | 仅元数据 ≈ 100 tokens | 这体现了 Skills 设计中的核心思想：**渐进式披露（Progressive Disclosure），先暴露轻量级能力描述，在确定需要时，再加载完整执行方法。** ## SKILL 的分类：参考型和任务型 ### 参考知识型（怎么做）给 Claude 补充**背景知识和规范约定**，相当于一份 "常驻代码规范手册"。典型内容：编码规范、API 设计约定、领域业务知识、项目特有模式、风格指南。 **调用特点** - **自动内联生效**：SKILL加载后内容直接融入对话上下文，Claude 写代码时自动参照执行 - 不需要你手动 `/skill-name` 触发，Claude 自己判断什么时候用 - 适合 "约定类、规范类、知识类" 内容示例： ```markdown --- name: api-conventions description: 本仓库的 API 设计规范 --- 编写接口时遵守以下约定： - 接口命名遵循 RESTful 风格 - 错误返回格式统一 - 所有入参必须做校验 ``` --- ### 任务步骤型（做什么）给 Claude 一套**明确的分步执行指令**，相当于一个 "可执行脚本"。典型场景：部署流程、提交规范、代码生成模板、固定操作流程。调用特点 - **手动触发为主**：通常由你输入 `/skill-name` 主动调用，而不是让 Claude 自己决定什么时候跑 - 适合 "流程固定、步骤明确" 的操作 - 两个关键配置： - `context: fork`：在独立子代理（subagent）里执行，不污染主对话上下文 - `disable-model-invocation: true`：**禁止 Claude 自动触发**，必须手动输入指令才会执行示例 ```markdown --- name: deploy description: 部署应用到生产环境 context: fork disable-model-invocation: true --- 按以下步骤执行部署： 1. 运行全量测试 2. 构建应用产物 3. 推送到部署目标 ``` ## SKILL 的配置 ### Skill 配置字段完整说明 > 参考：https://code.claude.com/docs/en/skills#frontmatter-reference 在 `SKILL.md` 顶部用 `---` 包裹的 YAML 区块叫 frontmatter，用来配置SKILL的行为。所有字段都是可选的，**只有 `description` 建议必填**——Claude 靠它判断什么时候自动触发这个SKILL。 ```yaml --- name: my-skill description: SKILL功能描述 disable-model-invocation: true allowed-tools: [Read, Grep] --- SKILL正文指令... ``` | 字段名 | 必填 | 默认值 | 作用说明 | | ---------------------------- | ---- | -------------- | ------------------------------------------------------------ | | **name** | 否 | 目录名 | SKILL列表中显示的展示名称 | | **description** | 推荐 | 正文第一段 | 描述SKILL功能与适用场景，Claude 据此判断是否自动加载。开头直接写核心用途，控制在 1536 字符内，超过的字符会被截断 | | **when_to_use** | 否 | — | 补充字段，专门写**触发关键词和典型场景示例**；最终会拼在 description 后面一起算字数，共享 1536 字符上限。典型场景：写明 "当用户问 XX 时使用"，提高自动触发准确率 | | **argument-hint** | 否 | — | `argument-hint` 就是你输入 `/SKILL名` 时，自动补全弹窗里显示的**参数提示文字**，纯展示用，告诉用户这个SKILL需要传什么参数，不做任何校验。 | | **arguments** | 否 | — | 给SKILL定义**带名字的位置参数**，用户调用SKILL时传的参数，会按顺序替换正文里的 `$参数名` 变量。**典型场景**：SKILL需要接收外部输入时使用 | | **disable-model-invocation** | 否 | `false` | 设为 true 禁止 Claude 自动加载，只能手动 `/SKILL名` 触发；同时子代理也不会自动执行。从 v2.1.196 版本起，只要SKILL开了 `disable-model-invocation: true`，**就算你在定时任务里写了 "调用这个SKILL"，到点了也不会执行**。 | | **user-invocable** | 否 | `true` | 设为 false 后从 `/` 命令菜单隐藏，用户看不到也不能直接调用。**典型场景**：纯背景知识库类SKILL，只供 Claude 内部参考 | | **allowed-tools** | 否 | — | 给SKILL**预授权工具白名单**—— 这个SKILL激活时，名单里的工具 Claude 可以直接用，不用每次都问你 "能不能调用 XX 工具"。持空格或逗号分隔的字符串，也支持 YAML 列表格式。**典型场景**：给自动化SKILL预先授权 Read/Grep 等常用工具 | | **disallowed-tools** | 否 | — | **工具黑名单**—— 将从 Claude 的可用工具池中移除指定工具。适用于不应调用某些工具的自主运行型SKILL，例如后台循环任务需禁用AskUserQuestion。支持空格或逗号分隔的字符串，也支持 YAML 列表格式。你发送下一条消息时，该限制自动失效。典型场景**：适合后台自动跑的SKILL，防止它调用需要人工交互的工具把流程卡死。 | | **model** | 否 | 会话当前模型 | 临时切换执行模型，仅当前轮生效，下条消息自动恢复。**典型场景**：复杂SKILL临时切更强模型，简单SKILL切省 token 型号 | | **effort** | 否 | 继承会话 | 临时调整思考深度：low /medium/high /xhigh/max
给这个SKILL单独调**AI 思考深度**，SKILL跑的时候用这个级别，跑完自动恢复会话原来的设置。级别越高想的越细、质量越高，但也越费 token、越慢。 | | **context** | 否 | 内联 | 让SKILL**在一个独立的 "子进程" 里跑**，有自己独立的上下文，跑出来的中间过程不会污染你主对话的记忆。**典型场景**：长流程、重任务，避免主对话被撑爆 | | **agent** | 否 | 默认子代理类型 | 配合 `context: fork` 指定子代理类型。**典型应用**：特殊任务需要特定子代理时使用 | | **paths** | 否 | — | 用于限定SKILL自动激活时机的 glob 匹配模式。支持逗号分隔的字符串或 YAML 列表。设置后，Claude 仅在操作匹配该模式的文件时，才会自动加载该SKILL。格式与路径专属规则（path-specific rules）相同。**典型场景**：前端专属SKILL只在改 .vue/.tsx 文件时加载 | | **shell** | 否 | `bash` | SKILL内 `!命令` 代码块使用的 shell，可选 `powershell` | | **hooks** | 否 | — | 就是SKILL的**生命周期回调函数**—— SKILL开始前、结束后等时机可以自动触发一些钩子逻辑，只在这个SKILL的生命周期里管用 | ### SKILL 调用命令名的命名规则 **输入 `/xxx` 调用SKILL时，命令名由文件目录位置决定，frontmatter 中的 `name` 字段仅作为列表展示名称，不影响实际调用命令。** 唯一例外：插件根目录下的 `SKILL.md`，其 `name` 字段会决定调用名。 | 存放位置 | 命令名来源 | 示例路径 → 调用命令 | | ------------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------ | | 个人 / 项目级SKILL目录`~/.claude/skills/` 或 `.claude/skills/` | 目录名 | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging` | | 嵌套子目录SKILL（与根目录重名时）子目录内的 `.claude/skills/` | 相对工作目录路径 + 冒号 + SKILL目录名 | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` | | 旧版命令文件`.claude/commands/` | 文件名（去掉扩展名） | `.claude/commands/deploy.md` → `/deploy` | | 插件内SKILL插件目录下的 `skills/` 子目录 | 插件名：SKILL目录名（命名空间隔离） | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review` | | 插件根目录 SKILL.md | frontmatter 的 `name` 字段，未填写则用插件目录名兜底 | `my-plugin/SKILL.md` 配置 `name: review` → `/my-plugin:review` | **关键说明** - **`name` 字段的作用**：仅用于SKILL列表的展示标签，不改变 `/` 后面实际输入的调用名；插件根目录 SKILL.md 是唯一例外 - **嵌套重名处理**：正常情况下嵌套SKILL也可用短名调用；与根目录SKILL重名时，嵌套SKILL自动加上路径前缀，避免冲突 - **插件命名空间**：**所有插件SKILL都带 `插件名:` 前缀，天然隔离**，不会和全局 / 项目SKILL产生命名冲突 ### SKILL 字符串替换变量 SKILL正文里可以用变量占位符，执行时自动替换成实际值。分为两类：**入参变量**和**系统环境变量**。 **入参相关变量** | 变量写法 | 说明 | | --------------- | ------------------------------------------------------------ | | `$ARGUMENTS` | 调用SKILL时传入的所有参数，原样输出；如果正文里没写这个变量，系统会自动在末尾追加 `ARGUMENTS: <传入值>` | | `$ARGUMENTS[N]` | 按下标取第 N 个参数，从 0 开始计数，比如 `$ARGUMENTS[0]` 是第一个参数 | | `$N` | 简写形式，`$0` = 第一个参数，`$1` = 第二个参数，以此类推 | | `$参数名` | 命名参数，需在 frontmatter 的 `arguments` 字段声明；按顺序对应位置，比如声明 `arguments: [issue, branch]`，则 `$issue` 对应第一个参数，`$branch` 对应第二个 | **系统环境变量** | 变量写法 | 说明 | 典型用途 | | ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | | `${CLAUDE_SESSION_ID}` | 当前会话 ID | 打日志、创建会话专属文件、关联SKILL输出与会话 | | `${CLAUDE_EFFORT}` | 当前思考深度级别：low /medium/high /xhigh/max注：Ultracode 不算独立级别，显示为 xhigh | 根据思考深度动态调整SKILL指令 | | `${CLAUDE_SKILL_DIR}` | `SKILL.md` 所在目录的绝对路径插件SKILL指向插件内的SKILL子目录，不是插件根目录 | 在 bash 命令里引用SKILL自带的脚本 / 资源文件，不受当前工作目录影响 | | `${CLAUDE_PROJECT_DIR}` | 项目根目录绝对路径，和hook、MCP 服务拿到的是同一个值 | 引用项目本地脚本，比如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，和SKILL装在哪无关 | 补充说明 - `${CLAUDE_PROJECT_DIR}` 需要 v2.1.196 及以上版本。这个变量**同时作用于SKILL正文和 frontmatter 的 `allowed-tools`**，比如权限规则 `Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)` 会和正文解析成同一路径 - **参数传递规则**：采用 shell 风格的引号处理多个单词组成一个参数时，用引号包裹。示例：`/my-skill "hello world" second` - `$0` → `hello world` - `$1` → `second` `$ARGUMENTS` 永远原样输出完整输入字符串，不做拆分 - **转义规则**：想输出字面量 `$`（比如写价格 `$1.00`），在前面加反斜杠转义：`\$1.00` - 只有紧跟在变量标识符前的**单个反斜杠**才会转义 - 其他位置的 `\$` 保持不变 - 双反斜杠 `\\$1` 不转义，两个反斜杠保留，且 `$1` 仍然会被替换成参数值示例： ```yaml --- name: session-logger description: 记录当前会话的活动日志 --- 将以下内容写入 logs/${CLAUDE_SESSION_ID}.log： $ARGUMENTS ``` 调用：`/session-logger 用户执行了部署操作` 实际替换后： ``` 将以下内容写入 logs/abc123xyz.log：用户执行了部署操作 ``` ### SKILL 配套文件机制 SKILL目录里不只有 `SKILL.md`，还可以放各种配套文件。**主文件只写核心逻辑，大文档、示例、脚本单独存放，按需加载**—— 避免SKILL一激活就把所有内容塞进上下文，省 token 也更清爽。 **为什么要拆文件**？大型参考文档、API 规范、示例集合这类内容，没必要每次跑SKILL都全部加载进上下文。 - `SKILL.md` 保持精简，只写概览和导航 - 详细资料放在独立文件里，用到才读取 ``` my-skill/ ├── SKILL.md # 必填，主文件：概览说明 + 导航指引 ├── reference.md # 详细 API 文档，按需加载 ├── examples.md # 使用示例，按需加载 └── scripts/ └── helper.py # 工具脚本，直接执行，不读入上下文 ``` **怎么让 Claude 知道有这些文件**？在 `SKILL.md` 里用 Markdown 链接引用配套文件，写明每个文件装了什么、什么时候该读： ```markdown ## 补充资源 - 完整 API 细节见 [reference.md](reference.md) - 使用示例见 [examples.md](examples.md) ``` **最佳实践**：**`SKILL.md` 控制在 500 行以内**，详细参考资料全部拆到独立文件里。类比理解：SKILL.md 是 README 索引页，配套文件是具体的文档章节，只在需要的时候翻到对应章节。 ### SKILL 调用权限控制默认情况下，**你和 Claude 都能调用任意SKILL**： - 你可以输入 `/SKILL名` 手动触发 - Claude 觉得相关时也会自动加载通过两个 frontmatter 字段可以限制调用方，形成三种权限模式。 | 参数 | 效果 | 使用场景 | | -------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | `disable-model-invocation: true` | 只有你能调用，Claude 不能自动触发。 | 有副作用、需要你控制时机的工作流，比如提交代码、部署、发消息。 | | `user-invocable: false` | 只有 Claude 能调用，你在命令菜单里看不到也不能直接调。 | 纯背景知识库类SKILL，不是一个可执行命令。 | 示例：部署 skill 仅支持手动调用。 ```markdown --- name: deploy description: 部署应用到生产环境 disable-model-invocation: true --- 将 $ARGUMENTS 部署到生产环境： 1. 运行全量测试 2. 构建应用 3. 推送到部署目标 4. 验证部署成功 ``` 这两个字段如何影响调用方式和上下文加载方式： | 配置 | 你能手动调用 | Claude 能自动调用 | 上下文加载方式 | | -------------------------------- | ------------ | ----------------- | ---------------------------------------------- | | **默认（不写）** | ✅ 可以 | ✅ 可以 | 描述常驻上下文，完整内容在调用时才加载 | | `disable-model-invocation: true` | ✅ 可以 | ❌ 不行 | 描述不进上下文，只有你手动调用时才加载完整内容 | | `user-invocable: false` | ❌ 不行 | ✅ 可以 | 描述常驻上下文，Claude 触发时加载完整内容 | > [!tip] > > - 常规会话的加载机制 > > 正常情况下，**只有 SKILL 描述常驻上下文**（让 Claude 知道有哪些SKILL可用），完整的SKILL内容只在真正调用时才加载进来，省 token。 > > - 子代理预加载不一样 > > 如果是子代理预加载的SKILL，机制不同 ——**启动时就把完整 SKILL 内容直接注入进去**，不是按需加载。 ### SKILL 内容的生命周期你或 Claude 调用SKILL后，渲染后的 `SKILL.md` 内容会**作为一条消息进入对话，并且一直保留到会话结束**。后续轮次 Claude Code **不会重新读取SKILL文件**。所以写法上要注意：需要全程生效的指引，要写成「常驻规则」，不要写成「一次性步骤」。 --- 当重复调用一个 SKILL 的处理方式 - **内容相同的情况** 如果重复调用时渲染出的内容和上下文里已有的完全一样，不会再塞一份完整内容，只加一条简短提示「该SKILL已加载」。 - **内容不同的情况** 如果参数变了，或者动态上下文命令产生了新输出，导致渲染结果不一样，就会**完整追加一份新内容**。 > [!warning] > > 版本差异：v2.1.202 之前的版本：每次重复调用都会完整追加一份SKILL指令，比较费 token。 --- **自动压缩机制（Auto-compaction）** 对话太长会触发自动摘要压缩，腾出上下文空间，SKILL 内容按以下规则处理： 1. **重新挂载**：压缩后，每个 SKILL 最近一次的调用内容会重新附在摘要后面 2. **单SKILL截断**：每个 SKILL 只保留前 5000 token 3. **总预算限制**：所有重新挂载的 SKILL 共享 25000 token 的总预算 4. **按新旧淘汰**：从最近调用的SKILL开始往里装，装不下的旧 SKILL 就直接整个丢掉 > 简单说：会话里调用的 SKILL 太多，老 SKILL 可能在压缩后就没了。 --- **常见问题： SKILL 好像不生效了怎么办？** - 情况一：内容还在，只是模型选了别的方案大多数情况 SKILL 内容其实还在上下文里，只是模型选择了其他工具或思路。 **解决**：把 SKILL 的描述和指令写得更强、更明确，让模型优先用它；或者用钩子强制 deterministic 行为。 - 情况二：被压缩弄丢了如果 SKILL 本身很大，或者你之后调用了很多其他 SKILL ，压缩后可能被挤掉了。 **解决**：压缩后重新调用一次 SKILL ，恢复完整内容。 ### SKILL 预授权机制 `allowed-tools` 参数是：给 SKILL 列的工具**预授权白名单**—— SKILL 激活时，名单里的工具 Claude 可以直接用，不用每次弹框问你同意。关键理解（别搞反） - ❌ 不是 "只能用这些工具" - ✅ 是 "这些工具不用问直接用" - 其他没列的工具照样能用，只是该问权限还是会问，受你的全局权限设置管控 --- **项目内 SKILL 的信任机制** 放在项目 `.claude/skills/` 目录里的SKILL，`allowed-tools` 不会立刻生效： - 需要你先接受**工作区信任弹窗**才会生效 - 和 `.claude/settings.json` 里的权限规则是同一套信任机制 > [!warning] > > 信任仓库前先检查一下项目里的SKILL，因为SKILL可以给自己授权很宽的工具权限，恶意SKILL有风险。 --- **精细授权语法**：支持按命令模式授权，不是只能写工具名： ```yaml allowed-tools: - Bash(git add *) - Bash(git commit *) - Bash(git status *) ``` 意思是：Bash 工具下执行 git 相关命令不用问，执行其他 Bash 命令该问还是问。 **完整示例** ```yaml --- name: commit description: 暂存并提交当前改动 disable-model-invocation: true allowed-tools: - Bash(git add *) - Bash(git commit *) - Bash(git status *) --- ``` 调用这个SKILL时，执行 git 相关命令不用每次确认。 --- **反向控制：禁用工具**，`disallowed-tools`（SKILL级黑名单） SKILL激活时，把列出的工具从可用池里直接移除，完全不能用。 - 只在SKILL激活期间生效 - 你发下一条消息后限制自动解除 ### SKILL 参数传递机制 ① **基本传参方式** 手动和 Claude 调用 SKILL 时都可以传参数，通过 `$ARGUMENTS` 变量获取传入的内容。 ```markdown --- name: fix-issue description: 修复 GitHub issue disable-model-invocation: true --- 按照编码规范修复 GitHub issue $ARGUMENTS 1. 读取 issue 描述 2. 理解需求 3. 实现修复 4. 编写测试 5. 提交代码 ``` 调用：`/fix-issue 123` 实际替换后： ```mark 按照编码规范修复 GitHub issue 123 1. 读取 issue 描述 ... ``` --- **② 没写 `$ARGUMENTS` 的兜底行为** 如果 SKILL 正文里没写 `$ARGUMENTS` 变量，你传了参数也不会丢 —— 系统会自动在 SKILL 内容末尾追加 `ARGUMENTS: <你输入的内容>`，保证 Claude 能看到。 --- **③ SKILL堆叠调用（v2.1.196+）** **功能**：一条消息开头可以连续写多个SKILL命令，一次性加载多个SKILL。 **示例**： ``` /code-review /fix-issue 123 ``` **效果**：同时加载 `code-review` 和 `fix-issue` 两个SKILL，末尾的 `123` 作为参数传给**每一个**SKILL。 > v2.1.199 之前：只加载第一个SKILL，后面的 `/fix-issue 123` 会被当成普通参数文本传进去。 **堆叠调用的规则** - 最多展开**第一个 + 后面 5 个**，共 6 个堆叠SKILL - 遇到第一个不是「内联可调用SKILL」的 token 就停止展开 - 停止点之后的所有内容，作为参数传给所有已经展开的SKILL **会停止展开的情况** - 分叉子代理类型的SKILL（`context: fork`） - 参数本身以 `/` 开头的SKILL（比如 `/loop`） - 遇到普通文字就停 --- **④ 按位置取单个参数** 两种写法等价 - `$ARGUMENTS[N]`：完整写法 - `$N`：简写形式下标从 0 开始，`$0` 是第一个参数，`$1` 是第二个。示例 ```yaml --- name: migrate-component description: 把组件从一个框架迁移到另一个 --- 将 $0 组件从 $1 迁移到 $2 保留所有原有功能和测试 ``` 调用：`/migrate-component SearchBar React Vue` 替换结果： - `$0` → `SearchBar` - `$1` → `React` - `$2` → `Vue` ## 高级模式 ### 动态注入上下文 **① 核心机制：!\`<command>\` 语法** 在 SKILL 内容里写 !\`shell命令\` ，**在发送给 Claude 之前就会先执行这条 shell 命令**，命令的输出会替换掉占位符。Claude 拿到的是最终数据，根本看不到命令本身。 **完整示例** ```markdown --- name: pr-summary description: 总结 PR 变更内容 context: fork agent: Explore allowed-tools: Bash(gh *) --- ## PR 上下文 - PR 差异：!`gh pr diff` - PR 评论：!`gh pr view --comments` - 变更文件：!`gh pr diff --name-only` ## 你的任务总结这个 PR... ``` 执行流程 - SKILL触发后，先依次执行所有 !\`...\`里的 shell 命令 - 命令输出替换掉对应的占位符 - 把渲染好的完整 prompt 发给 Claude - Claude 只看到最终的 PR 数据，不知道这些数据是怎么来的 > 关键：这是**预处理阶段**执行的，不是 Claude 运行时执行的。 --- **② 重要特性** 1. 只执行一次，不递归只对原始文件扫描替换一遍。命令输出里就算再有 !\`...\` 占位符，也不会再执行第二遍。 > 防止命令输出意外注入新的可执行命令。 2. 语法识别规则 `!` 必须出现在**行首**或者**紧跟空白字符之后**才会被识别。 - ✅ 行首：!\`cmd\` - ✅ 空白后：- !\`cmd\` - ❌ 跟在其他字符后：KEY=!\`cmd\`（会原样保留，不执行） --- **③ 多行命令写法** 单行写不下的，用 ```! 围栏代码块： ````markdown ## 环境信息 ```! node --version npm --version git status --short ``` ```` --- **④ 全局禁用开关** 在 settings.json 里设置 `"disableSkillShellExecution": true` 效果 - 用户/项目/插件/附加目录来源的 SKILL ，shell 命令全部不执行 - 占位符会被替换成 `[shell command execution disabled by policy]` - **官方内置和托管SKILL不受影响** 适用场景企业托管配置里用，用户不能覆盖，防止自定义SKILL执行任意 shell 命令。 --- **⑤ 深度推理提示** SKILL 内容里任意位置写上 `ultrathink`，触发时会开启深度推理模式。 > 相当于一次性加强思考深度，具体看 https://code.claude.com/docs/en/model-config#use-ultrathink-for-one-off-deep-reasoning 专门文档。 ### 在子代理中独立运行 SKILL 在 frontmatter 加上 `context: fork`，SKILL会开启隔离执行模式；整个 `SKILL.md` 的内容会直接作为子代理的完整提示词；关键隔离特性：**子代理读取不到主对话的聊天历史**，完全独立上下文。 > [!warning] > > `context: fork` 只适合**带有明确执行任务**的 SKILL； > > 如果 SKILL 只有规范、标准、参考文档，没有具体待办任务，子代理只会拿到一堆规则，没有执行目标，最终返回无有效内容。两种「SKILL + 子代理」协作模式对比 | 模式 | 系统提示词来源 | 执行任务 | 额外加载内容 | | ------------------------- | ------------------- | --------------------- | --------------------------------------------- | | SKILL配置 `context: fork` | 你指定的 agent 类型 | 整个 SKILL.md 全文 | 默认加载 `CLAUDE.md`；`Explore/Plan` 类型除外 | | 子代理配置 `skills` 字段 | 子代理自身 md 正文 | Claude 下发的委派任务 | 预加载 SKILL + `CLAUDE.md` | 开启 fork 后，任务写在 SKILL 里，再通过 `agent: xxx` 指定子代理类型执行；内置的 `Explore`（调研）、`Plan`（方案规划）两种代理会刻意精简上下文：**不会加载 CLAUDE.md、不会读取 git 状态**；因此搭配 `agent: Explore` 的分叉SKILL，仅能读取当前 `SKILL.md` + 该代理自带系统提示词，无额外冗余内容，节省 Token。示例：基于 Explore 子代理的调研SKILL 这份示例演示：搭配 `context: fork` + `agent: Explore`，让 SKILL 在独立隔离的 Explore 子代理里执行代码库检索分析任务。整个 SKILL 正文会直接作为子代理的执行任务，Explore 代理自带一套只读工具，专门适配代码库查阅场景。 ```markdown --- name: deep-research description: 对指定主题深度调研 context: fork agent: Explore --- 深度调研 $ARGUMENTS 相关内容： 1. 通过 Glob、Grep 查找相关代码文件 2. 读取并分析代码逻辑 3. 输出总结，附带具体文件路径作为依据 ``` **该SKILL完整运行流程** - 创建全新、完全隔离的独立子代理上下文，**无法读取主对话历史** - 子代理把整个 SKILL 正文当作自身执行指令（包含传入的参数 `$ARGUMENTS`） - `agent: Explore` 决定子代理的运行环境：配套专用模型、代码检索只读工具、对应权限 - 调研完成后，仅把精简总结结果传回主对话，中间检索过程不会污染主会话上下文 agent 字段补充规则 `agent` 用来指定使用哪一套子代理配置，可选两类： - 内置预设代理：`Explore`（代码检索）、`Plan`（方案规划）、`general-purpose`（通用） - 自定义子代理：存放于 `.claude/agents/` 目录下的自建子代理 - 不填写 agent 字段时，默认使用通用 `general-purpose` 子代理 > 适合大规模代码检索、全局逻辑梳理、跨文件溯源； > > 用 Explore 代理只会提供文件读取、检索类只读工具，不会执行修改、部署等高风险操作，安全性更高，同时上下文体积更小、更省 Token。 ### 限制 Claude 自动调用 SKILL 默认情况下，只要SKILL没写 `disable-model-invocation: true`，Claude 就能自动调用它。 - SKILL里配了 `allowed-tools`：SKILL运行时，清单内工具无需弹窗确认； - 其余工具依旧受你的全局权限管控； - 内置指令 `/init`、`/review`、`/security-review` 可通过 SKILL 工具调用；像 `/compact` 这类内置指令不行。 --- 三种管控 Claude 调用 SKILL 的方式 **方式 ①：全局禁用所有SKILL（权限黑名单）** `/permissions`: ``` # Add to deny rules: Skill ``` 作用：直接封禁整个 Skill 工具，Claude 完全无法自动调用任何SKILL。 **方式 ②：权限规则精细放行 / 拦截指定SKILL** 语法说明： - `Skill(commit)`：精准匹配SKILL名，只控制 `/commit` - `Skill(deploy *)`：前缀匹配，该SKILL带任意参数都生效示例配置： ``` # 仅允许这两个SKILL被 Claude 自动调用 Skill(commit) Skill(review-pr *) # 禁止 Claude 调用所有 deploy 相关SKILL Skill(deploy *) ``` **方式 ③：单SKILL内部禁用 Claude 调用（推荐高危操作）** 在SKILL头部加 `disable-model-invocation: true` ``` --- name: deploy disable-model-invocation: true --- ``` 效果：该SKILL直接从 Claude 的上下文列表移除，模型完全无法自动触发，**只能你手动输入命令调用**。 > 关键区分易混字段 > > - user-invocable: false > > 只控制SKILL是否在命令菜单展示，**拦不住 Claude 自动调用**，不能用来限制模型； > > - disable-model-invocation: true > > 真正阻断模型自动调用，Claude 看不到、也无法主动执行该SKILL。 ### 通过全局配置覆盖 SKILL 可见性 `skillOverrides` 是全局配置项，优先级高于 SKILL 自身 frontmatter。适合**不能修改 SKILL.md** 的场景：团队共享仓库内的SKILL、MCP 服务提供的SKILL。在命令面板输入 `/skills`，选中SKILL按空格切换状态，回车自动保存到 `.claude/settings.local.json`，不用手动写 JSON。配置键为SKILL命令名，值有 4 种模式： | 配置值 | Claude 能否看到SKILL信息 | 终端 / 命令菜单是否显示 | | ----------------------- | ------------------------- | ----------------------- | | `"on"` | 能看到名称 + 完整描述 | 展示 | | `"name-only"` | 仅能看到SKILL名称，无描述 | 展示 | | `"user-invocable-only"` | 完全隐藏（Claude 看不见） | 展示，仅你手动调用 | | `"off"` | 完全隐藏 | 隐藏 | ### v2.1.199 新增特性设为 `"off"` 后，不止终端菜单隐藏： - 远程控制客户端 - Agent SDK 调用接口都不会展示该SKILL。即便手动输入完整 `/SKILL名`，也会直接报错，不会执行SKILL。 **默认规则**：没在 `skillOverrides` 里定义的SKILL，默认等效 `"on"`。 **配置案例**： ```json { "skillOverrides": { "legacy-context": "name-only", "deploy": "off" } } ``` - `legacy-context`：Claude 只能看到SKILL名，看不到完整描述，菜单正常显示 - `deploy`：全局彻底隐藏，模型看不见、菜单不出现，手动调用直接报错 > [!warning] > > 插件SKILL**不受 `skillOverrides` 控制**，如需管理插件SKILL，使用 `/plugin` 相关命令操作。 ## SKILL 效果验证与迭代优化说明仅看到 SKILL 被触发，只能说明 Claude 识别到了这个 SKILL，**不代表它按照你的预期完成了任务**。判断 SKILL 是否合格，需要分开验证两件事： - 符合场景的提问出现时，Claude 能不能主动调用该 SKILL； - SKILL 执行后产出的内容，是否符合你的预期标准。 **标准验证方法（基线对照法）** - 准备几条贴合真实业务场景的测试提问； - 分两种环境各跑一遍： - 开启目标 SKILL 的全新会话 - 关闭该 SKILL 的全新会话 - 对比两组输出结果，判断SKILL是否起到正向作用。 > [!warning] > > 必须使用**全新空白会话**测试。如果沿用之前调试 SKILL 的旧会话，上下文里残留的SKILL信息会掩盖指令存在的缺陷，导致你误判 SKILL 没问题。 ### skill-creator 插件自动化 SKILL 评测 `skill-creator` 是官方插件，可以自动完成上面提到的「开启 / 关闭SKILL、对比输出」整套评测流程，不用手动新建会话来回测试。安装命令： ``` /plugin install skill-creator@claude-plugins-official ``` 安装插件后必须执行 `/reload-plugins` 命令，当前会话才能加载插件自带功能：重载完成后，直接让 Claude 评测SKILL，示例指令： ``` evaluate my summarize-changes skill with skill-creator ``` 插件会引导你一步步编写测试用例，并自动完成整套对照评测流程。 ### skill-creator 插件核心评测能力 - 存储测试用例会在SKILL目录自动生成 `evals/evals.json`，统一存放：测试提问、配套输入文件、预期行为判定规则。 - 隔离独立执行每条测试用例单独创建子代理运行，每次都是干净空白上下文；同时自动记录单次运行 Token 消耗、耗时。 - 自动打分判定按你写的断言规则校验输出结果，生成 `grading.json`，每条用例标注「通过 / 失败」并附上判定依据。 - 基准对照统计生成 `benchmark.json`，汇总两组数据做对比： - 开启SKILL：通过率、耗时、Token 消耗 - 关闭SKILL：通过率、耗时、Token 消耗方便你权衡：SKILL提升效果 VS 额外的性能 / Token 开销。 - SKILL版本 A/B 盲测对SKILL两个不同版本做盲对照测试，修改代码提交前，验证新版本是否确实优化了效果。 - 优化SKILL描述自动生成两类测试提问： - 理应触发该SKILL的场景 - 不该触发该SKILL的场景统计触发准确率；如果SKILL误触发、漏触发，会自动给出 `name/description` 文案修改建议。 - 可视化评审面板生成 HTML 评测报告，可逐条查看所有用例输出，手动记录主观优化意见，下一轮迭代会读取这份反馈。 ## 案例 ~~~markdown --- name: codebase-visualizer description: 生成可交互、支持折叠的代码库目录可视化图表。适用于初次浏览仓库、梳理项目架构、查找大体积文件等场景。 allowed-tools: Bash(python3 *) --- # 代码库可视化工具生成交互式 HTML 目录树，展示项目完整文件结构，文件夹支持展开与收起。 ## 使用方式在项目根目录执行可视化脚本： ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py . ``` 执行后会在当前目录生成 `codebase-map.html` 文件，并自动调用默认浏览器打开。 ## 可视化页面包含内容 - **可折叠文件夹**：点击文件夹即可展开 / 收起子目录 - **文件大小**：每个文件右侧展示占用存储空间 - **文件类型分色**：不同后缀的文件使用区分色标记 - **文件夹总占用**：展示每个目录下全部文件的合计体积 ~~~ python 代码 ```python #!/usr/bin/env python3 """Generate an interactive collapsible tree visualization of a codebase.""" import json import sys import webbrowser from html import escape from pathlib import Path from collections import Counter IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'} def scan(path: Path, stats: dict) -> dict: result = {"name": path.name, "children": [], "size": 0} try: for item in sorted(path.iterdir()): if item.name in IGNORE or item.name.startswith('.'): continue if item.is_file(): size = item.stat().st_size ext = item.suffix.lower() or '(no ext)' result["children"].append({"name": item.name, "size": size, "ext": ext}) result["size"] += size stats["files"] += 1 stats["extensions"][ext] += 1 stats["ext_sizes"][ext] += size elif item.is_dir(): stats["dirs"] += 1 child = scan(item, stats) if child["children"]: result["children"].append(child) result["size"] += child["size"] except PermissionError: pass return result def generate_html(data: dict, stats: dict, output: Path) -> None: ext_sizes = stats["ext_sizes"] total_size = sum(ext_sizes.values()) or 1 sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8] colors = { '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8', '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26', '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e', '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25', } lang_bars = "".join( f'

{ext}' f'

' f'{(size/total_size)*100:.1f}%

' for ext, size in sorted_exts ) def fmt(b): if b < 1024: return f"{b} B" if b < 1048576: return f"{b/1024:.1f} KB" return f"{b/1048576:.1f} MB" html = f''' Codebase Explorer

📁 {escape(data["name"])}

''' output.write_text(html) if __name__ == '__main__': target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve() stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()} data = scan(target, stats) out = Path('codebase-map.html') generate_html(data, stats, out) print(f'Generated {out.absolute()}') webbrowser.open(f'file://{out.absolute()}') ``` ## 常见问题 ### SKILL 无法自动触发当 Claude 没有按预期自动调用你的 SKILL 时，按下面步骤排查： - 检查 SKILL 的 `description`（描述）里包含用户日常会用到的关键词； - 执行指令 `What skills are available?`，确认该 SKILL 能被正常识别加载； - 换一种提问话术，让内容和 SKILL 描述匹配度更高； - 如果该 SKILL 允许手动调用，直接用 `/SKILL名` 手动执行测试。如果 SKILL 头部的 YAML 配置格式错误，Claude Code 只会加载SKILL正文，但元数据全部失效：此时虽然 `/SKILL` 手动调用还能用，但 Claude 失去了用于匹配触发的描述信息。执行命令时带上 `--debug` 参数，就能查看配置解析报错详情。 ### SKILL 误触发、调用过于频繁如果 Claude 在不该使用该 SKILL 时频繁自动调用它： 1. 把 SKILL 的描述（description）写得更精准、限定更严格； 2. 若只希望自己手动调用、禁止模型自动触发，在头部配置加上 `disable-model-invocation: true`。 ### SKILL 描述被截断 Claude Code 会把所有 SKILL 的名称与描述加载进上下文，让 Claude 知道当前有哪些可用 SKILL。所有 SKILL 的名称一定会完整保留；但如果你创建了大量 SKILL，系统会压缩缩短各 SKILL 的描述，以此适配 SKILL 列表的字符总限额。这会导致用于匹配触发的关键字被删掉，造成 Claude 无法识别调用该 SKILL。字符总限额规则：限额大小为模型上下文窗口的 1%。当列表总字符超出限额时，系统会**优先删除你使用频率最低的 SKILL 的描述**，高频使用的 SKILL 会完整保留全部描述文字。 - 执行 `/doctor` 命令，可以查看 SKILL 列表占用上下文的预估量，以及占用字符最多的 SKILL。 - 一旦列表超出字符限额，调试日志内会写入警告信息，带上 `--debug` 参数运行即可查看日志。在 `/context` 输出里的 Skills 行，展示的是经过限额截断后、模型实际接收的列表字符大小，数值和模型拿到的数据保持一致。 > 版本 v2.1.196 之前，这一行会统计所有 SKILL 完整描述的总字符，显示数值会远大于实际配置的限额，存在虚高问题。 **解决办法** - 提升总字符限额配置 `skillListingBudgetFraction` 参数（例：0.02 代表占上下文窗口 2%）；或配置环境变量 `SLASH_COMMAND_TOOL_CHAR_BUDGET`，直接设定一个固定字符上限。 - 释放额度给重要 SKILL 在 `skillOverrides` 中将低优先级 SKILL 设置为 `"name-only"`，这类 SKILL 仅展示名称、不再附带描述，节省字符空间。 - 从源头精简描述文本精简 `description` 和使用说明文字，并且把核心使用场景放在最前面。每条 SKILL 自身还有独立硬限制：描述 + 说明合计最多 1536 字符，该上限不受总限额影响。可通过 `skillListingMaxDescChars` 修改单条 SKILL 的字符上限。

📊 Summary

By file type

📁 {escape(data["name"])}

05-ClaudeCode-SKILL基本介绍和配置.

Dylan Kwok

05-ClaudeCode-SKILL基本介绍和配置