Claude Code Skill功能详解：从重复指令到可复用AI开发技能

30款热门AI模型一站整合DeepSeek/GLM/Claude 随心用限时 5 折。 点击领海量免费额度在实际的 AI 辅助开发工作流中我们经常需要向 Claude 重复解释项目特定的编码规范、部署流程或复杂的多步骤任务。每次手动粘贴这些冗长的指令不仅效率低下也容易出错。Claude Code 的 Skill 功能正是为了解决这一问题而生它允许你将一组固定的指令、检查清单或操作流程封装成一个可复用的“技能”Claude 可以在合适的时机自动调用或者由你通过简单的命令手动触发。这相当于为你的开发环境创建了一套自定义的、智能化的自动化脚本。本文将带你从零开始彻底掌握 Claude Code 中 Skill 的核心概念、安装、创建、触发和使用的完整流程。无论你是希望标准化团队的代码审查流程还是想自动化日常的构建部署或是为特定项目注入领域知识Skill 都能显著提升你与 Claude 协作的效率和准确性。我们将通过一个从简单到复杂的实战案例让你不仅能理解 Skill 是什么更能亲手创建并应用它来解决实际问题。1. 理解 Skill从重复指令到可复用能力在深入操作之前我们首先要厘清 Skill 的本质及其在 Claude Code 中的定位。Skill 不是简单的宏或代码片段它是一种将自然语言指令、上下文信息和工具权限打包成可复用单元的高级机制。1.1 Skill 是什么Skill 的核心是一个包含 YAML 前端元数据Frontmatter和 Markdown 指令的SKILL.md文件。它定义了做什么在 Markdown 正文中描述任务或知识。何时用通过description字段告诉 Claude 在什么对话场景下自动加载此技能。谁触发通过disable-model-invocation等字段控制是由用户手动触发还是由 Claude 自动触发。用什么通过allowed-tools字段预授权 Claude 在执行此技能时使用特定工具无需每次询问。在哪执行通过context: fork等字段决定是在主会话中运行还是在独立的子代理Subagent中隔离执行。与直接写在CLAUDE.md中的项目须知不同Skill 的内容通常只在被触发时才加载到对话上下文中。这意味着你可以创建大量详细的参考技能如“API 设计规范”、“数据库迁移指南”而不会在每次会话开始时都占用宝贵的上下文令牌只有在 Claude 处理相关任务时这些知识才会被动态注入。1.2 Skill 与命令、插件的关系Claude Code 的扩展能力是一个分层体系理解它们的关系有助于正确选用。特性Skill (技能)内置命令 (如/compact)插件 (Plugin)核心形式一个目录内含SKILL.md和可选支持文件。Claude Code 内置的固定功能。一个包含plugin.json的目录可捆绑技能、代理、钩子等。创建者用户、团队或社区。Anthropic (Claude Code 官方)。开发者、社区或组织。主要目的封装可复用的指令集或知识库。提供会话管理、工具调用等基础操作。打包和分发一组相关的扩展功能可包含多个技能。触发方式用户输入/技能名或 Claude 根据描述自动调用。用户输入/命令名。通过/plugin install安装其包含的技能按技能方式触发。能力范围主要是文本指令可预授权工具可运行子代理。固定的程序逻辑。最广泛可包含技能、自定义代理、MCP 服务器、钩子、输出样式等。复用范围个人、项目或企业级。全局可用。通过插件市场安装后在启用该插件的环境中可用。简单来说内置命令是开箱即用的工具。Skill是你根据自身需求定制的“智能脚本”。插件是 Skill 等功能的高级打包和分发形式。原有的.claude/commands/目录下的文件已被合并到 Skill 体系中它们仍然工作但 Skill 目录结构提供了更强大的功能如支持文件和更精细的控制。1.3 Skill 的生命周期与上下文管理理解 Skill 如何被加载和使用对于编写高效的技能至关重要。发现与加载Claude Code 启动时会从多个位置扫描 Skill 目录个人、项目、企业级。Skill 的description会被加载到一个共享的“技能列表”上下文中供 Claude 判断何时调用。这个列表的大小受预算限制过长的描述可能会被截断。触发与执行自动触发当你的对话匹配某个 Skill 的description时Claude 会决定是否调用它。这适用于参考类知识。手动触发你输入/技能名来显式执行。这适用于有副作用的操作如部署。内容注入当一个 Skill 被触发时其SKILL.md的完整内容经过动态上下文替换后会作为一条消息注入到当前对话中。上下文保持与压缩注入的技能内容会保留在会话上下文中影响后续对话。当会话因长度需要压缩时最近使用的技能内容会被优先保留旧的技能内容可能被移除。如果发现技能在几次对话后“失效”可能需要重新触发它。2. 环境准备与 Skill 目录结构在创建第一个 Skill 之前确保你的 Claude Code 已正确安装并运行。我们将从设置 Skill 的存储位置开始。2.1 确认 Claude Code 安装与版本打开终端运行以下命令检查 Claude Code 是否已安装及其版本。Skill 的某些高级功能需要较新版本。claude --version确保你的版本至少是2.1.145或更高以支持/run,/verify等捆绑技能和context: fork等高级特性。如果需要更新请参考官方文档进行升级。2.2 理解 Skill 的存放位置Skill 可以存放在三个主要位置作用范围不同位置路径示例适用范围优先级个人技能~/.claude/skills/skill-name/你所有的项目中项目技能project-root/.claude/skills/skill-name/仅当前项目低企业技能(由管理员配置)组织内所有用户高优先级规则当同名技能存在于多个位置时企业级覆盖个人级个人级覆盖项目级。项目内的技能也会覆盖同名的捆绑技能如/code-review。嵌套目录在单体仓库Monorepo中你可以在子目录如packages/frontend/.claude/skills/下创建技能。当 Claude 处理该子目录的文件时这些技能会自动可用。如果与根目录技能同名它们会以限定名如/packages/frontend:deploy出现。2.3 创建你的个人技能目录首先为你将在所有项目中使用的技能创建一个中心化的存储位置。# 创建个人技能根目录 mkdir -p ~/.claude/skills这个目录将被 Claude Code 自动扫描。在此目录下每个技能都应该拥有自己独立的子目录。3. 创建你的第一个 Skill代码变更总结让我们从一个实用且简单的技能开始自动总结 Git 工作区的未提交变更并识别潜在风险。这个技能演示了 Skill 的基本结构、动态上下文注入和两种触发方式。3.1 创建技能目录和文件在个人技能目录下为我们的“总结变更”技能创建一个文件夹。mkdir -p ~/.claude/skills/summarize-changes接下来在该目录中创建核心文件SKILL.md。# 使用你喜欢的编辑器创建并编辑该文件例如 code ~/.claude/skills/summarize-changes/SKILL.md3.2 编写 SKILL.md 内容将以下内容复制到SKILL.md中。我们逐部分分析其构成。--- 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.前端元数据 (Frontmatter):description: 这是最重要的字段。它用自然语言描述了技能的功能和触发场景。Claude 依靠这个字段来判断是否自动调用该技能。我们明确写明了使用时机“当用户询问变更、需要提交信息或要求审查差异时”。技能正文 (Markdown):## Current changes: 这是一个标题用于组织内容。!git diff HEAD: 这是动态上下文注入的关键语法。!command中的命令会在技能内容发送给 Claude之前执行并将其输出直接替换到该位置。因此Claude 看到的是实时的git diff结果而不是一条待执行的命令。## Instructions: 给 Claude 的具体任务指令。它基于上面注入的 diff 内容进行操作总结变更并识别风险。3.3 测试你的第一个技能打开一个 Git 项目在终端中进入任何一个包含 Git 仓库的目录。制造一些变更修改或创建一个文件但不要提交。echo // test change somefile.js启动 Claude Codeclaude测试自动触发在 Claude Code 会话中输入与description匹配的请求What did I change?如果一切正常Claude 应该会加载summarize-changes技能执行git diff并基于结果给出总结和风险提示。测试手动触发你也可以直接调用技能/summarize-changes这会产生同样的效果。恭喜你已经成功创建并运行了第一个 Skill。这个技能虽然简单但涵盖了 Skill 的核心要素元数据、动态内容注入和任务指令。4. 深入 Skill 配置控制、参数与高级模式掌握了基础技能后我们来探索如何通过前端元数据字段精细控制技能行为以及如何构建更复杂、更强大的技能。4.1 核心前端元数据字段详解以下表格列出了SKILL.md中---之间的 YAML 字段及其用途字段是否必需描述与示例description推荐技能描述。Claude 据此决定是否自动调用。应包含关键用例。name否在技能列表中显示的标签。默认使用目录名。disable-model-invocation否设为true可阻止 Claude 自动调用此技能仅允许用户手动触发。适用于部署、提交等有副作用的操作。user-invocable否设为false可将技能从/菜单中隐藏仅允许 Claude 自动调用。适用于纯背景知识。allowed-tools否技能激活时Claude 可以不经用户批准直接使用的工具列表。例如Bash(git add *) Bash(git commit *)。arguments否定义命名的位置参数用于技能内容中的$name替换。接受列表或空格分隔的字符串。例如[issue, branch]。context否设为fork可使技能在独立的子代理中运行与主会话隔离。agent否当context: fork时指定用于执行的子代理类型如Explore,Plan或自定义代理名。shell否指定!command使用的 shell。bash默认或powershellWindows需设置CLAUDE_CODE_USE_POWERSHELL_TOOL1。4.2 创建需手动触发的部署技能对于像部署这样需要明确用户意图的操作我们应该设置disable-model-invocation: true。创建技能目录和文件mkdir -p ~/.claude/skills/deploy-staging code ~/.claude/skills/deploy-staging/SKILL.md写入以下内容--- name: deploy-staging description: Deploy the application to the staging environment. disable-model-invocation: true allowed-tools: Bash(npm run *) Bash(ssh *) Bash(scp *) arguments: [version, environment] --- # Deploy to Staging Deploy version $version to the $environment environment. ## Prerequisites - Ensure you are on the main branch and have pulled the latest changes. - Ensure all tests pass. ## Deployment Steps 1. **Build the application:** bash npm run buildRun the test suite:npm testDeploy to server:scp -r ./dist userstaging-server:/var/www/app/ ssh userstaging-server cd /var/www/app ./restart.shVerify deployment:Check the staging URL and ensure the new version is running correctly.Rollback PlanIf the deployment fails, revert to the previous version by running:ssh userstaging-server cd /var/www/app git reset --hard HEAD~1 ./restart.sh**关键点分析** 1. **disable-model-invocation: true**确保只有当你输入 /deploy-staging 时该技能才会运行Claude 不会擅自触发部署。 2. **allowed-tools**预授权了 npm run、ssh 和 scp 命令。当技能激活时Claude 可以直接执行这些命令而无需每次询问使流程更流畅。 3. **arguments**定义了两个命名参数 version 和 environment。在技能正文中我们可以用 $version 和 $environment 来引用它们。 4. **结构化指令**将部署流程分解为清晰的步骤并包含了回滚方案使 Claude 的执行更具可预测性。 **使用方式**/deploy-staging 1.2.5 stagingClaude 会接收到一个已经将 $version 替换为 1.2.5、$environment 替换为 staging 的完整部署指令集。 ### 4.3 使用动态上下文注入构建研究技能 !command 语法非常强大它允许技能在运行时获取实时数据。让我们创建一个用于研究 GitHub Issue 的技能。 bash mkdir -p ~/.claude/skills/research-issue code ~/.claude/skills/research-issue/SKILL.md--- name: research-issue description: Research a GitHub issue by number, fetching details, comments, and linked code. context: fork agent: Explore allowed-tools: Bash(gh *) --- # Research GitHub Issue #$ARGUMENTS ## Issue Context Fetching latest issue data... - **Issue Details:** !gh issue view $ARGUMENTS --json title,body,state,labels,assignees --jq . | \Title: \ .title, \State: \ .state, \Labels: \ (.labels | map(.name) | join(\, \)), \Assignees: \ (.assignees | map(.login) | join(\, \)), \\nDescription:\n\ .body - **Issue Comments:** !gh issue view $ARGUMENTS --comments --json comments --jq .comments[] | \- \ .author.login \: \ .body | head -20 - **Linked Pull Requests:** !gh issue view $ARGUMENTS --json linkedPullRequests --jq .linkedPullRequests[] | \- #\ .number \: \ .title \ (\ .state \)\ 2/dev/null || echo \None found.\ ## Your Task Based on the information above: 1. Summarize the core problem or feature request described in the issue. 2. Identify any existing discussion or decisions in the comments. 3. If linked PRs exist, assess their status and whether they address the issue. 4. Suggest potential files in the current codebase that might need to be modified to address this issue. Use Grep or Glob to find relevant code. 5. Propose a high-level implementation approach.关键点分析context: fork与agent: Explore这个技能将在独立的子代理中运行。Explore代理是一个只读的、专注于代码探索的代理它不会修改文件但可以广泛使用Grep、Glob等工具来搜索代码库。这非常适合研究类任务避免了污染主会话的上下文。多命令动态注入我们使用了多个!command来实时获取 Issue 的标题、描述、评论和关联的 PR。这些命令使用 GitHub CLI (gh) 执行。在技能发送给 Claude之前这些占位符就会被实际的命令输出替换。使用$ARGUMENTS技能通过$ARGUMENTS接收用户输入即 Issue 编号。这使得技能可以处理不同的 Issue。使用方式/research-issue 123Claude 会启动一个Explore子代理该代理会先执行gh命令获取 Issue #123 的详细信息然后基于这些实时数据进行分析和提出建议。4.4 添加支持文件构建复杂技能对于复杂的技能可以将详细的参考文档、模板或脚本放在单独的支撑文件中保持SKILL.md的简洁。假设我们有一个“生成 API 客户端”的技能它需要详细的 OpenAPI 规范示例。mkdir -p ~/.claude/skills/generate-api-client/{templates,examples} code ~/.claude/skills/generate-api-client/SKILL.mdSKILL.md内容--- name: generate-api-client description: Generate a TypeScript API client from an OpenAPI specification. disable-model-invocation: true allowed-tools: Bash(npx *) --- # Generate TypeScript API Client This skill generates a type-safe API client based on an OpenAPI spec file. ## Usage Specify the path to your OpenAPI spec (YAML or JSON) as an argument:/generate-api-client ./api/openapi.yaml## Process 1. Validate the OpenAPI specification. 2. Generate client code using the openapi-typescript and openapi-fetch stack. 3. Output the client to ./src/lib/api-client/. ## Reference - For OpenAPI specification conventions, see [spec-conventions.md](spec-conventions.md). - For example generated output, see [examples/generated-client.ts](examples/generated-client.ts). - To customize the template, see [templates/client.hbs](templates/client.hbs). ## Commands to Run bash # Validate spec npx apideck/validatorlatest $ARGUMENTS # Generate types npx openapi-typescript $ARGUMENTS --output ./src/lib/api-client/schema.d.ts # Generate client (example using a custom template) # npx openapi-fetch --schema $ARGUMENTS --output ./src/lib/api-client/ --template ./templates/client.hbs然后创建支撑文件 bash # 创建规范约定文件 code ~/.claude/skills/generate-api-client/spec-conventions.md# API Specification Conventions - Use operationId for every path. - Use consistent error response schemas. - Document all query/path/body parameters. ...# 创建示例输出文件 code ~/.claude/skills/generate-api-client/examples/generated-client.ts// Example generated client import createClient from openapi-fetch; import type { paths } from ./schema; export const client createClientpaths({ baseUrl: /api }); // ...通过SKILL.md中的[文件名](文件名)语法Claude 在需要时会去读取这些支撑文件的内容。这避免了将大量参考信息一次性全部加载到上下文中节省了令牌。5. 技能的管理、排查与最佳实践创建技能后你需要知道如何管理它们以及当技能不按预期工作时如何排查。5.1 查看与管理可用技能在 Claude Code 会话中你可以使用以下命令/help列出所有可用的命令和技能。技能会带有[Skill]标记。/skills打开一个交互式面板查看所有技能及其描述、触发状态。你可以在这里按空格键切换技能的可见性状态on,name-only,user-invocable-only,off这些设置会保存到.claude/settings.local.json的skillOverrides中。/context查看当前会话的上下文使用情况其中包含“Skills”一行显示技能列表占用的令牌数。5.2 常见问题排查问题现象可能原因检查与解决步骤技能没有出现在/help列表中1. 技能目录位置错误。2.SKILL.md文件名或路径错误。3. 前端元数据 YAML 格式错误。1. 确认技能放在~/.claude/skills/或项目.claude/skills/下。2. 确认入口文件名为SKILL.md大小写敏感。3. 检查---分隔符和 YAML 缩进。可尝试在启动 Claude Code 时加--debug参数查看解析错误。Claude 不自动触发技能1.description不够具体或与用户请求不匹配。2. 技能列表预算超限描述被截断。3. 设置了disable-model-invocation: true。1. 优化description包含用户可能说的关键词。2. 运行/doctor查看技能列表预算和截断情况。考虑将不重要的技能设为name-only。3. 确认是否需要手动触发。手动触发技能 (/skill-name) 无效1. 技能名输入错误。2. 设置了user-invocable: false。3. 技能被skillOverrides设置为off。1. 使用/skills面板确认准确的技能名。2. 检查技能前端元数据中的user-invocable字段。3. 检查.claude/settings.local.json中的skillOverrides设置。!command占位符没有执行1. 语法错误如缺少反引号。2. 命令执行失败或输出为空。3. 全局设置disableSkillShellExecution为true。1. 确保格式为!command注意是反引号。2. 在终端中手动运行该命令确保它能成功执行并输出内容。3. 检查 Claude Code 设置。技能内容在几次对话后似乎“失效”会话上下文压缩Auto-compaction移除了较早的技能内容。重新触发该技能 (/skill-name)将其内容重新注入到当前上下文中。5.3 技能设计与编写最佳实践描述要具体description是 Claude 匹配的关键。使用动作导向的语言并包含用户可能使用的同义词。例如“Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.”正文要简洁技能内容一旦加载会持续占用上下文令牌。避免冗长的叙述直接说明要做什么。将详细的参考资料移到单独的支撑文件中。为有副作用的操作设置disable-model-invocation: true对于部署、提交、发送消息等操作务必禁止 Claude 自动调用确保控制权在用户手中。善用动态上下文注入 (!command)让技能基于实时数据git 状态、API 响应、文件列表运行而不是静态的假设。复杂任务使用context: fork对于需要深度研究、探索或可能干扰主会话流程的任务在子代理中运行它们。这能保持主会话的整洁并允许使用专门的代理如Explore。预授权工具 (allowed-tools)对于你信任的技能预授权相关工具可以消除频繁的确认弹窗使交互更流畅。但需谨慎授权尤其是对于项目级技能。测试与迭代使用skill-creator插件通过/plugin install skill-creatorclaude-plugins-official安装来系统化地测试你的技能。它可以帮你创建测试用例在有无技能的情况下分别运行并比较输出结果确保技能按预期工作。项目技能要提交到版本控制将.claude/skills/目录添加到你的项目仓库中确保团队所有成员共享同一套开发规范和工作流。5.4 从个人技能到团队共享当你打磨好一个有用的技能后可以考虑将其分享项目级共享将技能目录复制到项目的.claude/skills/下并提交到 Git。这是最简单的团队共享方式。创建插件如果你有一组相关的技能、代理或配置可以将它们打包成一个插件。创建一个包含plugin.json的目录将技能放在skills/子目录下。插件可以通过文件共享或发布到插件市场来分发。企业级部署对于大型组织管理员可以通过托管设置Managed Settings向所有用户部署技能。Skill 是 Claude Code 将静态知识转化为动态能力的关键桥梁。通过将重复的流程、项目特定的知识和复杂的操作封装成可触发、可组合的技能你不仅能提升个人效率更能为整个团队构建起一套智能、一致的开发辅助环境。从今天开始尝试将你最常向 Claude 复述的指令写成第一个 Skill体验自动化带来的流畅感。 30款热门AI模型一站整合DeepSeek/GLM/Claude 随心用限时 5 折。 点击领海量免费额度