🎯 学习目标

完成本章后，你将能够：

  • ✅ 理解 Skill 的本质：它是 Prompt 模板、脚本与上下文的组合体。
  • ✅ 熟练调用内置及社区技能，快速解决常见开发痛点。
  • ✅ 使用 skill-creator 或手动编写，定制符合个人/团队需求的专属技能。
  • ✅ 建立私有的 技能库，并在团队间安全地分享与版本管理。
  • ✅ 掌握技能调用的参数传递技巧，实现动态化执行。

8.1 Agent Skills 概述：什么是技能？

💡 核心定义

Skill (技能) 是 Claude Code 中一种预定义的、可复用的能力单元。
它不仅仅是一段简单的 Prompt，而是一个包含以下要素的完整包：

  1. 触发指令：如 /skill refactor-legacy。
  2. 系统提示词 (System Prompt)：针对特定任务优化的详细指令集（角色、约束、步骤）。
  3. 上下文预设：自动加载相关的文件或目录模式。
  4. 执行脚本 (可选)：关联的 Shell 脚本或工具链（如运行测试、格式化）。

🆚 Skill vs. 普通 Prompt vs. Hook

特性 普通 Prompt Hook (钩子) Skill (技能)
触发方式 自然语言描述 事件自动触发 (如文件保存) 命令式调用 (/skill <name>)
复用性 低 (每次需重新描述) 中 (固定逻辑) 极高 (一次定义，无限次调用)
复杂度 简单对话 系统级操作 复杂工作流 (多步推理 + 执行)
灵活性 高 (随意聊) 低 (死板) 中高 (支持参数化输入)
适用场景 临时问答、小修改 自动化 lint/test/backup 标准化任务 (重构、生成 boilerplate、代码审查)

🧩 技能的内部结构

一个典型的 Skill 通常由一个 Markdown 文件或 JSON 配置定义：

# skill-name.md
## Role
你是一名资深数据库架构师。

## Task
分析提供的 SQL 文件，找出性能瓶颈，并给出优化建议。

## Constraints
- 只关注 SELECT 语句。
- 必须解释索引缺失的原因。
- 输出格式为 Markdown 表格。

## Workflow
1. 读取目标文件。
2. 使用 EXPLAIN 模拟分析 (如果环境允许)。
3. 输出报告。

8.2 Skills 使用实例：调用现有技能解决具体问题

Claude Code 通常预置了一些基础技能，或者你可以从社区获取。以下是几个高频实战场景。

🚀 场景 1：一键代码审查 (/skill code-review)

痛点：每次提交前都要手动检查规范、潜在 Bug 和安全性。
操作：

# 假设当前修改了 src/auth.ts
/skill code-review --file src/auth.ts --focus "security, performance"

AI 行为：

  1. 自动读取 src/auth.ts。
  2. 加载“安全专家”人设 Prompt。
  3. 检查 SQL 注入、XSS、硬编码密钥等问题。
  4. 输出结构化报告，并直接给出修复后的代码块。

🏗️ 场景 2：样板代码生成 (/skill gen-crud)

痛点：每次新加一个实体，都要写 Controller, Service, Repository, DTO, Test，繁琐且易错。
操作：

/skill gen-crud --entity Product --fields "name:string, price:number, stock:int"

AI 行为：

  1. 解析参数 Product 和字段列表。
  2. 按照项目既定架构（如 NestJS 或 Spring Boot 风格），一次性生成 5-6 个文件。
  3. 自动注册路由。
  4. 生成对应的单元测试骨架。

🐞 场景 3：智能故障排查 (/skill debug-stack)

痛点：面对长长的报错堆栈，肉眼难以定位根源。
操作：

# 将错误日志粘贴到终端，或直接指向日志文件
/skill debug-stack --log logs/error.log --context src/

AI 行为：

  1. 解析堆栈跟踪，提取关键帧。
  2. 关联 src/ 下的相关源代码。
  3. 结合项目记忆中的历史 Bug 记录，推测最可能的原因。
  4. 提供“验证假设”的命令（如“运行这个特定的测试用例”）。

