这篇文章介绍了Claude Code 使用指南，分享给大家做个参考，收藏极客资料网收获更多编程知识

2026-02-28

Claude Code

https://github.com/anthropics/claude-code
https://code.claude.com/docs/en/overview

What is Claude Code ?

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows -- all through natural language commands. Use it in your terminal, IDE

**

Claude Code 如何工作

https://code.claude.com/docs/zh-CN/how-claude-code-works

Claude 可以做什么

工具是使 Claude Code 成为 Agent 的原因。没有工具，Claude 只能用文本回应。有了工具，Claude 可以采取行动：读取您的代码、编辑文件、运行命令、搜索网络并与外部服务交互。每个工具使用都会返回信息，反馈到循环中，告知 Claude 的下一个决定。内置工具通常分为四类，每一类代表不同类型的代理能力。

类别	Claude 可以做什么
文件操作	读取文件、编辑代码、创建新文件、重命名和重新组织
搜索	按模式查找文件、使用正则表达式搜索内容、探索代码库
执行	运行 shell 命令、启动服务器、运行测试、使用 git
网络	搜索网络、获取文档、查找错误消息
代码智能	编辑后查看类型错误和警告、跳转到定义、查找引用（需要代码智能插件）

**简而言之: 你跟大语言模型对话, 只管提出需求, 模型直接帮你生成代码, 项目文件和文件结构, 也可以执行终端命令. 例如: npm install xxx 安装依赖, gradle build 构建项目等等, 也就是说它最终的目的是希望仅使用自然语言描述需求, 就可以帮你构建应用

Claude Code 可以访问什么

• 您的项目。 您目录和子目录中的文件，以及其他地方有您许可的文件。
• 您的终端。 您可以运行的任何命令：构建工具、git、包管理器、系统实用程序、脚本。如果您可以从命令行做到，Claude 也可以。
• 您的 git 状态。 当前分支、未提交的更改和最近的提交历史。
• 您的 CLAUDE.md。 一个 markdown 文件，您可以在其中存储项目特定的说明、约定和 Claude 应该在每个会话中了解的上下文。
• 您配置的扩展。 用于外部服务的 MCP servers、用于工作流的 skills、用于委派工作的 subagents 和用于浏览器交互的 Claude in Chrome。

安装(for windowns)

https://code.claude.com/docs/zh-CN/overview
https://code.claude.com/docs/zh-CN/jetbrains

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

本地执行会报错, 估计是GWF的问题.. 懒得搞了, 可以参考 https://docs.bigmodel.cn/cn/coding-plan/tool/claude#%E6%AD%A5%E9%AA%A4%E4%B8%80%EF%BC%9A%E5%AE%89%E8%A3%85-claude-code 进行安装

0. 前提条件：

• 需要安装 Node.js 18 或更新版本环境
• MacOS 用户请使用 nvm 方式安装 Nodejs，若直接安装包安装后续会遇到权限问题
• Windows 用户还需安装 Git for Windows

1. 进入命令行界面，安装 Claude Code

npm install -g @anthropic-ai/claude-code

2. 运行如下命令，查看安装结果，若显示版本号则表示安装成功

claude --version

3. 连接IDE
   在任何外部终端中使用 /ide 命令将 Claude Code 连接到您的 JetBrains IDE 并激活所有功能：

/ide

如果您希望 Claude 能够访问与 IDE 相同的文件，请从与 IDE 项目根目录相同的目录启动 Claude Code。

for JetBrains IDEs

• 快速启动：使用 Cmd+Esc（Mac）或 Ctrl+Esc（Windows/Linux）直接从编辑器打开 Claude Code，或点击 UI 中的 Claude Code 按钮

三种核心工作模式

Claude Code 是 Anthropic 推出的终端级 AI 编程助手，它主要提供三种核心工作模式，用户可以通过快捷键 Shift + Tab (有时候是 Alt+M)在这三种模式之间循环切换。
这三种模式分别是：

1. 默认模式 (Default / Edit Mode)

当 Claude 建议修改文件、执行命令或进行其他操作时，必须先征询用户的同意。用户需要确认（Approve）后，操作才会执行。

2. 自动模式 (Auto / Auto-accept Mode)

Claude 会自动执行它认为必要的文件修改和命令，不需要每次操作都等待用户授权。

3. 规划模式 (Plan / Scale Mode)

只动口不动手，专注于策略, 可理解为把先写代码变成先达成共识

