使用技能扩展 Claude

icodebase 2026-01-28 18:46:56 AI基础 Skills 收藏

0 / 273

在 Claude Code 中创建、管理和共享技能以扩展 Claude 的功能。包括自定义斜杠命令。

技能扩展了 Claude 能做的事情。创建一个包含说明的 SKILL.md 文件，Claude 就会将其添加到其工具包中。Claude 在相关时使用技能，或者你可以使用 /skill-name 直接调用一个技能。

对于内置命令（如 /help 和 /compact），请参阅交互模式。自定义斜杠命令已合并到技能中。 .claude/commands/review.md 中的文件和 .claude/skills/review/SKILL.md 中的技能都会创建 /review 并以相同方式工作。你现有的 .claude/commands/ 文件继续工作。技能添加了可选功能：支持文件的目录、控制你或 Claude 是否调用它们的前置元数据，以及 Claude 在相关时自动加载它们的能力。

Claude Code 技能遵循Agent Skills开放标准，该标准适用于多个 AI 工具。Claude Code 使用额外功能扩展了该标准，如调用控制、子代理执行和动态上下文注入。

入门

创建你的第一个技能

此示例创建一个教 Claude 使用视觉图表和类比来解释代码的技能。由于它使用默认前置元数据，Claude 可以在你询问某事如何工作时自动加载它，或者你可以使用 /explain-code 直接调用它。

创建技能目录

在你的个人技能文件夹中为技能创建一个目录。个人技能在所有项目中都可用。

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

编写 SKILL.md

每个技能都需要一个 SKILL.md 文件，包含两部分：YAML 前置元数据（在 --- 标记之间）告诉 Claude 何时使用该技能，以及包含 Claude 在调用技能时遵循的说明的 Markdown 内容。name 字段变成 /slash-command，description 帮助 Claude 决定何时自动加载它。创建 ~/.claude/skills/explain-code/SKILL.md：

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.

测试技能

你可以通过两种方式测试它：让 Claude 自动调用它 ，通过询问与描述匹配的内容：

How does this code work?

或直接使用技能名称调用它 ：

/explain-code src/auth/login.ts

无论哪种方式，Claude 都应该在其解释中包含类比和 ASCII 图表。

技能存放位置

你存储技能的位置决定了谁可以使用它：

位置	路径	适用于
企业		你的组织中的所有用户
个人	`~/.claude/skills/<skill-name>/SKILL.md`	你的所有项目
项目	`.claude/skills/<skill-name>/SKILL.md`	仅此项目
插件	`<plugin>/skills/<skill-name>/SKILL.md`	启用插件的位置

项目技能覆盖具有相同名称的个人技能。如果你在 .claude/commands/ 中有文件，它们的工作方式相同，但技能优先于具有相同名称的命令。

从嵌套目录自动发现

当你在子目录中处理文件时，Claude Code 会自动从嵌套的 .claude/skills/ 目录中发现技能。例如，如果你在 packages/frontend/ 中编辑文件，Claude Code 也会在 packages/frontend/.claude/skills/ 中查找技能。这支持单仓库设置，其中包有自己的技能。每个技能都是一个以 SKILL.md 作为入口点的目录：

my-skill/
├── SKILL.md           # 主要说明（必需）
├── template.md        # Claude 要填写的模板
├── examples/
│   └── sample.md      # 显示预期格式的示例输出
└── scripts/
    └── validate.sh    # Claude 可以执行的脚本

SKILL.md 包含主要说明并且是必需的。其他文件是可选的，让你构建更强大的技能：Claude 要填写的模板、显示预期格式的示例输出、Claude 可以执行的脚本或详细的参考文档。从你的 SKILL.md 中引用这些文件，以便 Claude 知道它们包含什么以及何时加载它们。

.claude/commands/ 中的文件仍然有效并支持相同的前置元数据。建议使用技能，因为它们支持支持文件等其他功能。

配置技能

技能通过 SKILL.md 顶部的 YAML 前置元数据和随后的 Markdown 内容进行配置。

技能内容类型

技能文件可以包含任何说明，但思考你想如何调用它们有助于指导包含的内容：参考内容 添加 Claude 应用于你当前工作的知识。约定、模式、风格指南、领域知识。此内容内联运行，以便 Claude 可以将其与你的对话上下文一起使用。

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

