刚开始使用 Claude Code 的 Skill 程序时很多人会发现它与普通命令行工具完全不同：缺少直观的帮助文档、方法层级混乱、还有自动触发机制常让人手忙脚乱。老实说，下面通过清晰的结构和实战案例，一步步把这些痛点拆解。让你能快速上手并高效维护自己的 Skill。

目录

什么是 Skill？

Skill 是 Claude 用来执行特定任务的“能力说明书”。它由一个包含必需文件SKILL.md的目录组成，Claude 会将其加入工具箱并在匹配时自动加载。

⚠️ 使用者痛点：许多开发者误以为只需写一个脚这篇文章件即可；怎么说呢，必须按目录结构组织。而且文件名固定为SKILL.md.

• 自动触发：Claude 根据Description字段判断当前对话是否相关；若相关则自动加载，怎么说呢，
• 手动触发：输入/skill-name即可主动调用。

// 示例
使用者说这方面，"how does this work?"
→ Claude 检索所有 skill 的 description
→ 找到匹配项后自动加载并回答

Skill 与 Command 的区别

.claude/commands/deploy.md    // legacy .claude/skills/deploy/SKILL.md    // modern

🚧 提示：若你已有大量 legacy commands，只需保留即可；但想要利用子目录、Sub Agent 或更细粒度权限，请迁移到 skills/。

再看快速上手，创建第一个 Skill

说到步骤一。建目录 & 写 SKILL.md

⚠️ 使用者痛点： ① 创建目录方法错误导致 Claude 无法识别；② 未按小写连字符命名会被拒绝；③ frontmatter 字段缺失导致无描述、无法自加载。

mkdir-p ~/.claude/skills/explain-code

Tip：方法中不能出现空格或中文，否则会报错。 #2 写 SKILL.md 基础模板：

---# 基础信息
name: "explain-code"\
description: "Explains code with visual diagrams."\
---
## How it works
When you ask “how does this work?”,Claude will automatically load this skill based on description keyword “explains”.
### Usage
/explain-code
Example : /explain-code src/auth/login.ts

✔️ 必须以---开头。并保持 YAML 正确缩进，否则解析失败。怎么说呢，`

bash

$ claude --list-skills | grep explain-code

若未出现。请检查前述三条痛点，`

'目录结构示例'

@注意：`SKILL.md` 是唯一必需文件。其余可选，但建议添加参考文档与示例提高可维护性。话说回来，

• SKILL.md – 入口文件 & 前端说明
• reference.md – 详细技术规范，可按需引用
• examples/ └── sample.md – 演示用例 & 使用场景
• scripts/ └── helper.py – 可执行辅助脚本
• assets/ └── diagram.svg – 可视化图表

---

'存放位置与优先级'

&Td width =35 %>".claude/skills/{skillName}/"' 当前工作区、git 提交 可共享同仓库 ⏬      }'/> TD &tD wi=d20>% 插件配置