Claude 只讨论思路和生成计划，不会真正修改任何文件或执行终端命令。它会输出一个详细的步骤列表或架构方案供用户参考。

另外按下 Ctrl + G 可以使用外部编辑器 编辑提示词

权限工具

工具类型	示例	需要批准	”是，不再询问”行为
只读	文件读取、Grep	否	不适用
Bash 命令	Shell 执行	是	每个项目目录和命令永久有效
文件修改	Edit/Write 文件	是	直到会话结束

管理权限

https://code.claude.com/docs/zh-CN/permissions

您可以使用 /permissions 查看和管理 Claude Code 的工具权限。此 UI 列出所有权限规则和它们来自的 settings.json 文件。

• Allow 规则让 Claude Code 使用指定的工具而无需手动批准。
• Ask 规则在 Claude Code 尝试使用指定工具时提示确认。
• Deny 规则防止 Claude Code 使用指定的工具。

命令

命令前缀

主要有三类前缀触发器：

符号	类型	本质作用
/	Command（命令）	执行内置操作
@	Context（上下文）	引用文件/代码/目录
!	Bash 模式	直接执行终端命令
无前缀	自然语言	普通任务指令

常用命令

命令	作用
/help	查看全部能力
/resume	选择之前的会话
/rewin	回退会话和代码
/clear	清空对话
/export	导出对话
/context	查看上下文使用情况
/status	环境状态
/tasks	管理后台任务
/memory	编辑 CLAUDE.md
/model	切换模型
/mcp	查看MCP

# MCP
# 在 Claude Code 中检查服务器状态
/mcp
# 列出所有已配置的服务器
claude mcp list
# 查看特定服务器的详细信息
claude mcp get github
# 删除服务器
claude mcp remove github

#了解当前会话的TOKEN消耗情况
/cost

# 会话管理 回滚
/rewind 

# 管理记忆 (管理CLAUDE.md)
/memory 

会话分支 fork-session

--fork-session 的作用是在恢复会话时创建一个新的会话 ID，而不是重用原始会话。这意味着原始会话保持不变，新的对话会在一个独立的分支中进行。

# 分支  探索缓存方案
claude --resume perf-analysis --fork-session

# 分支 探索重构方案
claude --resume perf-analysis --fork-session

类似 Git 的分支概念

常用快捷键

快捷键	描述	上下文
Ctrl+C	取消当前输入或生成	标准中断
Ctrl+D	退出 Claude Code 会话	EOF 信号
Ctrl+G	在默认文本编辑器中打开	在默认文本编辑器中编辑您的提示或自定义响应
Ctrl+L	清除终端屏幕	保留对话历史
Ctrl+O	切换详细输出	显示详细的工具使用和执行情况
Ctrl+R	反向搜索命令历史	交互式搜索以前的命令
Ctrl+V 或 Cmd+V（iTerm2）或 Alt+V（Windows）	从剪贴板粘贴图像	粘贴图像或图像文件的路径
Ctrl+B	后台运行任务	后台运行 bash 命令和代理。Tmux 用户按两次
Left/Right arrows	在对话框选项卡之间循环	在权限对话框和菜单中的选项卡之间导航
Up/Down arrows	导航命令历史	回忆以前的输入
Esc + Esc	回退代码/对话	将代码和/或对话恢复到之前的状态
Shift+Tab 有时候是Alt+M	切换权限模式	在自动接受模式、Plan Mode 和正常模式之间切换
Option+P（macOS）或 Alt+P（Windows/Linux）	切换模型	在不清除提示的情况下切换模型
Option+T（macOS）或 Alt+T（Windows/Linux）	切换扩展思考	启用或禁用扩展思考模式。首先运行 /terminal-setup 以启用此快捷键

配置

https://code.claude.com/docs/en/settings

配置文件

