claude code接入skills

AI进阶, 第一步让AI按照自己的想法办事.

RestXtra Lv7
  2026-07-25 17:41:41 2026-07-25 17:41:41 创建   2026-07-25 18:17:35 2026-07-25 18:17:35 更新      

一、什么是 Skills？

在 Claude Code 中，Skills（技能） 是一种扩展机制，让你能够为 Claude 提供结构化的指令、流程和知识，使其在特定场景下表现得更加专业和可控。

简单来说，Skills 解决了这样的痛点：

  • 你总是把同一段说明、检查清单或多步骤流程反复粘贴到聊天中？
  • 你的 CLAUDE.md 文件里渐渐塞满了“操作步骤”而非“事实知识”？
  • 你希望 Claude 在某种情境下自动执行一套标准化流程，或按你的命令一键完成复杂任务？

——这些就是 Skills 的用武之地。

核心优势

特性 说明
按需加载 Skill 正文只在被调用时注入上下文，不影响日常对话的令牌预算
多种调用方式 可由用户直接命令触发（/skill-name），也可由 Claude 根据描述自动匹配
支持文件与脚本 可附带模板、参考文档、可执行脚本，构建复杂工具
分层管理 支持项目级、个人级、组织级（企业托管）和插件级 Skills，可覆盖
动态上下文注入 在 Skill 被读取前执行 Shell 命令，将实时数据嵌入提示中
Subagent 隔离运行 可将 Skill 放入独立子代理中执行，不影响主对话上下文
符合开放标准 遵循 Agent Skills 开放标准，兼容多 AI 工具

二、Skill 的存放位置安装与优先级

Skills 可以放在不同位置，决定其适用范围和优先级。

范围 路径 适用对象
项目 .claude/skills/<skill-name>/SKILL.md 仅当前项目
个人 ~/.claude/skills/<skill-name>/SKILL.md 所有项目
插件 <plugin>/skills/<skill-name>/SKILL.md 启用该插件的环境
企业 由托管设置指定 组织内所有用户

优先级规则：企业 > 个人 > 项目。同名的 Skill，高优先级的会覆盖低优先级的。插件 Skill 使用 plugin-name:skill-name 命名空间，不会与其它层级冲突。

嵌套目录支持：在 Monorepo 中，子包可以拥有自己的 .claude/skills/，当 Claude 编辑该子目录中的文件时，会自动发现并使用对应的 Skill。若嵌套 Skill 与根 Skill 同名，可通过限定名称（如 apps/web:deploy）显式调用。

1. 手动安装（基于文件目录）

这是最通用的方法，只需将 Skill 文件夹放到指定目录下，Claude Code 会自动发现并加载。

  • 个人全局使用（所有项目可用）：放在 ~/.claude/skills//SKILL.md
  • 单个项目使用（仅当前仓库）：放在项目根目录下的 .claude/skills//SKILL.md
  • Monorepo 子包使用：放在子目录中，如 packages/frontend/.claude/skills//SKILL.md（当编辑该子目录文件时自动激活）

注意：每个 Skill 目录下必须包含 SKILL.md 文件作为入口。

2. 通过插件市场安装（一键安装）

如果 Skill 被打包成插件发布在官方市场，可以使用命令直接安装：

  • 使用 /plugin install @ 安装插件。
  • 安装后运行 /reload-plugins 使其在当前会话中立即可用（或重启会话）。
  • 若是例如skills.sh这类型网站, 可以一键用命令进行安装
    • image
  • 示例：/plugin install skill-creator@claude-plugins-official

3. 企业/托管部署（组织范围）

如果由公司管理员配置了托管设置，Skills 会被自动推送到所有组织成员的环境中，无需个人手动操作。

三、Skill 的基本结构

一个 Skill 本质上是一个目录，其中必须包含 SKILL.md 文件，还可选包含其它支持文件。

1
2
3
4
5
6
7
my-skill/
├── SKILL.md           # 主要指令文件（必需）
├── template.md        # 模板文件
├── examples/
│   └── sample.md      # 示例输出
└── scripts/
    └── helper.py      # 可执行脚本