任务内容 为 Claude 提供特定操作的分步说明，如部署、提交或代码生成。这些通常是你想使用 /skill-name 直接调用的操作，而不是让 Claude 决定何时运行它们。添加 disable-model-invocation: true 以防止 Claude 自动触发它。

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

你的 SKILL.md 可以包含任何内容，但思考你想如何调用技能（由你、由 Claude 或两者）以及你想在哪里运行它（内联或在子代理中）有助于指导包含的内容。对于复杂的技能，你也可以添加支持文件以保持主技能专注。

前置元数据参考

除了 Markdown 内容外，你可以使用 SKILL.md 文件顶部 --- 标记之间的 YAML 前置元数据字段来配置技能行为：

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read, Grep
---

Your skill instructions here...

所有字段都是可选的。只建议使用 description，以便 Claude 知道何时使用该技能。

字段	必需	描述
`name`	否	技能的显示名称。如果省略，使用目录名称。仅小写字母、数字和连字符（最多 64 个字符）。
`description`	推荐	技能的作用以及何时使用它。Claude 使用它来决定何时应用该技能。如果省略，使用 Markdown 内容的第一段。
`argument-hint`	否	自动完成期间显示的提示，指示预期的参数。示例：`[issue-number]` 或 `[filename] [format]`。
`disable-model-invocation`	否	设置为 `true` 以防止 Claude 自动加载此技能。用于你想使用 `/name` 手动触发的工作流。默认值：`false`。
`user-invocable`	否	设置为 `false` 以从 `/` 菜单中隐藏。用于用户不应直接调用的背景知识。默认值：`true`。
`allowed-tools`	否	此技能处于活动状态时 Claude 可以使用而无需请求权限的工具。
`model`	否	此技能处于活动状态时要使用的模型。
`context`	否	设置为 `fork` 以在分叉的子代理上下文中运行。
`agent`	否	设置 `context: fork` 时要使用的子代理类型。
`hooks`	否	限定于此技能生命周期的钩子。

可用的字符串替换

技能支持技能内容中动态值的字符串替换：

变量	描述
`$ARGUMENTS`	调用技能时传递的所有参数。如果内容中不存在 `$ARGUMENTS`，参数将作为 `ARGUMENTS: <value>` 追加。
`${CLAUDE_SESSION_ID}`	当前会话 ID。用于日志记录、创建特定于会话的文件或将技能输出与会话关联。

使用替换的示例：

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

添加支持文件

技能可以在其目录中包含多个文件。这使 SKILL.md 专注于要点，同时让 Claude 仅在需要时访问详细的参考材料。大型参考文档、API 规范或示例集合不需要在每次技能运行时加载到上下文中。

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

从 SKILL.md 中引用支持文件，以便 Claude 知道每个文件包含什么以及何时加载它：

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

保持 SKILL.md 在 500 行以下。将详细的参考材料移到单独的文件。

控制谁调用技能

默认情况下，你和 Claude 都可以调用任何没有设置 disable-model-invocation: true 的技能。你可以键入 /skill-name 直接调用它，Claude 可以在与你的对话相关时自动加载它。两个前置元数据字段让你限制这一点：* disable-model-invocation: true ：只有你可以调用该技能。用于有副作用或你想控制时间的工作流，如 /commit、/deploy 或 /send-slack-message。你不希望 Claude 因为你的代码看起来准备好了就决定部署。

user-invocable: false ：只有 Claude 可以调用该技能。用于不可作为命令操作的背景知识。legacy-system-context 技能解释了旧系统的工作原理。Claude 在相关时应该知道这一点，但 /legacy-system-context 对用户来说不是一个有意义的操作。

此示例创建一个只有你可以触发的部署技能。disable-model-invocation: true 字段防止 Claude 自动运行它：

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

以下是两个字段如何影响调用和上下文加载：

前置元数据	你可以调用	Claude 可以调用	何时加载到上下文
（默认）	是	是	描述始终在上下文中，调用时加载完整技能
`disable-model-invocation: true`	是	否	描述不在上下文中，你调用时加载完整技能
`user-invocable: false`	否	是	描述始终在上下文中，调用时加载完整技能

