Claude Skills

Skills 核心知识点总览

1) Skills 是什么

Skills 是一种 基于文件系统的可复用能力，用来把某个领域的经验、流程、最佳实践打包起来，让 Claude 在合适的时候自动使用。

你可以把它理解成：
- 不是一次性提示词
- 也不是单纯的文档
- 而是一个可以被 Claude 按需加载 的“能力包”

Skills 的价值

- 专门化 Claude
- 减少重复说明
- 复用工作流
- 适合团队共享
- 把最佳实践固化到流程里

---
2) Skills 的核心机制：渐进式披露

Skills 的设计原则是 Progressive Disclosure，也就是分层加载。

三层结构

1. Metadata（元数据）
- 永远加载
- 只有 name 和 description
- 很轻量
2. Instructions（指令正文）
- 当 skill 被触发时加载
- 主要是 SKILL.md 的正文
- 这里写具体流程和指导
3. Resources（资源文件）
- 需要时才加载
- 包括模板、脚本、参考文档等
- 可以很大，但不会一开始就进上下文

这意味着什么

- 你可以安装很多 Skills
- 不会一开始就把上下文撑爆
- Claude 只在“需要的时候”深入读取

---
3) Skills 的存放位置和优先级

Skills 可以存在不同层级：

类型

- Enterprise：组织级
- Personal：个人级，通常在 ~/.claude/skills/
- Project：项目级，通常在 .claude/skills/
- Plugin：插件内技能

优先级

优先级通常是：
Enterprise > Personal > Project

插件技能用命名空间区分，避免冲突。

---
4) 自动发现机制

Claude Code 会自动发现 skills，不只看当前目录，还会看：

- 子目录里的 .claude/skills/
- 通过 --add-dir 加入的目录

这对 monorepo 很有用：不同 package 可以有自己的 skills。

---
5) Skill 的基本目录结构

一个典型 skill 目录像这样：

my-skill/
├── SKILL.md
├── templates/
├── references/
└── scripts/

说明

- SKILL.md：主入口，必须有
- templates/：输出模板
- references/：长文档、规范、知识库
- scripts/：可执行脚本

---
6) SKILL.md 的 frontmatter

Skills 通过 YAML frontmatter 描述自己。

必填字段

- name
- description

常见可选字段

- argument-hint
- disable-model-invocation
- user-invocable
- allowed-tools
- model
- effort
- context
- agent
- shell
- hooks
- paths

---
7) name 的规则

name 要满足：
- 小写字母
- 数字
- 连字符 -
- 最长 64 字符
- 不能包含 claude 或 anthropic

---
8) description 为什么最重要

description 决定 Claude 会不会自动触发这个 skill。

它应该同时写清楚：
- 这个 skill 是干什么的
- 什么时候用它
- 最好包含用户自然会说的关键词

重点

如果你想让 Claude 自动调用 skill，description 一定要写得具体、带场景、带触发词。

---
9) 控制 skill 的调用方式

有 3 种状态：

默认

- 用户可以手动调用
- Claude 也可以自动调用

disable-model-invocation: true

- 只有用户能手动调用
- Claude 不能自动触发
- 适合有副作用的操作，比如 deploy、commit

user-invocable: false

- 用户看不到这个 skill
- 但 Claude 可以自动调用
- 适合“背景知识型”skill

---
10) 技能内容的两种类型

Skills 里主要有两类内容：

Reference Content

- 提供知识
- 让 Claude 更懂某个领域
- 比如品牌语气、API 规范、代码审查原则

Task Content

- 提供步骤化工作流
- 通常是用户直接调用的命令型 skill
- 比如部署、生成文档、重构流程

---
11) 字符串替换和动态上下文

Skills 支持动态变量和上下文注入。

常见变量

- $ARGUMENTS：用户传入的全部参数
- $ARGUMENTS[N] / $N：第 N 个参数
- ${CLAUDE_SESSION_ID}：当前 session ID
- ${CLAUDE_SKILL_DIR}：skill 所在目录

动态命令注入

- !`command`

这个写法会先执行 shell 命令，再把输出塞进 skill 内容里。

用途

- 读取当前分支信息
- 获取 PR diff
- 注入实时上下文
- 让 skill 更“活”

---
12) 在 subagent 中运行 skill

可以用 context: fork 让 skill 在独立上下文里运行。