层级类型	方法示例	作用范围
公司级管理员统一配置	~/.claude/skills/{skillName}/	所有使用者共享。可覆盖个人设置
个人设置	~/.claude/skills/{skillName}/	仅当前使用者可见，可覆盖项目设置                                                                                                                                                                                                            ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​	"↑"         ↑"  ' />
"↑"'项目级配置	同一项目内同名 skill 优先级为最新提交者版本，如冲突请改名或合并逻辑。
% '<'plugin'/skills/'{skillName}''>/ '插件激活后生效'	% 插件内部作用域。仅在插件启用时有效，不会影响主应用程序！ TR> tBODy /> TBODY /> TABLE /> *优先级顺序* ： 公司> 私人> 项目> 插件。话说回来，同名 skill 高优先级覆盖低优先级。 'Monorepo 支持' "如果你的代码库采用 monorepo 结构。例如 packages/frontend/,在编辑该包下的文件时Claude 会自动探测对应包中的 .claude/skills 并激活相关技能。" 帮助团队在大型项目中保持一致性。 'Frontmatter 完整参考' yaml --- # 基础信息 ------------------------- name : my-skill # 可选，省略则使用目录名 description : 一句话描述 # 推荐看看，用于自动匹配关键词 # 调用控制 ------------------------- disable-model-invocation : true # 禁止模型自动调用，仅手动 /name 可执行 user-invocable : false # 不出现在 /menu，仅模型可调用 argument-hint : " " # 命令补全时显示提示参数 # 执行环境 ------------------------- allowed-tools : Read Grep Glob # 限制可用工具。如空格分隔列表 model : claude-opus-- # 指定模型名称 effort : low # 思考力度：low / medium / high / max context : fork # 在独立 Sub Agent 中运行，实现上下文隔离 agent : Explore # 配合 context:fork 指定 Agent 类型 # 使用范围 ------------------------- paths : "src/**/*.tsx" # 匹配 glob 时才激活，可逗号分隔多个模式 # 自定义 Shell 环境 ----------------- shell : bash # 内联 shell 命令所使用的解释器，bash 或 powershell ... **⚠️ 使用者痛点**： * 未关闭 `disable-model-invocation` 时一旦描述词匹配过于宽泛，可能导致意外执行危险操作。* `paths` 写错 glob 模式，会导致技能永远不会被激活。* `allowed-tools` 列表为空时即使你编写了复杂脚本，也无法调用任何工具。其实， '调用控制对比' =frontmatter key =能否被自己调用 =Claude 能否自动调用 =description 是否进入上下文？ 默认情况✅✅✅​​ disable-model-invocation:true​​ ✅❌❌​ user-invocable:false​​❌✅✅​ ​ ​ '控制触发方式' '只允许手动触发' yaml --- name : deploy description : Deploy application to production disable-model-invocation:true # 防止 Claude 自动触发——非常关键！--- Deploy $ARGUMENTS to production: • Run tests. • Build. • Push to target. **⚠️ 使用者痛点**： * 忘记设置 `disable-model-invocation:true` 会导致在任何包含关键词 “deploy” 的句子里都被误启动，引起灾难性部署。 '只允许 Claude 自动加载' yaml --- name : legacy-system-context description : Context about our legacy payment system architecture. user-invocable:false # 不显示在菜单——只是背景信息。--- Our legacy payment system was built in JavaScript…**⚠️ 使用者痛点**： * 若忘记 `user-invocable:false`。该背景信息会占据 `/menu` 空间，使得真正需要手动操作的命令被淹没。 '传递参数' yaml --- name : fix-issue description : Fix a GitHub issue by number. disable-model-invocation:true --- Fix GitHub issue $ARGUMENTS following our coding standards. bash $ /fix-issue A娱乐1234567 # $ARGUMENTS 被替换为 “A娱乐1234567” **⚠️ 使用者痛点**： * 当参数中含空格或特殊符号时需要使用引号包裹，否则解析错误。* 多个参数要么使用 `$ARGUMENTS` 或简写 `$N`;如果遗漏索引顺序混乱，将得到错误结果。 '进阶用法' '支持文件拆分大型 Skill' A large skill file 会导致启动延迟甚至崩溃。推荐将细节拆成单独模块，只保留入口概览，并按需引用。 perl my-api-skill/ ├── SKILL.md // 概览 + 导航指向其它文件 ├── endpoints.md // API 文档。必要时才载入 ├── examples.md // 示例代码 └── scripts/ └── validate.py // 验证脚本 // SKILL.md 内容示例： --- name:"my-api-skill" description:"API documentation helper" --- For detailed API docs see . For usage examples see . **⚠️ 使用者痛点**： * 没有正确引用外部 Markdown 文件，会导致链接失效；确保相对方法正确且大小写一致。 '动态注入上下文 ' ' yaml --- name : pr-summary description: Summarize a pull request. context : fork agent : Explore allowed-tools : Bash ## Pull request context PR diff!`gh pr diff` PR comments!`gh pr view --comments` Changed files!`gh pr diff --name-only` ## Task Summarize this pull request focusing on changes and reasons. Bash 命令是在 **技能运行前预处理** 阶段执行；Claude 本身只看到最终渲染后的 Prompt，而不是 Shell 输出。 . Error handling —— 若 Shell 返回非零状态。你可以通过 `` 捕获并返回给使用者，以避免抛错。 . Caution —— 对外部命令开启权限前请评估安全风险；最好限制在可信环境下运行，例如 CI/CD Pipeline 或受限终端。 '在 Sub Agent 中运行 ' yaml name : deep-research description : Research a topic thoroughly using codebase exploration. context : fork agent : Explore Research $ARGUMENTS thoroughly: • Find relevant files via Glob/Grep. • Read/analyze code. • Summarize findings with references. The above creates an isolated conversation thread — previous chat history is **not shared**,ensuring sensitive state stays local. If your workflow relies on global variables or prior reasoning steps。you must explicitly pass m via arguments. . This isolation also means you cannot rely on previously defined functions unless you re-import m within sub‑agent’s environment. '方法限定自动触发 ' name : react-conventions description : React component conventions for this project. paths的观点是，"src/components//.tsx","src/pages//.tsx" When writing React components in this project: • Use functional components only… If your glob pattern contains typos,it will never match. . The pattern uses npm's glob syntax — double-check case sensitivity across OSes. '开启深度思考 ' text name的观点是。architecture-review ultrathinkReview architecture of $ARGUMENTS… This keyword tells Claude to enter an extended reasoning mode that might consume more tokens and time. If your session quota is tight,consider limiting ultrathink usage only for critical reviews. . You can combine ultrathink with `effort:max`。which forces high-level planning even if model memory is low. Sage Name Description /batch …-> 大规模并行代码变更。 /debug -> 开启 debug 日志分析当前会话问题。 /loop ... -> 定时重复执行 prompt，如轮询部署状态等。 /simplify -> 启动 review Agent 并修复代码质量问题。 /claude-api -> 加载多语言 API 文档供查询。 ⚠️ 使用者痛点 新人往往把这些 bundled skills 当作“一键即用”。但大多数需要结合自己的 repo 设置才能发挥作用，例如 /batch 要事先准备好目标文件列表。按理说， 某些 bundled skills 如 /debug 会产生大量日志。如果不及时清理可能占满硬盘空间。 '常见问题 & FAQ' CQ01: "Skill 不自动触发？" 原因: description 缺乏关键词；或者因为同名更高优先级版本遮蔽了此 Skill。解决: 确认 <./list-skills> 输出正常，并尝试重命名冲突字段或升级至更低优先级层次。 CQ02: "Skill 太频繁地被激活？" 原因: description 表达过于宽泛，例如包含通用词汇“help”。解决: 精炼 description，只保留最主要关键词；若仍想保留全部功能，请把该功能拆成子命令。并通过 $ARGUMENTS. CQ03: "Description 被截断怎么办？" 原因: 超过最大字符数。解决: 把关键短句放到最前面把冗余细节压缩至后面或移至外部 Markdown 文件再引用。 CQ04: "如何迁移旧 commands 到新的 skills 格式？" 原因: 新功能需求未迁移，如子目录支持、Sub Agent 等不可用。解决: 保留旧 file，仅当需要新功能时复制一份到 .claude/skills/.../SKILL.md。并删除 commands/*.md. CQ05: "如何让同事共享我的 Skill？" 原因: 权限不足或方法不一致。解决: 把 提交到 Git 仓库，并保证每位同事都 clone 至相同相对方法下；其实，或者创建一个公共仓库专门托管技能集合。再通过安装脚本同步至各自机器上。说起来， CQ06: "为什么我的子技能没有生效？" 原因: 子技能位于不同层次但未显式指定 paths: 或 allowed-tools: 导致无法访问主环境中的资源；强行打破跨层次依赖亦可能因安全策略拒绝访问。解决: 给子技能单独定义 context:fork agent:* allowed-tools:*,并确认其拥有所需工具链与网络访问权限。其实， CQ07: Li>"我想让某个关键字只在后台静默提供给模型。却不暴露给使用者，" 强制隐藏关键字可以通过设定 并将其纳入 allowed-tools: 限制，以确保只有模型能看到而使用者看不到。 /footer