💡 提示：许多技能支持 Tab 补全。输入 /skill 后按 Tab，可以看到所有可用技能列表及其简短描述。

8.3 skill-creator 使用：自定义并创建新技能

当现有技能无法满足需求时，你需要创造自己的武器。Claude Code 提供了 skill-creator 向导或手动创建两种方式。

🛠️ 方法一：使用交互式向导 (skill-creator)

这是最适合新手的入门方式。

  1. 启动向导： 
    /skill-creator
  2. 回答引导问题：
    • 技能名称：refactor-to-typescript
    • 描述：将指定的 JS 文件重构为严格的 TS 文件，并生成类型定义。
    • 目标角色：TypeScript 专家。
    • 关键步骤：
      1. 分析 JS 代码推断类型。
      2. 添加接口定义。
      3. 替换 var/let 为强类型声明。
      4. 运行 tsc --noEmit 验证。
    • 所需权限：文件写入，命令执行。
  3. 自动生成：向导会在 .claude/skills/ 目录下生成配置文件和 Prompt 模板。
  4. 测试运行：立即尝试 /skill refactor-to-typescript --file src/old-utils.js。

📝 方法二：手动编写 (高级控制)

对于复杂技能，直接编辑文件更灵活。

步骤：

  1. 在 .claude/skills/ 目录下创建 my-skill-name.md (或 .json，视具体版本规范而定)。
  2. 编写内容：
---
name: api-mock-generator
description: 根据 Swagger/OpenAPI 文档生成 Mock 数据服务
version: 1.0
args:
  - name: spec_file
    required: true
    description: Path to the OpenAPI YAML/JSON file
  - name: output_dir
    required: false
    default: "./mocks"
    description: Output directory for mock files
---

# Role
你是一名后端测试专家，擅长使用 Faker 库生成逼真的 Mock 数据。

# Instructions
1. 读取 {{spec_file}} 中的 API 定义。
2. 识别所有 POST/GET 端点及其响应 Schema。
3. 在 {{output_dir}} 中为每个端点创建一个独立的 Mock 处理函数。
4. 确保生成的数据符合 Schema 类型约束（如邮箱格式、日期范围）。
5. 创建一个主入口文件 `index.js` 导出所有 Mock 服务。

# Constraints
- 必须使用 `faker` 库 v8+ 语法。
- 禁止硬编码任何真实用户数据。
- 如果 Schema 中有枚举值，Mock 数据必须从中随机选择。

# Output Format
先列出计划生成的文件列表，待用户确认后再生成代码。
  1. 保存并生效：无需重启，下次输入 /skill api-mock-generator 即可调用。

🔑 关键要素详解

  • Args (参数)：定义用户传入的变量，使用 {{variable_name}} 在 Prompt 中引用。
  • Constraints (约束)：明确禁止项，防止 AI 发挥过度。
  • Output Format (输出格式)：规范 AI 的回复结构，便于后续脚本解析或人类阅读。

8.4 技能库的管理与分享

随着技能越来越多，管理它们变得至关重要。同时，优秀的技能值得在团队内共享。

📂 本地管理策略

  • 目录结构： 
    .claude/skills/
├── core/             # 核心通用技能 (review, test, doc)
├── domain/           # 业务特定技能 (payment-flow, user-auth)
├── experimental/     # 试验中技能 (不稳定，慎用)
└── deprecated/       # 已废弃技能 (归档)
  • 命名规范：使用 kebab-case (如 gen-react-component)，保持动词开头，清晰表达意图。
  • 版本标记：在技能文件头部添加 version 字段，重大变更时升级版本号。

🤝 团队分享与协作

技能是团队知识沉淀的最佳载体。

  1. Git 同步：

    • 将 .claude/skills/ 目录提交到 Git 仓库。
    • 注意：确保技能文件中不包含硬编码的 API Key 或个人路径。使用环境变量或占位符。
    • 团队成员 git pull 后，立即拥有相同的 AI 能力集。

  2. 技能市场/注册表 (Registry)：

    • 对于开源社区或大型组织，可以建立一个中央仓库（如 GitHub Repo awesome-claude-skills）。
    • 使用 /skill install <github-url> (若插件支持) 或手动克隆到本地技能目录。

  3. 文档化：

    • 在项目 README.md 中开辟 “Available Skills” 章节。
    • 列出每个技能的名称、用途、参数示例。
    • 示例： 
      ## 🤖 Available AI Skills
