在实际使用 Claude Code 进行开发时很多开发者会遇到一个瓶颈面对复杂的、需要多步骤协作或特定领域知识的任务单纯依靠代码补全和对话交互效率并不高。这时Claude Code 的 Skill 功能就显得尤为重要。它允许你将一系列操作、逻辑、甚至外部工具调用封装成一个可复用的“技能”从而将 Claude Code 从一个智能代码助手升级为一个可以执行特定工作流的自动化伙伴。理解 Skill 的本质、掌握其安装、创建和触发方法是解锁 Claude Code 高级用法的关键。Skill 的核心是“可复用的自动化脚本”。它不仅仅是一个代码片段更是一个包含触发条件、执行逻辑、参数处理和结果输出的完整单元。例如你可以创建一个 Skill 来自动化代码审查流程当你在代码文件中输入特定注释时Skill 被触发自动分析当前文件的代码风格、潜在 Bug 和安全漏洞并将结果以结构化评论的形式插入到文件中。这远比手动与 Claude Code 对话描述审查需求要高效和精准得多。本文将以一个完整的实战流程带你从零开始理解 Claude Code 中的 Skill。我们将首先厘清 Skill 的概念和工作原理然后准备必要的开发环境。接着我们会一步步创建一个用于“自动生成函数单元测试”的实用 Skill涵盖从项目结构、代码编写、配置定义到本地安装的全过程。最后我们会详细探讨多种触发和使用 Skill 的方式并针对开发中常见的配置错误、触发失败等问题提供具体的排查路径和解决方案。无论你是想提升个人开发效率还是为团队构建标准化的开发工具链掌握 Skill 的创建与使用都将是一个强有力的助力。1. 理解 Claude Code Skill从自动化脚本到智能工作流在深入动手之前我们必须先建立对 Skill 的准确认知。很多人容易将 Skill 与普通的代码片段或宏命令混淆这会导致在使用时无法发挥其最大价值。1.1 Skill 是什么不仅仅是代码块Claude Code Skill 是一个由 YAML 配置文件和 Python 脚本或其他可执行逻辑共同定义的、可被 Claude Code 识别和调用的自动化模块。你可以把它想象成 IDE 的插件或命令行工具但它更深地集成在 Claude Code 的上下文中能够直接读取编辑器状态、项目文件并与 Claude Code 的 AI 能力进行交互。一个标准的 Skill 包含以下几个核心部分元数据Metadata定义 Skill 的名称、描述、版本、作者等信息通常存放在skill.yaml文件中。这是 Claude Code 识别和管理 Skill 的入口。触发器Triggers规定 Skill 在什么条件下被激活。常见触发器包括特定的命令行命令、代码中的特殊注释如// skill-generate-test、文件保存事件、或者通过 Claude Code 的 UI 按钮手动触发。执行逻辑Execution Logic这是 Skill 的核心即它被触发后具体要做什么。这通常是一段 Python 脚本它可以分析当前打开的代码文件。调用 Claude Code 的 API 来生成代码、解释逻辑或回答问题。执行系统命令如运行测试、格式化代码。读写项目中的其他文件。与外部 API 或服务进行通信。参数ParametersSkill 可以接受输入参数使其行为更加灵活。参数可以通过触发器传递例如在命令中附带参数或在注释中指定。输出OutputSkill 执行完成后可以将结果输出到多个地方直接插入到当前编辑器、创建一个新文件、在终端显示信息或者在 Claude Code 的特定面板中展示。与简单的代码片段相比Skill 的优势在于其上下文感知能力和流程封装性。一个代码片段你需要手动选择并粘贴到合适的位置而 Skill 可以自动分析你光标所在的函数然后在其下方生成匹配的测试代码整个过程无需你离开编辑器进行任何复制粘贴操作。1.2 Skill 的工作原理事件驱动的协作模型理解 Skill 的工作流程有助于后续的调试和问题排查。其生命周期大致如下监听Claude Code 启动后会加载所有已安装 Skill 的skill.yaml配置文件并注册其中定义的触发器。触发当用户在编辑器或终端中执行了匹配某个触发器定义的操作时例如输入了特定命令Claude Code 会捕获到这个事件。准备上下文Claude Code 会为即将执行的 Skill 准备运行时上下文。这通常包括当前工作目录、打开的文件路径、文件内容、光标位置、选中的文本等。执行Claude Code 调用该 Skill 对应的执行脚本如main.py并将上下文信息作为参数或环境变量传递给脚本。处理与输出Skill 脚本执行其逻辑处理传入的上下文和参数最终通过标准输出、写入文件或调用 Claude Code API 等方式返回结果。渲染Claude Code 接收 Skill 的输出并按照 Skill 定义的方式将其呈现给用户例如替换选中文本、在新标签页打开生成的文件等。这个过程是事件驱动的。Skill 开发者不需要关心 Claude Code 主程序如何运行只需要关注“当我的触发器被激活时我能拿到什么数据以及我需要输出什么数据”。注意Skill 的执行环境通常是受限的。出于安全考虑它可能无法访问某些系统路径或执行高危命令。在开发涉及文件操作或命令执行的 Skill 时务必考虑跨平台兼容性和权限问题。2. 环境准备与 Claude Code 配置在创建第一个 Skill 之前确保你的基础环境是正确可用的。许多后续问题都源于环境配置不当。2.1 基础环境检查Claude Code Skill 开发主要依赖 Python 和 Claude Code 本身。请按顺序检查以下项目Python 环境Skill 脚本通常用 Python 编写。打开终端命令行执行以下命令python --version # 或 python3 --version确保显示 Python 3.7 或更高版本。如果未安装请从 Python 官网下载安装。建议使用虚拟环境来管理 Skill 的依赖避免污染全局 Python 环境。可以使用venv或conda创建。# 使用 venv 创建虚拟环境 python -m venv claude-skill-env # 激活虚拟环境 (Windows) claude-skill-env\Scripts\activate # 激活虚拟环境 (macOS/Linux) source claude-skill-env/bin/activateClaude Code 安装与版本确认你已正确安装 Claude Code。启动 Claude Code通常可以在帮助菜单或关于页面中找到版本信息。确保你使用的是支持 Skill 功能的版本较新的稳定版通常都支持。Skill 功能可能位于扩展Extensions或插件Plugins管理面板中。Skill 开发目录Claude Code 需要知道去哪里寻找 Skill。通常Skill 可以安装在用户目录下的特定文件夹中例如~/.claude-code/skills/Linux/macOS或%USERPROFILE%\.claude-code\skills\Windows。你需要确认这个目录存在或者根据 Claude Code 的文档确认正确的 Skill 安装路径。2.2 验证 Claude Code 的 Skill 功能在 Claude Code 中通过界面或命令验证 Skill 功能是否就绪。查看已安装 Skill在 Claude Code 中尝试打开命令面板通常快捷键是CtrlShiftP或CmdShiftP输入并选择类似“Skills: List Installed Skills”的命令。如果该命令存在并能显示一个列表即使是空的说明 Skill 框架已启用。检查设置在 Claude Code 的设置中搜索“skill”相关配置项。可能会存在如skill.path或skill.autoDiscovery等设置用于指定 Skill 的加载路径。如果找不到任何与 Skill 相关的命令或设置很可能你使用的 Claude Code 版本不包含此功能或者该功能需要手动启用。请查阅对应版本的官方文档。2.3 创建 Skill 开发工作区为了高效开发建议建立一个独立的工作目录来存放你的 Skill 项目。# 创建一个专门用于 Skill 开发的目录 mkdir -p ~/dev/claude-skills cd ~/dev/claude-skills # 为我们即将创建的示例 Skill 创建项目文件夹 mkdir unit-test-generator cd unit-test-generator这个unit-test-generator文件夹将包含我们第一个 Skill 的所有文件。3. 创建你的第一个 Skill单元测试生成器我们将创建一个实用的 Skill单元测试生成器。它的功能是当用户在代码文件中将光标置于一个函数定义上并触发该 Skill 时自动为这个函数生成相应的单元测试代码并插入到当前文件或一个相邻的测试文件中。3.1 定义 Skill 元数据skill.yaml在unit-test-generator目录下创建skill.yaml文件。这是 Skill 的“身份证”和“说明书”。# skill.yaml name: unit-test-generator version: 1.0.0 author: Your Name description: 自动为当前光标所在的函数生成单元测试代码。 license: MIT # 触发器定义 triggers: - type: command command: generate-unit-test title: 生成单元测试 description: 为当前函数生成单元测试 # 执行入口点 entryPoint: main.py # 运行时配置可选 configuration: # 测试框架选择默认为 pytest testFramework: type: string default: pytest description: 使用的测试框架 (pytest, unittest) # 测试文件后缀 testFileSuffix: type: string default: _test.py description: 测试文件的后缀例如 _test.py 或 Test.py关键参数解释name: Skill 的唯一标识符在命令中会用到。triggers: 定义了如何触发这个 Skill。这里我们定义了一个类型为command的触发器意味着在 Claude Code 的命令面板中输入generate-unit-test即可触发。entryPoint: 指定当 Skill 被触发时Claude Code 应该执行哪个脚本文件。这里是main.py。configuration: 这里定义了一些用户可配置的选项。这些配置值可以在 Skill 脚本中读取使得 Skill 的行为更灵活。例如用户可以在 Claude Code 的设置中修改testFramework的默认值。3.2 实现核心逻辑main.py在同一个目录下创建main.py文件。这是 Skill 的大脑。#!/usr/bin/env python3 # main.py import os import sys import json import subprocess from pathlib import Path def main(): Skill 的主函数。Claude Code 会调用此函数。 它通过标准输入 (stdin) 接收上下文数据并通过标准输出 (stdout) 返回结果。 # 1. 读取 Claude Code 传递过来的上下文数据 input_data sys.stdin.read() if not input_data: print(json.dumps({error: 未接收到输入数据}), filesys.stderr) sys.exit(1) try: context json.loads(input_data) except json.JSONDecodeError as e: print(json.dumps({error: f输入数据 JSON 解析失败: {e}}), filesys.stderr) sys.exit(1) # 2. 从上下文中提取关键信息 # 这些字段名取决于 Claude Code 的 API通常是固定的或可查阅文档 current_file context.get(filePath) cursor_position context.get(cursorPosition, {}) # 可能包含 line, column file_content context.get(fileContent, ) # 获取 Skill 的配置参数 config context.get(configuration, {}) test_framework config.get(testFramework, pytest) test_suffix config.get(testFileSuffix, _test.py) if not current_file: print(json.dumps({error: 无法获取当前文件路径}), filesys.stderr) sys.exit(1) # 3. 解析当前文件找到光标所在的函数 # 这是一个简化的示例实际中可能需要更复杂的语法分析例如使用 ast 模块 target_function extract_function_at_cursor(file_content, cursor_position) if not target_function: print(json.dumps({error: 无法在光标位置识别到有效的函数定义}), filesys.stderr) sys.exit(1) # 4. 调用 Claude Code 的 AI 能力来生成测试代码模拟 # 在实际开发中这里可能会通过 HTTP 请求调用 Claude Code 的内部 API # 本例中我们模拟一个简单的基于规则的生成 generated_test_code generate_test_code(target_function, test_framework) # 5. 决定将生成的测试代码放在哪里 output_action decide_output_action(current_file, test_suffix, generated_test_code) # 6. 将结果以 Claude Code 期望的格式输出 result { action: output_action[type], content: output_action.get(content), filePath: output_action.get(filePath), message: f已为函数 {target_function.get(name)} 生成 {test_framework} 测试。 } print(json.dumps(result)) def extract_function_at_cursor(content, cursor_pos): 简化版的函数提取逻辑。实际项目应使用 ast 等库进行精确解析。 lines content.split(\n) line_num cursor_pos.get(line, 0) # 从光标行向上搜索找到以 def 开头的行 for i in range(line_num, -1, -1): if lines[i].strip().startswith(def ): func_line lines[i] # 非常简单的提取假设函数名后紧跟括号 import re match re.match(rdef\s(\w), func_line) if match: return { name: match.group(1), line: i, signature: func_line.strip() } return None def generate_test_code(func_info, framework): 根据函数信息和测试框架生成测试代码。 func_name func_info[name] if framework pytest: return fimport pytest def test_{func_name}(): Test for function {func_name}. # TODO: 编写具体的测试逻辑 # 示例: result {func_name}(...) # assert result expected_value raise NotImplementedError(测试用例待实现) elif framework unittest: return fimport unittest class Test{func_name.capitalize()}(unittest.TestCase): def test_{func_name}(self): Test for function {func_name}. # TODO: 编写具体的测试逻辑 # 示例: result {func_name}(...) # self.assertEqual(result, expected_value) self.fail(测试用例待实现) if __name__ __main__: unittest.main() else: return f# 测试框架 {framework} 暂不支持自动生成模板。 def decide_output_action(current_file_path, test_suffix, test_code): 决定输出行为插入当前文件还是创建新测试文件。 current_path Path(current_file_path) # 策略如果当前文件已经是测试文件以 _test.py 结尾则插入当前文件 if current_path.name.endswith(test_suffix): return { type: insert, content: test_code, position: endOfFile # 可以是 cursorPosition, endOfFile 等 } else: # 否则创建对应的测试文件 test_file_name current_path.stem test_suffix test_file_path current_path.parent / test_file_name return { type: createFile, filePath: str(test_file_path), content: test_code } if __name__ __main__: main()代码核心逻辑解读数据输入Skill 通过标准输入sys.stdin接收一个 JSON 字符串其中包含了 Claude Code 传递的完整上下文文件路径、内容、光标位置、配置等。上下文解析脚本解析 JSON提取出当前文件、光标位置和用户配置。这是 Skill 感知环境的依据。业务逻辑extract_function_at_cursor函数尝试从光标位置向上查找函数定义。这是一个简化实现生产级 Skill 应使用 Python 的ast抽象语法树模块进行精确解析。生成内容generate_test_code函数根据选择的测试框架pytest/unittest生成对应的测试代码模板。这里只是静态生成更强大的 Skill 可以在此处调用 Claude Code 的 AI API根据函数的具体实现动态生成更有针对性的测试用例。输出决策decide_output_action函数决定输出方式。如果当前文件已经是测试文件则将测试代码插入文件末尾否则创建一个新的测试文件。这体现了 Skill 的智能决策能力。结果返回最后脚本将一个包含action、content等字段的 JSON 对象打印到标准输出sys.stdout。Claude Code 会读取这个输出并根据action类型执行相应的操作如插入文本、创建文件。3.3 完善项目结构与依赖一个完整的 Skill 项目可能还需要其他文件。依赖管理 (requirements.txt)如果你的 Skill 需要第三方库例如requests用于调用外部 API需要在此声明。# requirements.txt # 本例中未使用外部库文件可为空或包含通用工具库 # requests2.28.0说明文档 (README.md)良好的文档对于 Skill 的分享和使用至关重要。# Unit Test Generator Skill 一个 Claude Code Skill用于自动生成 Python 函数的单元测试代码。 ## 功能 - 识别光标所在的 Python 函数。 - 支持 pytest 和 unittest 框架的测试模板。 - 智能判断并插入测试代码到当前文件或创建新的测试文件。 ## 使用方法 1. 将光标置于目标函数定义行内。 2. 在 Claude Code 中打开命令面板 (CtrlShiftP / CmdShiftP)。 3. 输入并执行命令 generate-unit-test。 ## 配置 在 Claude Code 设置中搜索 unit-test-generator可以修改 - testFramework: 选择测试框架 (pytest/unittest)。 - testFileSuffix: 指定测试文件的后缀。最终项目结构unit-test-generator/ ├── skill.yaml # Skill 元数据与触发器定义 ├── main.py # 核心执行逻辑 ├── requirements.txt # Python 依赖声明可选 └── README.md # 使用说明可选4. 安装、触发与使用 Skill创建好 Skill 项目后下一步就是将其安装到 Claude Code 中并验证其功能。4.1 安装 Skill 到 Claude CodeClaude Code 通常有两种安装 Skill 的方式本地路径安装和打包发布安装。对于开发阶段我们使用本地安装。找到 Skill 目录首先你需要确定 Claude Code 用于加载本地 Skill 的目录。这个目录通常位于用户配置文件夹下。你可以通过以下方式查找或确认在 Claude Code 的设置中搜索skill。查阅 Claude Code 的官方文档中关于“Skill Development”或“Local Skill”的部分。常见的路径有macOS/Linux:~/.claude-code/skills/或~/.config/Claude Code/skills/Windows:%APPDATA%\Claude Code\skills\或%USERPROFILE%\.claude-code\skills\创建符号链接或直接复制推荐使用符号链接软链接这样你在开发目录 (~/dev/claude-skills/unit-test-generator) 中的修改能实时生效。# macOS/Linux 示例 ln -s ~/dev/claude-skills/unit-test-generator ~/.claude-code/skills/unit-test-generator # Windows (PowerShell 管理员模式) 示例 # New-Item -ItemType SymbolicLink -Path $env:USERPROFILE\.claude-code\skills\unit-test-generator -Target C:\Users\YourName\dev\claude-skills\unit-test-generator如果无法创建符号链接也可以直接将整个unit-test-generator文件夹复制到上述 Skill 目录中。重启或重载 Claude Code安装后需要重启 Claude Code或者执行重载 Skill 的命令如果存在以使新 Skill 被加载。4.2 触发 Skill 的多种方式我们的skill.yaml中定义了一个command类型的触发器。这是最常用的一种方式。通过命令面板触发在 Claude Code 中打开一个 Python 文件将光标放在某个函数定义内部例如def calculate_sum(a, b):这一行。按下CtrlShiftP(Windows/Linux) 或CmdShiftP(macOS) 打开命令面板。输入generate-unit-test即我们在skill.yaml中定义的command值。从列表中选择该命令并执行。通过快捷键绑定可选为了提高效率你可以在 Claude Code 的键盘快捷键设置中为generate-unit-test命令分配一个快捷键。其他触发器类型除了commandSkill 还可以定义其他触发器例如comment: 当代码中出现特定格式的注释时触发如# skill-test。fileEvent: 当文件被保存、打开时触发。uiButton: 在 Claude Code 的 UI 中添加一个按钮来触发。 定义这些触发器需要在skill.yaml的triggers部分进行更详细的配置具体语法需参考 Claude Code 的官方 Skill 开发文档。4.3 验证 Skill 运行结果成功触发 Skill 后你应该能看到以下效果之一场景一创建新测试文件如果当前文件是math_utils.py且光标在calculate_sum函数上Skill 会在同一目录下创建一个名为math_utils_test.py的文件并包含生成的测试模板。场景二插入当前文件如果当前文件已经是math_utils_test.py则生成的测试代码会被插入到这个文件的末尾。你可以在 Claude Code 的“输出”面板Output中选择对应的 Skill 通道查看main.py脚本打印的日志和错误信息这对于调试至关重要。5. 常见问题排查与调试技巧开发和使用 Skill 过程中难免会遇到问题。以下是一些常见问题的排查路径。5.1 Skill 安装后未出现在命令面板问题现象可能原因检查方式处理建议在命令面板输入generate-unit-test找不到命令。1. Skill 目录不正确。2.skill.yaml文件格式错误。3. Claude Code 未加载 Skill。1. 确认skill.yaml文件在正确的 Skill 加载目录下。2. 使用 YAML 在线校验工具检查skill.yaml语法。3. 重启 Claude Code或在命令面板尝试运行Skills: Reload命令如果存在。1. 检查并修正 Skill 安装路径。2. 确保skill.yaml缩进正确关键字段name,triggers,entryPoint存在且有效。3. 查看 Claude Code 的开发者控制台Developer Tools是否有加载错误。5.2 Skill 触发后无反应或报错问题现象可能原因检查方式处理建议执行命令后编辑器没有任何变化也没有错误提示。1.main.py脚本执行出错但未捕获。2. Skill 输出格式不符合 Claude Code 预期。3. Python 环境或依赖问题。1.查看输出面板在 Claude Code 中打开“输出”Output面板在下拉列表中选择与你 Skill 名称相关的通道查看日志。2.手动测试脚本在终端中模拟 Claude Code 的输入调用你的main.py检查其输出。echo {filePath:test.py, cursorPosition:{line:5}} | python main.py3. 检查main.py是否有执行权限 (chmod x main.py)。1. 在main.py中增加更详细的错误捕获和日志输出print(json.dumps(...), filesys.stderr)。2. 确保脚本最后打印的 JSON 结果格式正确特别是action字段是 Claude Code 支持的类型。3. 确保用于运行 Skill 的 Python 解释器路径正确且安装了所有必需的依赖。5.3 Skill 逻辑不符合预期问题现象可能原因检查方式处理建议Skill 执行了但生成的测试代码位置不对或内容错误。1. 上下文数据解析错误。2. 业务逻辑函数如extract_function_at_cursor有 bug。3. 配置参数未正确读取。1. 在main.py开头打印接收到的完整contextJSON确认数据结构。2. 单独测试extract_function_at_cursor函数传入各种边界情况的content和cursor_pos。3. 打印config变量确认是否成功读取了用户设置。1. 根据打印的上下文调整解析逻辑。2. 使用更健壮的解析方式例如用ast模块替代简单的字符串搜索。3. 在skill.yaml和读取配置的代码中确保配置项的键名完全一致。5.4 性能与权限问题Skill 执行缓慢如果 Skill 需要调用网络 API 或执行复杂计算可能会阻塞编辑器。考虑将耗时操作异步化或提供进度提示。文件操作权限不足如果 Skill 需要写入系统目录或受保护的文件可能会因权限问题失败。确保 Skill 只在项目工作区内操作文件并做好异常处理try...except PermissionError。跨平台兼容性路径分隔符/vs\、命令行工具差异可能导致问题。在代码中使用pathlib.Path或os.path.join来处理路径避免硬编码。6. 进阶实践与最佳实践掌握了基础创建流程后你可以遵循以下最佳实践来构建更强大、更可靠的 Skill。6.1 设计可配置与可扩展的 Skill充分利用configuration将可能会变的选项如 API 密钥、默认行为、文件命名规则都设计为配置项让用户无需修改代码即可定制。参数化触发器让命令可以接受参数。例如generate-unit-test --frameworkunittest。这需要在skill.yaml的触发器定义和main.py的参数解析中做相应设计。模块化代码将核心逻辑如代码分析、AI 调用、文件操作拆分成独立的函数或类使main.py保持清晰便于单元测试和维护。6.2 提升 Skill 的智能与实用性集成 AI 能力我们的示例是静态生成模板。一个真正的“智能”测试生成器应该分析目标函数的签名、文档字符串甚至实现逻辑调用 Claude Code 的 API 来生成更具体、更合理的测试用例和断言。这通常需要向 Claude Code 的后端服务发送一个包含代码上下文的请求。错误处理与用户反馈对可能出错的地方如网络超时、解析失败、文件已存在进行妥善处理并通过 Claude Code 的消息提示或输出面板给用户清晰友好的反馈而不是让脚本静默失败。支持更多语言和框架将 Skill 从 Python 扩展到 JavaScript、Java、Go 等其他语言并支持这些语言生态中流行的测试框架如 Jest, JUnit。6.3 生产环境下的考量日志与监控为 Skill 添加详细的日志记录记录触发时间、输入上下文、执行结果和耗时。这对于排查线上问题和了解 Skill 使用情况非常重要。版本管理使用语义化版本控制SemVer来管理你的 Skill。在skill.yaml中更新version字段并在发布时提供更新日志。安全审计如果 Skill 会执行用户输入的代码、访问网络或文件系统必须进行严格的安全审查。避免命令注入、路径遍历等安全漏洞。不要执行未经校验的外部命令。性能优化避免在 Skill 中执行阻塞主线程的长时间操作。对于复杂任务可以考虑将其委托给后台进程或服务。从创建一个简单的单元测试生成器开始你已经走完了 Skill 开发的核心流程定义元数据、编写执行逻辑、处理上下文、输出结果。这个模式可以扩展到无数场景代码格式化、依赖检查、API 客户端生成、数据库迁移脚本创建、部署自动化等等。关键在于想清楚你想要自动化的工作流是什么然后利用 Claude Code 提供的上下文信息和 AI 能力将其封装成一个精准、高效的 Skill。开始构思你的下一个 Skill将重复性工作交给自动化让自己更专注于创造性的编码。
在实际使用 Claude Code 进行开发时很多开发者会遇到一个瓶颈面对复杂的、需要多步骤协作或特定领域知识的任务单纯依靠代码补全和对话交互效率并不高。这时Claude Code 的 Skill 功能就显得尤为重要。它允许你将一系列操作、逻辑、甚至外部工具调用封装成一个可复用的“技能”从而将 Claude Code 从一个智能代码助手升级为一个可以执行特定工作流的自动化伙伴。理解 Skill 的本质、掌握其安装、创建和触发方法是解锁 Claude Code 高级用法的关键。Skill 的核心是“可复用的自动化脚本”。它不仅仅是一个代码片段更是一个包含触发条件、执行逻辑、参数处理和结果输出的完整单元。例如你可以创建一个 Skill 来自动化代码审查流程当你在代码文件中输入特定注释时Skill 被触发自动分析当前文件的代码风格、潜在 Bug 和安全漏洞并将结果以结构化评论的形式插入到文件中。这远比手动与 Claude Code 对话描述审查需求要高效和精准得多。本文将以一个完整的实战流程带你从零开始理解 Claude Code 中的 Skill。我们将首先厘清 Skill 的概念和工作原理然后准备必要的开发环境。接着我们会一步步创建一个用于“自动生成函数单元测试”的实用 Skill涵盖从项目结构、代码编写、配置定义到本地安装的全过程。最后我们会详细探讨多种触发和使用 Skill 的方式并针对开发中常见的配置错误、触发失败等问题提供具体的排查路径和解决方案。无论你是想提升个人开发效率还是为团队构建标准化的开发工具链掌握 Skill 的创建与使用都将是一个强有力的助力。1. 理解 Claude Code Skill从自动化脚本到智能工作流在深入动手之前我们必须先建立对 Skill 的准确认知。很多人容易将 Skill 与普通的代码片段或宏命令混淆这会导致在使用时无法发挥其最大价值。1.1 Skill 是什么不仅仅是代码块Claude Code Skill 是一个由 YAML 配置文件和 Python 脚本或其他可执行逻辑共同定义的、可被 Claude Code 识别和调用的自动化模块。你可以把它想象成 IDE 的插件或命令行工具但它更深地集成在 Claude Code 的上下文中能够直接读取编辑器状态、项目文件并与 Claude Code 的 AI 能力进行交互。一个标准的 Skill 包含以下几个核心部分元数据Metadata定义 Skill 的名称、描述、版本、作者等信息通常存放在skill.yaml文件中。这是 Claude Code 识别和管理 Skill 的入口。触发器Triggers规定 Skill 在什么条件下被激活。常见触发器包括特定的命令行命令、代码中的特殊注释如// skill-generate-test、文件保存事件、或者通过 Claude Code 的 UI 按钮手动触发。执行逻辑Execution Logic这是 Skill 的核心即它被触发后具体要做什么。这通常是一段 Python 脚本它可以分析当前打开的代码文件。调用 Claude Code 的 API 来生成代码、解释逻辑或回答问题。执行系统命令如运行测试、格式化代码。读写项目中的其他文件。与外部 API 或服务进行通信。参数ParametersSkill 可以接受输入参数使其行为更加灵活。参数可以通过触发器传递例如在命令中附带参数或在注释中指定。输出OutputSkill 执行完成后可以将结果输出到多个地方直接插入到当前编辑器、创建一个新文件、在终端显示信息或者在 Claude Code 的特定面板中展示。与简单的代码片段相比Skill 的优势在于其上下文感知能力和流程封装性。一个代码片段你需要手动选择并粘贴到合适的位置而 Skill 可以自动分析你光标所在的函数然后在其下方生成匹配的测试代码整个过程无需你离开编辑器进行任何复制粘贴操作。1.2 Skill 的工作原理事件驱动的协作模型理解 Skill 的工作流程有助于后续的调试和问题排查。其生命周期大致如下监听Claude Code 启动后会加载所有已安装 Skill 的skill.yaml配置文件并注册其中定义的触发器。触发当用户在编辑器或终端中执行了匹配某个触发器定义的操作时例如输入了特定命令Claude Code 会捕获到这个事件。准备上下文Claude Code 会为即将执行的 Skill 准备运行时上下文。这通常包括当前工作目录、打开的文件路径、文件内容、光标位置、选中的文本等。执行Claude Code 调用该 Skill 对应的执行脚本如main.py并将上下文信息作为参数或环境变量传递给脚本。处理与输出Skill 脚本执行其逻辑处理传入的上下文和参数最终通过标准输出、写入文件或调用 Claude Code API 等方式返回结果。渲染Claude Code 接收 Skill 的输出并按照 Skill 定义的方式将其呈现给用户例如替换选中文本、在新标签页打开生成的文件等。这个过程是事件驱动的。Skill 开发者不需要关心 Claude Code 主程序如何运行只需要关注“当我的触发器被激活时我能拿到什么数据以及我需要输出什么数据”。注意Skill 的执行环境通常是受限的。出于安全考虑它可能无法访问某些系统路径或执行高危命令。在开发涉及文件操作或命令执行的 Skill 时务必考虑跨平台兼容性和权限问题。2. 环境准备与 Claude Code 配置在创建第一个 Skill 之前确保你的基础环境是正确可用的。许多后续问题都源于环境配置不当。2.1 基础环境检查Claude Code Skill 开发主要依赖 Python 和 Claude Code 本身。请按顺序检查以下项目Python 环境Skill 脚本通常用 Python 编写。打开终端命令行执行以下命令python --version # 或 python3 --version确保显示 Python 3.7 或更高版本。如果未安装请从 Python 官网下载安装。建议使用虚拟环境来管理 Skill 的依赖避免污染全局 Python 环境。可以使用venv或conda创建。# 使用 venv 创建虚拟环境 python -m venv claude-skill-env # 激活虚拟环境 (Windows) claude-skill-env\Scripts\activate # 激活虚拟环境 (macOS/Linux) source claude-skill-env/bin/activateClaude Code 安装与版本确认你已正确安装 Claude Code。启动 Claude Code通常可以在帮助菜单或关于页面中找到版本信息。确保你使用的是支持 Skill 功能的版本较新的稳定版通常都支持。Skill 功能可能位于扩展Extensions或插件Plugins管理面板中。Skill 开发目录Claude Code 需要知道去哪里寻找 Skill。通常Skill 可以安装在用户目录下的特定文件夹中例如~/.claude-code/skills/Linux/macOS或%USERPROFILE%\.claude-code\skills\Windows。你需要确认这个目录存在或者根据 Claude Code 的文档确认正确的 Skill 安装路径。2.2 验证 Claude Code 的 Skill 功能在 Claude Code 中通过界面或命令验证 Skill 功能是否就绪。查看已安装 Skill在 Claude Code 中尝试打开命令面板通常快捷键是CtrlShiftP或CmdShiftP输入并选择类似“Skills: List Installed Skills”的命令。如果该命令存在并能显示一个列表即使是空的说明 Skill 框架已启用。检查设置在 Claude Code 的设置中搜索“skill”相关配置项。可能会存在如skill.path或skill.autoDiscovery等设置用于指定 Skill 的加载路径。如果找不到任何与 Skill 相关的命令或设置很可能你使用的 Claude Code 版本不包含此功能或者该功能需要手动启用。请查阅对应版本的官方文档。2.3 创建 Skill 开发工作区为了高效开发建议建立一个独立的工作目录来存放你的 Skill 项目。# 创建一个专门用于 Skill 开发的目录 mkdir -p ~/dev/claude-skills cd ~/dev/claude-skills # 为我们即将创建的示例 Skill 创建项目文件夹 mkdir unit-test-generator cd unit-test-generator这个unit-test-generator文件夹将包含我们第一个 Skill 的所有文件。3. 创建你的第一个 Skill单元测试生成器我们将创建一个实用的 Skill单元测试生成器。它的功能是当用户在代码文件中将光标置于一个函数定义上并触发该 Skill 时自动为这个函数生成相应的单元测试代码并插入到当前文件或一个相邻的测试文件中。3.1 定义 Skill 元数据skill.yaml在unit-test-generator目录下创建skill.yaml文件。这是 Skill 的“身份证”和“说明书”。# skill.yaml name: unit-test-generator version: 1.0.0 author: Your Name description: 自动为当前光标所在的函数生成单元测试代码。 license: MIT # 触发器定义 triggers: - type: command command: generate-unit-test title: 生成单元测试 description: 为当前函数生成单元测试 # 执行入口点 entryPoint: main.py # 运行时配置可选 configuration: # 测试框架选择默认为 pytest testFramework: type: string default: pytest description: 使用的测试框架 (pytest, unittest) # 测试文件后缀 testFileSuffix: type: string default: _test.py description: 测试文件的后缀例如 _test.py 或 Test.py关键参数解释name: Skill 的唯一标识符在命令中会用到。triggers: 定义了如何触发这个 Skill。这里我们定义了一个类型为command的触发器意味着在 Claude Code 的命令面板中输入generate-unit-test即可触发。entryPoint: 指定当 Skill 被触发时Claude Code 应该执行哪个脚本文件。这里是main.py。configuration: 这里定义了一些用户可配置的选项。这些配置值可以在 Skill 脚本中读取使得 Skill 的行为更灵活。例如用户可以在 Claude Code 的设置中修改testFramework的默认值。3.2 实现核心逻辑main.py在同一个目录下创建main.py文件。这是 Skill 的大脑。#!/usr/bin/env python3 # main.py import os import sys import json import subprocess from pathlib import Path def main(): Skill 的主函数。Claude Code 会调用此函数。 它通过标准输入 (stdin) 接收上下文数据并通过标准输出 (stdout) 返回结果。 # 1. 读取 Claude Code 传递过来的上下文数据 input_data sys.stdin.read() if not input_data: print(json.dumps({error: 未接收到输入数据}), filesys.stderr) sys.exit(1) try: context json.loads(input_data) except json.JSONDecodeError as e: print(json.dumps({error: f输入数据 JSON 解析失败: {e}}), filesys.stderr) sys.exit(1) # 2. 从上下文中提取关键信息 # 这些字段名取决于 Claude Code 的 API通常是固定的或可查阅文档 current_file context.get(filePath) cursor_position context.get(cursorPosition, {}) # 可能包含 line, column file_content context.get(fileContent, ) # 获取 Skill 的配置参数 config context.get(configuration, {}) test_framework config.get(testFramework, pytest) test_suffix config.get(testFileSuffix, _test.py) if not current_file: print(json.dumps({error: 无法获取当前文件路径}), filesys.stderr) sys.exit(1) # 3. 解析当前文件找到光标所在的函数 # 这是一个简化的示例实际中可能需要更复杂的语法分析例如使用 ast 模块 target_function extract_function_at_cursor(file_content, cursor_position) if not target_function: print(json.dumps({error: 无法在光标位置识别到有效的函数定义}), filesys.stderr) sys.exit(1) # 4. 调用 Claude Code 的 AI 能力来生成测试代码模拟 # 在实际开发中这里可能会通过 HTTP 请求调用 Claude Code 的内部 API # 本例中我们模拟一个简单的基于规则的生成 generated_test_code generate_test_code(target_function, test_framework) # 5. 决定将生成的测试代码放在哪里 output_action decide_output_action(current_file, test_suffix, generated_test_code) # 6. 将结果以 Claude Code 期望的格式输出 result { action: output_action[type], content: output_action.get(content), filePath: output_action.get(filePath), message: f已为函数 {target_function.get(name)} 生成 {test_framework} 测试。 } print(json.dumps(result)) def extract_function_at_cursor(content, cursor_pos): 简化版的函数提取逻辑。实际项目应使用 ast 等库进行精确解析。 lines content.split(\n) line_num cursor_pos.get(line, 0) # 从光标行向上搜索找到以 def 开头的行 for i in range(line_num, -1, -1): if lines[i].strip().startswith(def ): func_line lines[i] # 非常简单的提取假设函数名后紧跟括号 import re match re.match(rdef\s(\w), func_line) if match: return { name: match.group(1), line: i, signature: func_line.strip() } return None def generate_test_code(func_info, framework): 根据函数信息和测试框架生成测试代码。 func_name func_info[name] if framework pytest: return fimport pytest def test_{func_name}(): Test for function {func_name}. # TODO: 编写具体的测试逻辑 # 示例: result {func_name}(...) # assert result expected_value raise NotImplementedError(测试用例待实现) elif framework unittest: return fimport unittest class Test{func_name.capitalize()}(unittest.TestCase): def test_{func_name}(self): Test for function {func_name}. # TODO: 编写具体的测试逻辑 # 示例: result {func_name}(...) # self.assertEqual(result, expected_value) self.fail(测试用例待实现) if __name__ __main__: unittest.main() else: return f# 测试框架 {framework} 暂不支持自动生成模板。 def decide_output_action(current_file_path, test_suffix, test_code): 决定输出行为插入当前文件还是创建新测试文件。 current_path Path(current_file_path) # 策略如果当前文件已经是测试文件以 _test.py 结尾则插入当前文件 if current_path.name.endswith(test_suffix): return { type: insert, content: test_code, position: endOfFile # 可以是 cursorPosition, endOfFile 等 } else: # 否则创建对应的测试文件 test_file_name current_path.stem test_suffix test_file_path current_path.parent / test_file_name return { type: createFile, filePath: str(test_file_path), content: test_code } if __name__ __main__: main()代码核心逻辑解读数据输入Skill 通过标准输入sys.stdin接收一个 JSON 字符串其中包含了 Claude Code 传递的完整上下文文件路径、内容、光标位置、配置等。上下文解析脚本解析 JSON提取出当前文件、光标位置和用户配置。这是 Skill 感知环境的依据。业务逻辑extract_function_at_cursor函数尝试从光标位置向上查找函数定义。这是一个简化实现生产级 Skill 应使用 Python 的ast抽象语法树模块进行精确解析。生成内容generate_test_code函数根据选择的测试框架pytest/unittest生成对应的测试代码模板。这里只是静态生成更强大的 Skill 可以在此处调用 Claude Code 的 AI API根据函数的具体实现动态生成更有针对性的测试用例。输出决策decide_output_action函数决定输出方式。如果当前文件已经是测试文件则将测试代码插入文件末尾否则创建一个新的测试文件。这体现了 Skill 的智能决策能力。结果返回最后脚本将一个包含action、content等字段的 JSON 对象打印到标准输出sys.stdout。Claude Code 会读取这个输出并根据action类型执行相应的操作如插入文本、创建文件。3.3 完善项目结构与依赖一个完整的 Skill 项目可能还需要其他文件。依赖管理 (requirements.txt)如果你的 Skill 需要第三方库例如requests用于调用外部 API需要在此声明。# requirements.txt # 本例中未使用外部库文件可为空或包含通用工具库 # requests2.28.0说明文档 (README.md)良好的文档对于 Skill 的分享和使用至关重要。# Unit Test Generator Skill 一个 Claude Code Skill用于自动生成 Python 函数的单元测试代码。 ## 功能 - 识别光标所在的 Python 函数。 - 支持 pytest 和 unittest 框架的测试模板。 - 智能判断并插入测试代码到当前文件或创建新的测试文件。 ## 使用方法 1. 将光标置于目标函数定义行内。 2. 在 Claude Code 中打开命令面板 (CtrlShiftP / CmdShiftP)。 3. 输入并执行命令 generate-unit-test。 ## 配置 在 Claude Code 设置中搜索 unit-test-generator可以修改 - testFramework: 选择测试框架 (pytest/unittest)。 - testFileSuffix: 指定测试文件的后缀。最终项目结构unit-test-generator/ ├── skill.yaml # Skill 元数据与触发器定义 ├── main.py # 核心执行逻辑 ├── requirements.txt # Python 依赖声明可选 └── README.md # 使用说明可选4. 安装、触发与使用 Skill创建好 Skill 项目后下一步就是将其安装到 Claude Code 中并验证其功能。4.1 安装 Skill 到 Claude CodeClaude Code 通常有两种安装 Skill 的方式本地路径安装和打包发布安装。对于开发阶段我们使用本地安装。找到 Skill 目录首先你需要确定 Claude Code 用于加载本地 Skill 的目录。这个目录通常位于用户配置文件夹下。你可以通过以下方式查找或确认在 Claude Code 的设置中搜索skill。查阅 Claude Code 的官方文档中关于“Skill Development”或“Local Skill”的部分。常见的路径有macOS/Linux:~/.claude-code/skills/或~/.config/Claude Code/skills/Windows:%APPDATA%\Claude Code\skills\或%USERPROFILE%\.claude-code\skills\创建符号链接或直接复制推荐使用符号链接软链接这样你在开发目录 (~/dev/claude-skills/unit-test-generator) 中的修改能实时生效。# macOS/Linux 示例 ln -s ~/dev/claude-skills/unit-test-generator ~/.claude-code/skills/unit-test-generator # Windows (PowerShell 管理员模式) 示例 # New-Item -ItemType SymbolicLink -Path $env:USERPROFILE\.claude-code\skills\unit-test-generator -Target C:\Users\YourName\dev\claude-skills\unit-test-generator如果无法创建符号链接也可以直接将整个unit-test-generator文件夹复制到上述 Skill 目录中。重启或重载 Claude Code安装后需要重启 Claude Code或者执行重载 Skill 的命令如果存在以使新 Skill 被加载。4.2 触发 Skill 的多种方式我们的skill.yaml中定义了一个command类型的触发器。这是最常用的一种方式。通过命令面板触发在 Claude Code 中打开一个 Python 文件将光标放在某个函数定义内部例如def calculate_sum(a, b):这一行。按下CtrlShiftP(Windows/Linux) 或CmdShiftP(macOS) 打开命令面板。输入generate-unit-test即我们在skill.yaml中定义的command值。从列表中选择该命令并执行。通过快捷键绑定可选为了提高效率你可以在 Claude Code 的键盘快捷键设置中为generate-unit-test命令分配一个快捷键。其他触发器类型除了commandSkill 还可以定义其他触发器例如comment: 当代码中出现特定格式的注释时触发如# skill-test。fileEvent: 当文件被保存、打开时触发。uiButton: 在 Claude Code 的 UI 中添加一个按钮来触发。 定义这些触发器需要在skill.yaml的triggers部分进行更详细的配置具体语法需参考 Claude Code 的官方 Skill 开发文档。4.3 验证 Skill 运行结果成功触发 Skill 后你应该能看到以下效果之一场景一创建新测试文件如果当前文件是math_utils.py且光标在calculate_sum函数上Skill 会在同一目录下创建一个名为math_utils_test.py的文件并包含生成的测试模板。场景二插入当前文件如果当前文件已经是math_utils_test.py则生成的测试代码会被插入到这个文件的末尾。你可以在 Claude Code 的“输出”面板Output中选择对应的 Skill 通道查看main.py脚本打印的日志和错误信息这对于调试至关重要。5. 常见问题排查与调试技巧开发和使用 Skill 过程中难免会遇到问题。以下是一些常见问题的排查路径。5.1 Skill 安装后未出现在命令面板问题现象可能原因检查方式处理建议在命令面板输入generate-unit-test找不到命令。1. Skill 目录不正确。2.skill.yaml文件格式错误。3. Claude Code 未加载 Skill。1. 确认skill.yaml文件在正确的 Skill 加载目录下。2. 使用 YAML 在线校验工具检查skill.yaml语法。3. 重启 Claude Code或在命令面板尝试运行Skills: Reload命令如果存在。1. 检查并修正 Skill 安装路径。2. 确保skill.yaml缩进正确关键字段name,triggers,entryPoint存在且有效。3. 查看 Claude Code 的开发者控制台Developer Tools是否有加载错误。5.2 Skill 触发后无反应或报错问题现象可能原因检查方式处理建议执行命令后编辑器没有任何变化也没有错误提示。1.main.py脚本执行出错但未捕获。2. Skill 输出格式不符合 Claude Code 预期。3. Python 环境或依赖问题。1.查看输出面板在 Claude Code 中打开“输出”Output面板在下拉列表中选择与你 Skill 名称相关的通道查看日志。2.手动测试脚本在终端中模拟 Claude Code 的输入调用你的main.py检查其输出。echo {filePath:test.py, cursorPosition:{line:5}} | python main.py3. 检查main.py是否有执行权限 (chmod x main.py)。1. 在main.py中增加更详细的错误捕获和日志输出print(json.dumps(...), filesys.stderr)。2. 确保脚本最后打印的 JSON 结果格式正确特别是action字段是 Claude Code 支持的类型。3. 确保用于运行 Skill 的 Python 解释器路径正确且安装了所有必需的依赖。5.3 Skill 逻辑不符合预期问题现象可能原因检查方式处理建议Skill 执行了但生成的测试代码位置不对或内容错误。1. 上下文数据解析错误。2. 业务逻辑函数如extract_function_at_cursor有 bug。3. 配置参数未正确读取。1. 在main.py开头打印接收到的完整contextJSON确认数据结构。2. 单独测试extract_function_at_cursor函数传入各种边界情况的content和cursor_pos。3. 打印config变量确认是否成功读取了用户设置。1. 根据打印的上下文调整解析逻辑。2. 使用更健壮的解析方式例如用ast模块替代简单的字符串搜索。3. 在skill.yaml和读取配置的代码中确保配置项的键名完全一致。5.4 性能与权限问题Skill 执行缓慢如果 Skill 需要调用网络 API 或执行复杂计算可能会阻塞编辑器。考虑将耗时操作异步化或提供进度提示。文件操作权限不足如果 Skill 需要写入系统目录或受保护的文件可能会因权限问题失败。确保 Skill 只在项目工作区内操作文件并做好异常处理try...except PermissionError。跨平台兼容性路径分隔符/vs\、命令行工具差异可能导致问题。在代码中使用pathlib.Path或os.path.join来处理路径避免硬编码。6. 进阶实践与最佳实践掌握了基础创建流程后你可以遵循以下最佳实践来构建更强大、更可靠的 Skill。6.1 设计可配置与可扩展的 Skill充分利用configuration将可能会变的选项如 API 密钥、默认行为、文件命名规则都设计为配置项让用户无需修改代码即可定制。参数化触发器让命令可以接受参数。例如generate-unit-test --frameworkunittest。这需要在skill.yaml的触发器定义和main.py的参数解析中做相应设计。模块化代码将核心逻辑如代码分析、AI 调用、文件操作拆分成独立的函数或类使main.py保持清晰便于单元测试和维护。6.2 提升 Skill 的智能与实用性集成 AI 能力我们的示例是静态生成模板。一个真正的“智能”测试生成器应该分析目标函数的签名、文档字符串甚至实现逻辑调用 Claude Code 的 API 来生成更具体、更合理的测试用例和断言。这通常需要向 Claude Code 的后端服务发送一个包含代码上下文的请求。错误处理与用户反馈对可能出错的地方如网络超时、解析失败、文件已存在进行妥善处理并通过 Claude Code 的消息提示或输出面板给用户清晰友好的反馈而不是让脚本静默失败。支持更多语言和框架将 Skill 从 Python 扩展到 JavaScript、Java、Go 等其他语言并支持这些语言生态中流行的测试框架如 Jest, JUnit。6.3 生产环境下的考量日志与监控为 Skill 添加详细的日志记录记录触发时间、输入上下文、执行结果和耗时。这对于排查线上问题和了解 Skill 使用情况非常重要。版本管理使用语义化版本控制SemVer来管理你的 Skill。在skill.yaml中更新version字段并在发布时提供更新日志。安全审计如果 Skill 会执行用户输入的代码、访问网络或文件系统必须进行严格的安全审查。避免命令注入、路径遍历等安全漏洞。不要执行未经校验的外部命令。性能优化避免在 Skill 中执行阻塞主线程的长时间操作。对于复杂任务可以考虑将其委托给后台进程或服务。从创建一个简单的单元测试生成器开始你已经走完了 Skill 开发的核心流程定义元数据、编写执行逻辑、处理上下文、输出结果。这个模式可以扩展到无数场景代码格式化、依赖检查、API 客户端生成、数据库迁移脚本创建、部署自动化等等。关键在于想清楚你想要自动化的工作流是什么然后利用 Claude Code 提供的上下文信息和 AI 能力将其封装成一个精准、高效的 Skill。开始构思你的下一个 Skill将重复性工作交给自动化让自己更专注于创造性的编码。
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