SKILL.md 的组成

SKILL.md 由两部分构成：

  1. YAML Frontmatter（位于 — 标记之间）：元数据配置，告诉 Claude 何时使用该 Skill、如何调用、权限等。
  2. Markdown 正文：Claude 被调用时遵循的具体指令。
1
2
3
4
5
6
7
8
---
name: my-skill
description: 简要描述该 Skill 的功能和使用场景
disable-model-invocation: false
allowed-tools: Read Grep
---

你的指令内容在这里...

四、配置 Skills：Frontmatter 字段详解

以下字段均写在 — 之间，全部可选，但强烈建议设置 description。

字段 类型 说明
name string 显示名称，默认为目录名。注意：命令名称通常由目录名决定（插件根 SKILL.md 除外）
description string 推荐。功能描述，Claude 据此判断是否自动加载该 Skill
when_to_use string 额外触发上下文，如示例请求或触发短语，追加到 description 后
argument-hint string 自动完成时显示的参数提示，如[issue-number]
arguments list/string 命名位置参数，用于$name 替换
disable-model-invocation boolean 若为true，Claude 不能自动调用该 Skill，仅用户可手动触发（/name）
user-invocable boolean 若为false，从/ 菜单中隐藏，仅 Claude 可自动调用
allowed-tools list/string Skill 激活时，Claude 无需批准即可使用的工具（如Bash(git*)）
disallowed-tools list/string Skill 激活时，从 Claude 可用工具池中移除的工具
model string 该 Skill 激活时使用的模型（覆盖会话模型）
effort string 工作量级别：low/medium/high/xhigh/max
context string 设为fork 时在分叉子代理中运行
agent string 当context: fork 时，指定子代理类型（如Explore）
hooks object 限定于该 Skill 生命周期的钩子
paths list/string Glob 模式，仅当处理匹配文件时自动激活该 Skill
shell string 指定 Shell：bash（默认）或powershell

调用控制：谁可以调用？

默认情况下，你和 Claude 都可以调用任何 Skill。通过组合以下两个字段，可以精细控制：

配置 用户可调 Claude可调 说明
默认（无设置） ✅ ✅ 描述常驻上下文，调用时加载完整内容
disable-model-invocation: true ✅ ❌ 仅用户手动触发，用于有副作用的操作（如部署）
user-invocable: false ❌ ✅ 仅 Claude 自动触发，作为背景知识（不显示在命令菜单）

五、创建你的第一个 Skill

我们以一个实际例子开始：创建一个 Skill，用于总结 Git 未提交变更并标注风险。

步骤 1：创建目录

1
mkdir -p ~/.claude/skills/summarize-changes

步骤 2：编写 SKILL.md

1
2
3
4
5
6
7
8
9
10
11
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

关键点：

  • description 让 Claude 知道何时自动加载。
  • !git diff HEAD`` 是动态上下文注入：在 Claude 看到内容之前，该命令会被执行，其输出替换占位符，因此 Claude 直接获得实时 diff 数据。
  • 或者直接使用/skills-creator命令，协助创建skills

步骤 3：测试

在任意 Git 项目中启动 claude，修改一些文件，然后：

  • 让 Claude 自动触发：问 “What did I change?” 或 “review my diff”
  • 或手动调用：/summarize-changes

Claude 会给出变更摘要和风险列表。

六、高级模式

1. 动态上下文注入

!command`` 语法允许在 Skill 加载前执行 Shell 命令，将输出作为提示的一部分。适用于获取实时数据（如 PR 信息、当前环境状态）。

markdown

1
2
3
4
5
6
7
8
---
name: pr-summary
description: Summarize changes in a pull request
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`

内联形式仅当 ! 位于行首或紧跟空白时才识别。多行命令可使用围栏代码块：

1
2
3
4
## Environment
```!
node --version
npm --version

若需禁用此行为（如出于安全策略），可设置 “disableSkillShellExecution”: true。

2. 在 Subagent 中运行（context: fork）

当 Skill 任务复杂或可能产生大量中间输出时，可以将其放到分叉的子代理中执行，避免污染主对话上下文。