配合 agent

- Explore：适合只读探索
- Plan：适合做计划
- general-purpose：适合通用任务
- 也可以用自定义 agent

好处

- 主上下文更干净
- 适合复杂研究任务
- 适合把技能工作交给专门子代理

---
13) Supporting files：资源文件怎么组织

Skill 的正文不要写太长，详细内容放到外部文件里。

建议

- SKILL.md 保持简洁
- 大型参考材料放到 references/
- 模板放到 templates/
- 脚本放到 scripts/

原则

- SKILL.md 尽量控制在 500 行以内
- 需要时再加载其他资源

---
14) Skills 的最佳实践

1. 描述要具体

不要写：
- “帮助处理文档”

要写：
- “提取 PDF 文本、填写表单、合并文档。用于处理 PDF 文件、表单或文档提取任务。”

2. 一个 skill 做一件事

- 不要太宽泛
- 一个 skill = 一个能力

3. 描述里要包含触发词

Claude 是靠描述去匹配的，所以要写用户会说的话。

4. SKILL.md 不要太长

长内容拆出去。

5. 及时引用 supporting files

让主文件保持轻量。

---
15) 如何测试一个 skill

有两种方式：

自动触发

直接说一个匹配 description 的需求，让 Claude 自己触发。

手动调用

用 /skill-name 直接调用。

---
16) 如何更新 skill

直接编辑 SKILL.md 即可。

注意

- 更改后通常在下次 Claude Code 启动时生效
- 项目 skill 改动可以提交到 git，团队成员就能同步

---
17) 如何限制 Claude 可用的 skills

可以通过权限或 frontmatter 限制：

禁用所有 skills

在权限里禁用 Skill

限定特定 skills

可以允许或拒绝某些 skill

单个 skill 隐藏

使用：
- disable-model-invocation: true
- 或 user-invocable: false

---
18) Skills 和其他功能的区别

Skills

- 可自动或手动调用
- 适合复用能力和工作流

Slash Commands

- 原本是用户发起的快捷命令
- 现在已经并入 skills 体系

Subagents

- 负责隔离执行
- 更适合任务分派

Memory（CLAUDE.md）

- 持久项目上下文
- 适合长期规则和偏好

MCP

- 连接实时外部数据源
- 适合 API、数据库、服务

Hooks

- 事件驱动自动化
- 适合副作用和自动动作

---
19) 内置 Skills

Claude Code 自带一些内置 skills，例如：
- /simplify
- /batch
- /debug
- /loop
- /claude-api

这些不用安装，直接可用。

---
20) 常见实战模式

代码审查 skill

适合：
- 安全
- 性能
- 可维护性
- 代码质量

生成型 skill

适合：
- 博客草稿
- 文档生成
- 品牌文案

工作流 skill

适合：
- 重构
- 部署
- 代码审查
- PR 处理

---
21) 分享 Skills

团队共享

把 skill 放到项目里的 .claude/skills/，提交到 git 即可。

个人使用

复制到 ~/.claude/skills/

插件分发

把 skills 打包进插件里，便于统一安装和更新。

---
22) 安全注意事项

Skills 本质上是“可执行的能力包”，要像安装软件一样谨慎。

风险点

- 会调用工具
- 会执行脚本
- 可能访问外部 URL
- 可能引导 Claude 做危险操作

建议

- 只使用可信来源的 skills
- 仔细审查目录内的所有文件
- 特别注意 scripts 和外链内容

---
23) Troubleshooting 常见问题

Claude 不触发 skill

通常是：
- description 不够具体
- 触发词不明显
- 用户说法和描述不匹配

skill 冲突

- 命名要更具体
- trigger terms 要区分开

YAML 错误

- 检查 ---
- 检查缩进
- 不要用 tab

脚本跑不起来

- 检查权限
- 检查路径
- 确认脚本可执行

---
一句话版记忆

如果你只想记住最关键的几句：

1. Skills 是按需加载的可复用能力包。
2. description 决定 Claude 会不会自动触发 skill。
3. SKILL.md 写流程，references/ 放大资料，templates/ 放模板，scripts/ 放脚本。
4. disable-model-invocation 控制 Claude 能不能自动调用。
5. context: fork 可以把 skill 放到独立 subagent 里运行。
6. Skills 要写得具体、短小、可触发。