- `/skill db-migrate`: 自动生成并审查数据库迁移脚本。
- `/skill i18n-extract`: 扫描代码提取翻译键并生成 JSON 文件。

🔄 技能的生命周期管理

  • 定期审计：每季度检查一次技能库，删除不再使用的技能，更新过时的 Prompt（如适配新框架版本）。
  • 反馈循环：鼓励团队成员在使用技能后提出改进建议（“这个技能生成的测试覆盖率不够”），持续迭代优化。

🧪 动手练习：构建你的第一个专属技能

练习 1：创建“注释生成器”

  1. 目标：创建一个技能，自动为选定的函数添加符合 JSDoc/TSDoc 规范的详细注释。
  2. 步骤：
    • 运行 /skill-creator 或手动创建 add-docs.md。
    • 定义参数 --file 和 --function-name。
    • 编写 Prompt：要求 AI 分析函数逻辑，提取参数含义、返回值类型、潜在异常，并生成标准文档块。
  3. 测试：找一个无注释的复杂函数，运行 /skill add-docs --file src/utils.js --function-name calculateTax。

练习 2：封装“遗留代码清洗”流程

  1. 背景：项目中有很多旧代码需要清理 console.log 和 debugger。
  2. 任务：
    • 创建一个技能 clean-legacy。
    • 集成多个步骤：搜索 -> 生成 Diff -> 运行 Lint -> 确认提交。
    • 加入约束：严禁删除生产环境需要的日志（如 Error 级别）。
  3. 验证：在测试文件上运行该技能，观察是否准确移除了调试代码而保留了关键日志。

练习 3：团队技能共享模拟

  1. 将你刚才创建的 add-docs 技能文件复制到一个共享文件夹（或新建分支）。
  2. 编写一段简短的使用说明（Usage Guide）。
  3. 想象你是 Team Lead，向组员演示如何通过拉取代码获得这个新能力。

❓ 常见陷阱与解答 (FAQ)

问题 原因分析 解决方案
技能无法识别参数 Prompt 中未正确使用 {{param}} 占位符，或参数名不匹配。 检查技能定义文件中的 args 列表与 Prompt 内容是否一致。
技能执行结果不稳定 Prompt 描述模糊，缺乏具体的 Few-Shot 示例。 在技能 Prompt 中加入 1-2 个完美的输入输出示例（Few-Shot Learning）。
技能冲突 两个技能名字相同，或触发条件重叠。 统一命名空间（如 feat-xxx, fix-xxx），定期清理重名技能。
上下文溢出 技能自动加载了过多文件作为上下文。 在技能定义中限制 context_files 的数量，或使用按需加载策略。

📝 本章小结

  • Skill 是能力的封装：它将复杂的 Prompt 工程和产品化思维结合，让 AI 操作标准化、自动化。
  • 创造即赋能：利用 skill-creator 或手动编写，你可以将个人经验转化为团队资产。
  • 管理即传承：通过 Git 共享技能库，让新员工入职第一天就拥有资深工程师的 AI 辅助能力。
  • 迭代即进化：技能不是一成不变的，需随项目发展和 AI 能力提升持续优化。

🚀 下一步预告：
拥有了强大的技能库后，我们将进入 第 9 章：插件生态，探索如何连接更广阔的外部世界，让 Claude Code 不仅能写代码，还能操作数据库、调用 API、控制浏览器，真正成为全能开发者！

# 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

基于SpringBoot+Vue的桂林旅游景点导游平台管理系统设计与实现【Java+MySQL+MyBatis完整源码】

avatar AtomGit开源社区
cover

【毕业设计】SpringBoot+Vue+MySQL 大创管理系统平台源码+数据库+论文+部署文档

avatar AtomGit开源社区
cover

Web在线考试系统信息管理系统源码-SpringBoot后端+Vue前端+MySQL【可直接运行】

avatar AtomGit开源社区