1
2
3
4
5
6
7
8
9
10
11
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references
  • context: fork 让 Skill 在独立上下文中运行。
  • agent 指定子代理类型：Explore（只读探索）、Plan、general-purpose 或自定义代理。

3. 参数传递

调用 Skill 时可传递参数，通过 $ARGUMENTS、$N（位置索引）或命名参数访问。

1
2
3
4
5
6
---
name: fix-issue
arguments: [issue_number]
---

Fix GitHub issue $issue_number following our coding standards.

调用：/fix-issue 123 → $issue_number 替换为 123。

4. 支持文件与脚本

Skill 目录下可以放置额外文件，SKILL.md 中通过相对路径引用。Claude 会在需要时读取这些文件，而不会在每次调用时全部加载。

脚本可用 ${CLAUDE_SKILL_DIR} 获取 Skill 所在目录路径，确保脚本路径正确解析。

1
2
3
4
5
6
## Usage

Run the visualization script:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
1
2
3
4
5
6
7
8
9
10
11
12

脚本可以完成复杂的计算、生成视觉 HTML、调用外部 API 等，Claude 负责编排调用。

### 5. 预先批准工具（`allowed-tools`）

当 Skill 需要反复执行某些命令（如 `git` 操作），可以预先批准这些工具，避免每次询问用户。

```markdown
---
name: commit
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

6. 堆叠多个 Skills

你可以在一行中调用多个 Skills，尾部参数会传递给所有 Skill。

1
/code-review /fix-issue 123

Claude Code 会依次加载两个 Skill，并将 123 作为参数传给它们。

七、评估与迭代

如何知道你的 Skill 是否有效？从两个维度测量：

  1. 触发率：Claude 是否在期望的提示上自动调用了该 Skill？
  2. 输出质量：调用后，输出是否符合你的预期？

推荐使用官方 skill-creator 插件进行自动化评估：

bash

1
/plugin install skill-creator@claude-plugins-official

该插件支持：

  • 编写测试用例（提示、输入文件、预期行为）
  • 在隔离子代理中运行测试，记录令牌和时间
  • 生成通过/失败评分与基准报告
  • 盲 A/B 比较两个版本的 Skill
  • 描述调优建议
  • 生成 HTML 审查报告

八、故障排除

问题 可能原因 解决方案
Skill 未触发 描述不匹配用户自然语言 检查描述关键词，尝试重新表述请求
手动调用可用但自动不触发 disable-model-invocation: true 确认该字段是否应设为false
YAML 解析错误 Frontmatter 格式错误 用–debug 运行查看错误日志
Skill 列表中的描述被截断 过多 Skill 超出字符预算 在skillOverrides 中将低优先级设为"name-only"；或提高skillListingBudgetFraction
脚本路径错误 未使用${CLAUDE_SKILL_DIR} 使用该变量引用 Skill 内部文件，避免依赖当前工作目录
  • 标题: claude code接入skills
  • 作者: RestXtra
  • 创建于 : 2026-07-25 17:41:41
  • 更新于 : 2026-07-25 18:17:35
  • 链接: https://restxtra.github.io/2026/07/25/2026-07-25-claude-code接入skills/
  • 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。
目录
claude code接入skills
  1. 一、什么是 Skills？
    1. 核心优势
  2. 二、Skill 的存放位置安装与优先级
    1. 1. 手动安装（基于文件目录）
    2. 2. 通过插件市场安装（一键安装）
    3. 3. 企业/托管部署（组织范围）
  3. 三、Skill 的基本结构
    1. SKILL.md 的组成
  4. 四、配置 Skills：Frontmatter 字段详解
    1. 调用控制：谁可以调用？
  5. 五、创建你的第一个 Skill
    1. 步骤 1：创建目录
    2. 步骤 2：编写 SKILL.md
    3. 步骤 3：测试
  6. 六、高级模式
    1. 1. 动态上下文注入
    2. 2. 在 Subagent 中运行（context: fork）
    3. 3. 参数传递
    4. 4. 支持文件与脚本
    5. 6. 堆叠多个 Skills
  7. 七、评估与迭代
  8. 八、故障排除