在常规会话中，技能描述被加载到上下文中，以便 Claude 知道什么可用，但完整的技能内容仅在调用时加载。预加载技能的子代理的工作方式不同：完整的技能内容在启动时注入。

限制工具访问

使用 allowed-tools 字段来限制技能处于活动状态时 Claude 可以使用哪些工具。此技能创建一个只读模式，其中 Claude 可以浏览文件但不能修改它们：

---
name: safe-reader
description: Read files without making changes
allowed-tools: Read, Grep, Glob
---

将参数传递给技能

你和 Claude 都可以在调用技能时传递参数。参数可通过 $ARGUMENTS 占位符获得。此技能通过编号修复 GitHub 问题。$ARGUMENTS 占位符被替换为技能名称后面的任何内容：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

当你运行 /fix-issue 123 时，Claude 收到”按照我们的编码标准修复 GitHub 问题 123…”如果你使用参数调用技能但技能不包含 $ARGUMENTS，Claude Code 会将 ARGUMENTS: <your input> 追加到技能内容的末尾，以便 Claude 仍然看到你键入的内容。

高级模式

注入动态上下文

!command “ 语法在技能内容发送给 Claude 之前运行 shell 命令。命令输出替换占位符，所以 Claude 接收实际数据，而不是命令本身。此技能通过使用 GitHub CLI 获取实时 PR 数据来总结拉取请求。 !gh pr diff “ 和其他命令首先运行，它们的输出被插入到提示中：

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