Scope	Location	Who it affects	Shared with team?
Managed	Server-managed settings, plist / registry, or system-level managed-settings.json	All users on the machine	Yes (deployed by IT)
User	~/.claude/ directory	You, across all projects	No
Project	.claude/ in repository	All collaborators on this repository	Yes (committed to git)
Local	.claude/*.local.* files	You, in this repository only	No (gitignored)

配置模型

https://code.claude.com/docs/en/model-config

Learn about the Claude Code model configuration, including model aliases like opusplan

智谱模型

https://docs.bigmodel.cn/cn/coding-plan/tool/claude

调整配置文件的方来调整到其他模型

# 编辑或新增 `settings.json` 文件
# MacOS & Linux 为 `~/.claude/settings.json`
# Windows 为`用户目录/.claude/settings.json`
# 新增或修改里面的 env 字段
# 注意替换里面的 `your_zhipu_api_key` 为您上一步获取到的 API Key
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_zhipu_api_key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1
  }
}
# 再编辑或新增 `.claude.json` 文件
# MacOS & Linux 为 `~/.claude.json`
# Windows 为`用户目录/.claude.json`
# 新增 `hasCompletedOnboarding` 参数
{
  "hasCompletedOnboarding": true
}

在成功配置套餐后，默认为服务端模型映射，即您界面上看到的是 Claude 模型但实际是 GLM 模型。
Claude Code 内部模型环境变量与 GLM 模型对应关系，默认配置如下：

• ANTHROPIC_DEFAULT_OPUS_MODEL：GLM-4.7
• ANTHROPIC_DEFAULT_SONNET_MODEL：GLM-4.7
• ANTHROPIC_DEFAULT_HAIKU_MODEL：GLM-4.5-Air

使用 GLM-5，需要在配置文件 ~/.claude/settings.json 中，添加或替换如下环境变量参数：

{
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5"
  }
}

核心功能

Hooks

https://code.claude.com/docs/zh-CN/hooks#%E9%A1%B9%E7%9B%AE%E7%89%B9%E5%AE%9A%E7%9A%84-hook-%E8%84%9A%E6%9C%AC

Claude Code 提供了在不同时机插入你的 Hooks：

• PreToolUse：在工具调用之前运行（可以根据需要阻止工具的调用）
• PermissionRequest：在显示权限对话框时运行（可以允许或拒绝）
• PostToolUse：在工具调用完成后运行
• UserPromptSubmit：当用户提交提示时运行，在 Claude 处理之前
• Notification：当 Claude Code 发送通知时运行
• Stop：当 Claude Code 完成响应时运行
• SubagentStop：当子代理任务完成时运行
• PreCompact：在 Claude Code 即将运行压缩操作之前运行
• SessionStart：当 Claude Code 启动新会话或恢复现有会话时运行
• SessionEnd：当 Claude Code 会话结束时运行

in short: 在Claude Code 处理你的项目流程中, 比如 生成代码文件前后, 调用工具需前后等等, 插入逻辑, 侵入你的扩展需求

Skills

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

SKILLS 集合库- https://github.com/anthropics/skills/tree/main/skills

Skills example

1. 创建 skill 目录

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

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

存储 skill 的位置决定了谁可以使用它：

位置	路径	适用于
个人	~/.claude/skills/<skill-name>/SKILL.md	你的所有项目
项目	.claude/skills/<skill-name>/SKILL.md	仅此项目
Plugin	<plugin>/skills/<skill-name>/SKILL.md	启用 plugin 的位置

2. 编写 SKILL.md
   https://code.claude.com/docs/zh-CN/skills#

每个 skill 都需要一个 SKILL.md 文件，
包含两部分：

1. YAML frontmatter（在 --- 标记之间）告诉 Claude 何时使用该 skill
2. 包含 Claude 在调用 skill 时遵循的说明的 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.

3. 测试 skill
   https://code.claude.com/docs/zh-CN/skills#

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

How does this code work?

或直接使用 skill 名称调用它：

/explain-code src/auth/login.ts

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

Sub Agent

Sub Agent 适合 适合与主上下文关联很小, 但影响大的任务需求

• 保留上下文，通过将探索和实现保持在主对话之外
• 强制执行约束，通过限制 subagent 可以使用的工具
• 跨项目重用配置，使用用户级 subagents
• 专门化行为，为特定领域使用专注的系统提示
• 控制成本，通过将任务路由到更快、更便宜的模型（如 Haiku）

https://code.claude.com/docs/zh-CN/sub-agents#快速入门：创建您的第一个-subagent

创建

1. /agents 命令提供了一个交互式界面来管理 subagents。运行 /agents 来：

• 查看所有可用的 subagents（内置、用户、项目和插件）
• 使用引导式设置或 Claude 生成创建新 subagents
• 编辑现有 subagent 配置和工具访问
• 删除自定义 subagents
• 查看当存在重复项时哪些 subagents 处于活动状态

subagent 说明

.claude/agents/<name-of-agent>.md文件

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Frontmatter 定义 subagent 的元数据和配置。正文成为指导 subagent 行为的系统提示。Subagents 仅接收此系统提示（加上基本环境详细信息，如工作目录），而不是完整的 Claude Code 系统提示。

subagent 的 memory

Scope	Location	何时使用
user	~/.claude/agent-memory/<name-of-agent>/	subagent 应该在所有项目中记住学习
project	.claude/agent-memory/<name-of-agent>/	subagent 的知识是特定于项目的并可通过版本控制共享
local	.claude/agent-memory-local/<name-of-agent>/	subagent 的知识是特定于项目的但不应检入版本控制

内置的 subagent

Explore

一个快速的、只读的代理，针对搜索和分析代码库进行了优化。

• 模型：Haiku（快速、低延迟）
• 工具：只读工具（拒绝访问 Write 和 Edit 工具）
• 目的：文件发现、代码搜索、代码库探索

当 Claude 需要搜索或理解代码库而不进行更改时，它会委托给 Explore。这使探索结果保持在主对话上下文之外。调用 Explore 时，Claude 指定一个彻底程度级别：quick 用于有针对性的查找，medium 用于平衡的探索，或 very thorough 用于全面分析。

plan

在 plan mode 期间用于在呈现计划之前收集上下文的研究代理。

• 模型：从主对话继承
• 工具：只读工具（拒绝访问 Write 和 Edit 工具）
• 目的：用于规划的代码库研究

当您处于 plan mode 且 Claude 需要理解您的代码库时，它会将研究委托给 Plan subagent。这防止了无限嵌套（subagents 无法生成其他 subagents），同时仍然收集必要的上下文。

General-purpose

一个能够处理需要探索和操作的复杂多步骤任务的代理。

• 模型：从主对话继承
• 工具：所有工具
• 目的：复杂研究、多步骤操作、代码修改

当任务需要探索和修改、复杂推理来解释结果或多个依赖步骤时，Claude 会委托给 general-purpose。

Sub Agent 和 Agent Teams

Agent teams 让你协调多个 Claude Code 实例一起工作。一个会话充当团队负责人，协调工作、分配任务和综合结果。队友独立工作，每个都在自己的 context window 中，并直接相互通信。

Agent teams 和 subagents 都让你并行化工作，但它们的运作方式不同。根据你的工作人员是否需要相互通信来选择：

Subagents 只向主代理报告结果，彼此不交谈。在 agent teams 中，队友共享任务列表、认领工作并直接相互通信。

	Subagents	Agent teams
Context	自己的 context window；结果返回给调用者	自己的 context window；完全独立
通信	仅向主代理报告结果	队友直接相互发送消息
协调	主代理管理所有工作	共享任务列表，自我协调
最适合	只有结果重要的专注任务	需要讨论和协作的复杂工作
token成本	较低：结果汇总回主 context	较高：每个队友是一个独立的 Claude 实例

内置的工具

https://code.claude.com/docs/zh-CN/settings
Claude Code 可以访问一组强大的工具，帮助它理解和修改您的代码库：

工具	描述	需要权限
Agent	生成一个 subagent，具有自己的上下文窗口来处理任务	否
AskUserQuestion	提出多选问题以收集需求或澄清歧义	否
Bash	在您的环境中执行 shell 命令。请参阅 Bash 工具行为	是
CronCreate	在当前会话中计划重复或一次性提示（Claude 退出时消失）。请参阅计划任务	否
CronDelete	按 ID 取消计划任务	否
CronList	列出会话中的所有计划任务	否
Edit	对特定文件进行有针对性的编辑	是
EnterPlanMode	切换到计划模式以在编码前设计方法	否
EnterWorktree	创建一个隔离的 git worktree 并切换到它	否
ExitPlanMode	提出计划以供批准并退出计划模式	是
ExitWorktree	退出 worktree 会话并返回到原始目录	否
Glob	基于模式匹配查找文件	否
Grep	在文件内容中搜索模式	否
ListMcpResourcesTool	列出连接的 MCP servers 公开的资源	否
LSP	通过语言服务器的代码智能。在文件编辑后自动报告类型错误和警告。还支持导航操作：跳转到定义、查找引用、获取类型信息、列出符号、查找实现、跟踪调用层次结构。需要 code intelligence plugin 及其语言服务器二进制文件	否
NotebookEdit	修改 Jupyter notebook 单元格	是
Read	读取文件的内容	否
ReadMcpResourceTool	按 URI 读取特定 MCP 资源	否
Skill	在主对话中执行 skill	是
TaskCreate	在任务列表中创建新任务	否
TaskGet	检索特定任务的完整详情	否
TaskList	列出所有任务及其当前状态	否
TaskOutput	从后台任务检索输出	否
TaskStop	按 ID 杀死运行中的后台任务	否
TaskUpdate	更新任务状态、依赖项、详情或删除任务	否
TodoWrite	管理会话任务清单。在非交互模式和 Agent SDK 中可用；交互式会话改用 TaskCreate、TaskGet、TaskList 和 TaskUpdate	否
ToolSearch	当启用 tool search 时搜索和加载延迟工具	否
WebFetch	从指定的 URL 获取内容	是
WebSearch	执行网络搜索	是
Write	创建或覆盖文件	是

权限规则可以使用 /allowed-tools 或在权限设置中配置。另请参阅工具特定权限规则。

MCP

• 项目级：在项目根目录创建 .mcp.json
• 全局配置：修改 ~/.claude.json

对于远程 HTTP MCP 服务，可以使用以下命令：

# 基础添加命令
claude mcp add --transport http <name> <url>

# 示例：连接到本地 HTTP MCP 服务器
claude mcp add --transport http my-server http://localhost:8080/mcp

# 需要认证时使用 --header 参数
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

配置 Figma MCP

https://developers.figma.com/docs/figma-mcp-server/add-custom-rules/#rules-to-ensure-consistently-good-output
开源版 Figma-Context-MCP：https://github.com/GLips/Figma-Context-MCP

** 1：全局安装依赖**

npm install -g figma-developer-mcp

2：创建配置文件

在项目根目录创建 .mcp.json 文件（或修改 ~/.claude.json 以实现全局配置），添加以下内容：

{
  "mcpServers": {
    "figma-developer-mcp": {
      "command": "figma-developer-mcp",
      "args": [
        "--stdio"
      ],
      "env": {
        "FIGMA_API_KEY": "[YOUR_FIGMA_API_KEY]"
      }
    }
  }
}

配置说明：

• figma-developer-mcp：自定义别名，避免与官方 MCP 冲突
• FIGMA_API_KEY：需要在 Figma 中生成个人访问令牌

开源 MCP 提供 2 个核心工具：

1. 获取 Figma 图片：提取设计稿的视觉内容
2. 获取 Figma 数据：提取设计稿的结构数据

好恶心, 若是免费的账号 figma 一个月只能调个5次

插件

即是将 Hook、Skills 、Sub Agent、MCP 打包在一起的集合

https://code.claude.com/docs/zh-CN/plugins

如何编写 Agent Skills

https://agentskills.io/what-are-skills

Agent Skills 是一个由 Anthropic 牵头维护的 开放标准，用于教导 AI 如何处理特定任务或工作流程。

它是根据你的特定需求定制 AI 的最强大方式之一。当你需要执行可重复的工作流程时，你无需在每次和 AI 的对话中重复解释自己的偏好、流程和领域知识，Skills 让你只需教导 AI 一次，便能每次都从中受益。

Skill 能与 AI 的内置能力（如代码执行和文档创建）协同良好。对于构建和使用 MCP 的用户，它还提供了另一个强大层级的功能——帮助 AI 将外部工具访问转化为可靠、优化的工作流程。

该标准目前已得到 Anthropic/OpenAI/Google/Microsoft/Cursor 等多家行业领军公司的支持，迅速成为各大主流 AI 工具的标配。

根据标准定义，每个 Skill 都是一个规范化命名的文件夹，其中包含了 Markdown 文档、可执行脚本和其他类型的素材文件。

Claude Skills 完整构建指南

https://github.com/libukai/awesome-agent-skills/blob/main/assets/docs/Claude-Skills-%E5%AE%8C%E5%85%A8%E6%9E%84%E5%BB%BA%E6%8C%87%E5%8D%97.md

Skill 是一组指令——打包成一个简单的文件夹——用于教导 Claude 如何处理特定任务或工作流程。Skills 是根据你的特定需求定制 Claude 最强大的方式之一。你无需在每次对话中重复解释自己的偏好、流程和领域知识，Skills 让你只需教导 Claude 一次，便能每次受益。

Skills 在你拥有可重复工作流程时效果最佳：从规范中生成前端设计、使用一致方法论进行研究、按照团队风格指南创建文档，或编排多步骤流程。它们与 Claude 的内置能力（如代码执行和文档创建）协同良好。对于构建 MCP 集成的用户，Skills 提供了另一个强大层级——帮助将原始工具访问转化为可靠、优化的工作流程。

本指南涵盖构建高效 Skills 所需了解的一切内容——从规划与结构到测试与分发。无论你是为自己、团队还是社区构建 Skill，你都将在全文中找到实用模式和真实案例。

文件结构

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

Skill 是一个包含以下内容的文件夹：

• SKILL.md（必须）：带有 YAML frontmatter 的 Markdown 格式指令
• scripts/（可选）：可执行代码（Python、Bash 等）
• references/（可选）：按需加载的文档
• assets/（可选）：输出中使用的模板、字体、图标

关键规则

• SKILL.md 命名：
  必须完全命名为 SKILL.md（区分大小写）
  不接受任何变体（SKILL.MD、skill.md 等）
  Skill 文件夹命名：

• 使用 kebab-case：notion-project-setup ✅
  不使用空格：Notion Project Setup ❌
  不使用下划线：notion_project_setup ❌
  不使用大写：NotionProjectSetup ❌

元数据格式

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

Your skill instructions here...

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

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

变量模板

变量	描述
$ARGUMENTS	调用 skill 时传递的所有参数。如果内容中不存在 $ARGUMENTS，参数将作为 ARGUMENTS: <value> 追加。
$ARGUMENTS[N]	按 0 基索引访问特定参数，如 $ARGUMENTS[0] 表示第一个参数。
$N	$ARGUMENTS[N] 的简写，如 $0 表示第一个参数或 $1 表示第二个参数。
${CLAUDE_SESSION_ID}	当前会话 ID。用于日志记录、创建特定于会话的文件或将 skill 输出与会话关联。

嵌套的结构

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

从 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 行。将详细的参考资料移到单独的文件中。

加载原理

1. Level 1: 元数据，始终加载
   SKILL.md 文档内的元数据，包含名称与用途描述。长度约 100 tokens。
   Agent 启动时，就在 Context Window 中加载 Skill 元数据，将其包含在系统提示中。

2. Level 2: SKILL.md 文档内的正文内容，也就是主要技能指令，一般包含工作流程、最佳实践和指导。
   建议少于 5000 tokens。
   当用户发出的消息与Skill 元数据的描述匹配，需要调用 Skill 时，Agent 才会用 bash 读取文档正文 。读取时文档内容加载到 Context Window 中。

3. Level 3: 子技能指令 / 资源 / 代码，按需动态加载

• Sub-SKILL.md 子技能文档：相对独立、复杂的子技能指令，单独放在 Level3 拆分加载
• Scripts 代码脚本：视作“Agent 的可执行资源”，而不算 tool use（tool use 是 Agent 外部调用的独立服务）
  Agent 在 Agent 电脑（虚拟机）中直接调用脚本，脚本代码本身不进 Context Window，只有脚本运行完成后的输出会进 Agent 的 Context。
• Reference 参考文档、Assets 可用资源，当然都是 Level 3，仅在必需时动态读取加载。

![[Pasted image 20260313193935.png]]

File references

When referencing other files in your skill, use relative paths from the skill root:
SKILL.md

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

文件引用是从根目录开始

Progressive disclosure

Skills should be structured for efficient use of context:

1. Metadata (~100 tokens): The name and description fields are loaded at startup for all skills
2. Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
3. Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required

Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files

什么是好的 Skills?

根据 Anthropic 工程博客的说法："这些元数据……提供恰到好处的信息，让 Claude 知道何时应使用每个 Skill，而无需将全部内容加载到上下文中。"这是递进式披露的第一级。

结构：

[它做什么] + [何时使用] + [核心能力]

良好 description 的示例：

# 好——具体且可执行
description: Analyzes Figma design files and generates
developer handoff documentation. Use when user uploads .fig
files, asks for "design specs", "component documentation", or
"design-to-code handoff".

# 好——包含触发短语
description: Manages Linear project workflows including sprint
planning, task creation, and status tracking. Use when user
mentions "sprint", "Linear tasks", "project planning", or asks
to "create tickets".

# 好——清晰的价值主张
description: End-to-end customer onboarding workflow for
PayFlow. Handles account creation, payment setup, and
subscription management. Use when user says "onboard new
customer", "set up subscription", or "create PayFlow account".

什么是好的问题?

背景：
（我现在在做什么）
目标：
（我希望达到什么效果）
约束：
（不能做什么 / 必须遵守什么）约束模型行为边界
输出要求：
（代码 / 解释 / 步骤）

文章来源:https://www.cnblogs.com/dddy/p/19814289
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：jacktools123@163.com进行投诉反馈，一经查实，立即删除！