当此技能运行时：1. 每个 !command` “ 立即执行（在 Claude 看到任何内容之前）

输出替换技能内容中的占位符
Claude 接收具有实际 PR 数据的完全呈现的提示

这是预处理，不是 Claude 执行的东西。Claude 只看到最终结果。

要在技能中启用扩展思考，在你的技能内容中的任何地方包含单词”ultrathink”。

在子代理中运行技能

当你想让技能在隔离中运行时，在前置元数据中添加 context: fork。技能内容成为驱动子代理的提示。它将无法访问你的对话历史。

context: fork 仅对具有明确说明的技能有意义。如果你的技能包含”使用这些 API 约定”之类的指南而没有任务，子代理会收到指南但没有可操作的提示，并返回而不产生有意义的输出。

技能和子代理在两个方向上协同工作：

方法	系统提示	任务	也加载
带有 `context: fork` 的技能	来自代理类型（`Explore`、`Plan` 等）	SKILL.md 内容	CLAUDE.md
带有 `skills` 字段的子代理	子代理的 Markdown 正文	Claude 的委派消息	预加载的技能 + CLAUDE.md

使用 context: fork，你在技能中编写任务并选择代理类型来执行它。对于反向操作（定义使用技能作为参考材料的自定义子代理），请参阅子代理。

示例：使用 Explore 代理的研究技能

此技能在分叉的 Explore 代理中运行研究。技能内容成为任务，代理提供针对代码库探索优化的只读工具：

---
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

当此技能运行时：1. 创建一个新的隔离上下文

子代理接收技能内容作为其提示（“彻底研究 $ARGUMENTS…”）
agent 字段确定执行环境（模型、工具和权限）
结果被总结并返回到你的主对话

agent 字段指定要使用的子代理配置。选项包括内置代理（Explore、Plan、general-purpose）或来自 .claude/agents/ 的任何自定义子代理。如果省略，使用 general-purpose。

限制 Claude 的技能访问

默认情况下，Claude 可以调用任何没有设置 disable-model-invocation: true 的技能。内置命令如 /compact 和 /init 不能通过技能工具获得。控制 Claude 可以调用哪些技能的三种方法：通过在 /permissions 中拒绝技能工具来禁用所有技能 ：

# Add to deny rules:
Skill

使用权限规则允许或拒绝特定技能 ：

# Allow only specific skills
Skill(commit)
Skill(review-pr:*)

# Deny specific skills
Skill(deploy:*)

权限语法：Skill(name) 用于精确匹配，Skill(name:*) 用于带有任何参数的前缀匹配。通过在其前置元数据中添加 disable-model-invocation: true 来隐藏单个技能 。这会从 Claude 的上下文中完全删除该技能。

user-invocable 字段仅控制菜单可见性，不控制技能工具访问。使用 disable-model-invocation: true 来阻止程序化调用。

共享技能

技能可以根据你的受众在不同范围内分发：* 项目技能 ：将 .claude/skills/ 提交到版本控制

插件：在你的插件中创建 skills/ 目录
托管：通过托管设置部署组织范围内

生成视觉输出

技能可以捆绑并运行任何语言的脚本，给 Claude 超越单个提示中可能的功能。一个强大的模式是生成视觉输出：在浏览器中打开的交互式 HTML 文件，用于探索数据、调试或创建报告。此示例创建一个代码库浏览器：一个交互式树视图，你可以在其中展开和折叠目录、一目了然地查看文件大小，并按颜色识别文件类型。创建技能目录：

mkdir -p ~/.claude/skills/codebase-visualizer/scripts

创建 ~/.claude/skills/codebase-visualizer/SKILL.md。描述告诉 Claude 何时激活此技能，说明告诉 Claude 运行捆绑的脚本：

name: codebase-visualizer
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
allowed-tools: Bash(python:*)
-----------------------------

# Codebase Visualizer

Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

## Usage

Run the visualization script from your project root:

python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

This creates `codebase-map.html` in the current directory and opens it in your default browser.

## What the visualization shows

- **Collapsible directories**: Click folders to expand/collapse
- **File sizes**: Displayed next to each file
- **Colors**: Different colors for different file types
- **Directory totals**: Shows aggregate size of each folder

创建 ~/.claude/skills/codebase-visualizer/scripts/visualize.py。此脚本扫描目录树并生成一个自包含的 HTML 文件，具有：* 一个摘要侧边栏 ，显示文件计数、目录计数、总大小和文件类型数量

一个条形图 ，按文件类型（按大小排名前 8）分解代码库
一个可折叠树 ，你可以在其中展开和折叠目录，带有颜色编码的文件类型指示器

该脚本需要 Python，但仅使用内置库，因此无需安装包：

#!/usr/bin/env python3
"""Generate an interactive collapsible tree visualization of a codebase."""

import json
import sys
import webbrowser
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"""
📊 Summary
Files{stats["files"]:,}
Directories{stats["dirs"]:,}
Total size{fmt(data["size"])}
File types{len(stats["extensions"])}
By file type
{lang_bars}

📁 {data["name"]}

const data = {json.dumps(data)};
const colors = {json.dumps(colors)};
function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}
function render(node, parent) {{
if (node.children) {{
const det = document.createElement('details');
det.open = parent === document.getElementById('root');
det.innerHTML = `📁 ${{node.name}}${{fmt(node.size)}}`;
const ul = document.createElement('ul'); ul.className = 'tree';
node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));
node.children.forEach(c => render(c, ul));
det.appendChild(ul);
const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);
}} else {{
const li = document.createElement('li'); li.className = 'file';
li.innerHTML = `${{node.name}}${{fmt(node.size)}}`;
parent.appendChild(li);
}}
}}"""
data.children.forEach(c => render(c, document.getElementById('root')));

"""
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()}')

要测试，在任何项目中打开 Claude Code 并询问”可视化此代码库。“Claude 运行脚本，生成 codebase-map.html，并在浏览器中打开它。此模式适用于任何视觉输出：依赖关系图、测试覆盖率报告、API 文档或数据库架构可视化。捆绑的脚本完成繁重工作，而 Claude 处理编排。

故障排除

技能未触发

如果 Claude 在预期时不使用你的技能：1. 检查描述是否包含用户会自然说的关键字

验证技能是否出现在”有哪些技能可用？“中
尝试重新表述你的请求以更接近描述
如果技能是用户可调用的，使用 /skill-name 直接调用它

技能触发过于频繁

如果 Claude 在你不想要的时候使用你的技能：1. 使描述更具体

如果你只想手动调用，添加 disable-model-invocation: true

Claude 看不到我的所有技能

技能描述被加载到上下文中，以便 Claude 知道什么可用。如果你有很多技能，它们可能会超过字符预算（默认 15,000 个字符）。运行 /context 以检查有关排除的技能的警告。要增加限制，设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量。

阅读全文