Skills 教程

Skills(技能)是 AI 编程工具(Claude Code、Codex 等)的扩展能力标准:把"知识 + 工具 + 流程"打包成可复用的技能包,让 AI 遇到对应任务时自动使用专业方法,输出稳定高质量的结果。

本教程内容

本教程从 Skills 的简介与基本结构讲起,系统覆盖:目录结构、SKILL.md 编写、脚本扩展、参数传递、触发机制、调试、上下文管理、测试、版本管理、发布与生态搭建等全部主题。

为什么需要 Skills

把团队经验固化为 AI 可执行的标准流程
让 AI 处理专业任务时"有章可循"
一次编写,处处复用,持续进化
降低 AI 输出的随机性,提升质量下限

学习路径

先理解 Skills 是什么与如何工作,再动手写第一个 Skill;随后学习调试与测试保证质量;最后掌握发布与生态,把技能分享给团队或社区。

适用人群

AI 工具重度用户、希望团队规范使用 AI 的技术负责人、以及想构建 AI 技能生态的开发者。

Skills 简介

Skills 是 Anthropic 提出并推广的 AI 技能标准,被 Claude Code、Codex 等主流 AI 编程工具支持。它的核心思想:用标准化的方式给 AI"安装专业能力"。

Skills 是什么

一个 Skill 是一组文件:SKILL.md(技能说明文档,含触发条件与操作步骤)、scripts(自动化脚本)、references(参考资料)。AI 在任务匹配时自动加载并遵循其中指引。

与传统 prompt 的区别

维度	传统 prompt	Skills
形式	对话中临时粘贴	标准化文件,自动加载
复用	每次复制	一次安装,处处生效
触发	手动指定	按描述自动匹配
管理	零散	版本化、可分发
扩展	仅文本	可带脚本与参考文档

典型 Skills 示例

Python 打包发布技能
代码安全审查技能
Docker 运维排查技能
API 文档生成技能
数据库迁移规范技能

生态现状

Anthropic 官方开源了 skills 仓库(含 skill-creator 等示例),社区涌现了大量共享技能。多数 AI 编程工具已原生支持 Skills 目录约定。

核心价值

Skills 让"AI 的专业能力"变得:可积累(经验沉淀)、可复制(团队共享)、可进化(持续迭代)。这是 AI 辅助开发从"个人技巧"走向"组织资产"的关键一步。

Skills 基本结构

一个 Skill 的目录结构非常简洁,核心只有一个 SKILL.md 文件,可选配脚本与参考资料。本节介绍基本结构。

最小结构

my-skill/
└── SKILL.md          # 技能定义(必需)

完整结构

my-skill/
├── SKILL.md              # 技能说明:触发条件 + 使用步骤(必需)
├── scripts/              # 辅助脚本(可选)
│   ├── setup.sh          # 环境准备
│   └── run.sh            # 主流程脚本
└── references/           # 参考资料(可选)
    ├── guide.md          # 详细指南
    └── common-errors.md  # 常见错误与排查

SKILL.md 是核心

SKILL.md 是 AI 读取的主文件,包含两部分:

---
name: my-skill
description: 技能用途与触发条件的描述(自动匹配依据)
---

# 使用步骤
(正文:具体可执行的步骤、命令、检查点)

frontmatter 元数据

---
name: my-skill            # 技能名(必填)
description: |            # 触发描述(必填)
  一句话说明用途与触发场景。
version: 1.0.0            # 版本号
license: MIT              # 许可协议
metadata:                 # 可选元数据
  tags: [开发, 测试]
  author: your-name
---

脚本与参考的作用

scripts:把可自动化的部分做成脚本,AI 直接调用,减少手动步骤出错
references:存放长文档,SKILL.md 保持精简,需要时 AI 再读取

目录放置位置

~/.claude/skills/         # 用户级(所有项目可用)
.claude/skills/           # 项目级(团队共享,入库)
/etc/claude-code/skills/  # 企业级(强制下发)

基本结构就这么简单:一个 SKILL.md 就能起步,脚本与参考资料按需添加。下一节看完整目录结构约定。

Skills 目录结构

虽然最小结构只需一个文件,但遵循完整目录约定能让技能更规范、更易维护。本节详解 Skills 的目录规范。

标准目录树

skill-name/
├── SKILL.md                # 必选:技能定义
├── scripts/                # 可选:自动化脚本
│   ├── install.sh          # 安装/环境准备(命名约定: install.*）
│   ├── run.sh              # 主执行脚本
│   └── helper.py           # 辅助脚本
├── references/             # 可选:参考文档
│   ├── overview.md
│   ├── FAQ.md
│   └── errors.md
├── tests/                  # 可选:测试脚本
│   └── test_skill.sh
├── README.md               # 可选:给人类看的说明
├── LICENSE                 # 可选:许可协议
└── .gitignore              # 可选

文件命名约定

# scripts 目录推荐命名
install.*      # 环境准备(自动运行)
run.*          # 主流程入口
check.*        # 校验/检查
parse.*        # 数据解析

# references 命名随意,md 为宜
# 文件名用 kebab-case 或 snake_case

分层放置原则

用户级 ~/.claude/skills/        # 个人技能,所有项目生效
项目级 .claude/skills/          # 团队技能,随仓库分发
企业级 /etc/claude-code/skills/ # 强制技能,不可覆盖

技能内文件规范

SKILL.md 保持精简(1-3 屏),详细内容放 references
脚本幂等可重复执行,失败有明确输出
引用文件用相对路径,技能可整体移动
不包含敏感信息(密钥、内网地址)

仓库组织建议

# 多技能仓库结构
skills-repo/
├── skills/
│   ├── python-packaging/
│   ├── docker-ops/
│   └── api-testing/
├── README.md
└── .gitignore

统一的目录约定让技能"长得一样",团队维护成本大幅降低。下一个 Skill 从模板开始,保持结构一致。

第一个 Skill

本节手把手创建你的第一个 Skill:"代码审查技能"。完成后你就掌握了创建技能的全部流程。

步骤1:创建目录

mkdir -p ~/.claude/skills/code-review
cd ~/.claude/skills/code-review

步骤2:编写 SKILL.md

# ~/.claude/skills/code-review/SKILL.md
---
name: code-review
description: >
  审查代码质量与安全性。当用户要求"审查代码""检查
  安全问题""review diff"或希望评估代码时使用。
  输出带严重程度的问题清单,不修改代码。
---

# 代码审查流程
1. 获取待审查的代码(diff 或文件)
2. 按以下维度逐项检查:
   - 安全性:注入、越权、敏感信息泄露
   - 正确性:边界条件、空值处理、并发问题
   - 性能:复杂度、资源泄漏、不必要的重复计算
   - 可维护性:命名、注释、代码结构
3. 输出 markdown 报告:
   - 严重问题(阻塞合并)| 文件:行号 | 描述 | 建议
   - 一般问题
   - 改进建议

## 规则
- 只审查,不修改代码
- 每条问题给出定位(文件:行号)
- 不确定的问题标注"需确认"

步骤3:测试技能

# 在任意项目目录启动 claude
claude

# 触发技能
> 审查这个项目最近提交的代码

# 观察:技能是否自动加载并遵循流程

步骤4:验证触发描述

# 换不同的说法测试触发
> 帮我 review 一下代码
> 检查这段代码有没有安全问题
> 评估一下我的代码质量

步骤5:迭代优化

# 根据实测效果调整:
# - description 更精准(触发不准时)
# - 步骤更具体(输出不满意时)
# - 补充 references/common-errors.md

完成标准

[ ] 技能目录与 SKILL.md 就位
[ ] 触发描述有效(多种说法都能触发)
[ ] 输出符合预期的审查报告
[ ] 技能可复用(换项目依然生效)

恭喜!你拥有了第一个 Skill。从"一条好提示词"到"一个 Skill",区别就是:结构化、可复用、可分享。

VS Code Skills

VS Code 生态中也可以使用 Skills:通过 Claude Code 扩展、或把技能接入 VS Code 的 AI 助手,在编辑器内获得专业技能支持。

接入方式

Claude Code 扩展:VS Code 中安装 Claude Code 扩展后,Skills 目录约定直接生效
GitHub Copilot 自定义指令:通过 .github/instructions 类似机制(功能对等物)
Cursor Rules:Cursor 的 .cursor/rules 是类似的技能概念

在 VS Code 中使用

# 1. 安装 Claude Code 扩展
code --install-extension anthropic.claude-code

# 2. 创建技能目录(项目级)
mkdir -p .claude/skills/my-skill
# 编写 SKILL.md...

# 3. 打开对话面板使用
# 对话中自然触发,或手动指定技能名

VS Code 场景的典型技能

代码审查:选中代码 → 技能输出审查意见
测试生成:为当前文件生成单元测试
重构助手:按规范重构选中代码
错误解释:解释报错并给出修复方案

与编辑器功能的结合

# 技能内可以指示 AI 使用编辑器能力
# SKILL.md 中可以写:
# - 使用差异预览展示修改
# - 修改后运行语言服务的诊断
# - 用 Problem 面板展示问题

Cursor 的对应机制

# Cursor 使用 .cursor/rules/*.mdc
# 结构与 SKILL.md 类似:描述 + 规则
# 如果团队跨工具,可写一套规则两种格式

最佳实践

编辑器内用小而专的技能(聚焦单文件操作)
整仓级任务技能放终端用,编辑器内聚焦局部
团队共享:技能目录入库,新人拉取即用

VS Code 是许多开发者的主战场,把 Skills 接入编辑器,让"专业技能"在写代码的地方直接可用。

Skills 工作原理

理解 Skills 的工作机制,能帮助你写出"真正被触发、真正有效"的技能。本节拆解 AI 加载与执行技能的过程。

工作流程

用户任务输入
   ↓
① 扫描技能目录(用户级 + 项目级 + 企业级)
   ↓
② 读取每个 SKILL.md 的 description
   ↓
③ 语义匹配:任务与技能描述的相关度评分
   ↓
④ 加载匹配技能(通常 top 1-3 个)
   ↓
⑤ AI 按 SKILL.md 的步骤执行
   ↓
⑥ 需要时读取 scripts / references
   ↓
完成

匹配机制

基于语义相似度,而非关键词精确匹配
description 写得越贴近真实任务表述,匹配越准
多个技能匹配时,AI 选择最相关的(或组合使用)
用户也可以显式指定技能名强制使用

描述的重要性

# 差的描述(匹配不准)
description: 处理代码

# 好的描述(精准触发)
description: >
  审查代码质量与安全性。当用户要求审查代码、
  检查安全问题、review diff 时使用。
  输出带严重程度的问题清单,不修改代码。

执行时 AI 的行为

按 SKILL.md 的步骤顺序执行
步骤中的命令会被真实执行(Bash 工具)
references 中的文档按需读取
脚本可被调用以减少手动步骤

技能冲突处理

# 多个技能都想用怎么办?
# 1. description 越具体,匹配优先级越高
# 2. AI 会综合判断,选择最贴合的
# 3. 关键任务可显式指定
> 使用 code-review 技能审查这段代码

调试匹配

# 观察技能是否加载
claude --debug "触发技能的任务"
# 日志中会显示技能扫描与加载过程

一句话总结工作原理:技能 = 可检索的执行手册。AI 通过 description 找到手册,按 SKILL.md 的指引执行,需要时调用脚本与参考文档。

使用现有 Skills

很多优秀技能已经开源,直接安装使用比自己从零写更快。本节介绍获取、安装与管理现有技能的方法。

官方技能集合

# Anthropic 官方 skills 仓库
git clone https://github.com/anthropics/skills ~/.claude/skills/anthropics

# 包含:
# - skill-creator: 技能创建器(推荐先看)
# - artifacts-builder: 前端组件构建
# - document-auditor: 文档审查
# - ... 更多

社区技能仓库

# GitHub 搜索 "claude skills" 或 "agent skills"
# 流行的社区集合:
# - obra/superpowers(技能合集,见后文章节)
# - 各 AI 工具官方技能库

# 安装方式基本都是 git clone 到技能目录

安装后验证

# 1. 检查目录
ls ~/.claude/skills/
# 2. 查看技能说明
cat ~/.claude/skills/anthropics/skill-creator/SKILL.md
# 3. 实测触发
claude "使用 skill-creator 创建技能"

技能管理规范

# 目录命名带来源,便于管理
~/.claude/skills/
├── anthropics/          # 官方
├── community/           # 社区
└── my-team/             # 团队自制

# 或每个技能独立目录
~/.claude/skills/skill-creator/
~/.claude/skills/code-review/

选择技能的要点

看维护活跃度:最近有提交
看 description 质量:触发描述是否清晰
看 references 丰富度:文档是否完善
看许可证:是否允许商用/修改
先小范围试用,再决定是否推广

更新与卸载

# 更新:git pull 重新拉取
cd ~/.claude/skills/anthropics && git pull

# 卸载:删除目录即可
rm -rf ~/.claude/skills/community/old-skill

使用现成技能的正确姿势:先看 skill-creator 学规范 → 装几个高频技能试用 → 按需改造 → 沉淀自己的版本。

SKILL.md 文件

SKILL.md 是技能的灵魂,AI 主要依据它执行任务。本节详解 SKILL.md 的完整格式与编写要点。

文件格式

---
YAML frontmatter(元数据)
---

Markdown 正文(操作步骤)

frontmatter 字段详解

---
name: skill-name            # 必填:技能名(目录名建议一致)
description: |              # 必填:触发描述(自动匹配依据)
  技能用途、触发场景、输出特点。
  写 2-5 句,覆盖常见触发说法。
version: 1.0.0              # 版本号(可选,建议)
license: MIT                # 许可(可选)
metadata:                   # 可选
  tags: [python, 打包]      # 标签
  author: xxx               # 作者
  homepage: https://...     # 主页
---

正文结构建议

# 技能名(标题)
一句话概述技能作用。

## 使用场景
- 场景A
- 场景B

## 使用步骤
1. 第一步(含具体命令)
2. 第二步
3. 验证步骤

## 规则与约束
- 必须遵守的规则
- 禁止事项

## 常见问题
- 问题与解法(或引导到 references)

正文编写要点

步骤要"可执行":含具体命令、文件路径、检查点
命令要真实:AI 会真的执行,写错会失败
用中文或英文均可,但全篇语言一致
控制在 1-3 屏:详细内容放 references

示例片段

## 使用步骤
1. 检查项目根目录是否有 pyproject.toml
   - 没有则提示用户先初始化
2. 运行 `python -m build` 构建
   - 失败时检查:是否安装 build 包(pip install build)
3. 检查 dist/ 下产物
   - wheel 与 sdist 都存在,且文件名包含版本号
4. 输出构建报告与发布建议

## 禁止
- 不修改 pyproject.toml 中的依赖版本
- 不直接执行 twine upload(需用户确认)

常见错误

description 太泛("处理代码")→ 匹配不准
步骤含糊("做好配置")→ AI 无从执行
命令过时/错误 → 执行失败
内容过长 → 关键信息被稀释

写 SKILL.md 的心法:把它当成"给新同事的操作手册"——详细、具体、可验证。

Skills 描述

description(描述)是技能自动触发机制的关键:AI 通过它判断"这个任务是否该用这个技能"。写好描述,技能才"能被找到"。

描述的作用

用户任务 → AI 读取各技能 description → 语义匹配 → 加载

# description 决定:
# - 技能能否被正确触发(匹配准)
# - 是否被误触发(过度触发/漏触发)

好描述的结构

description: >
  用途(一句话)。
  触发场景(用户可能怎么说)。
  输出特点(会产出什么)。

# 示例
description: >
  审查代码质量与安全性。当用户要求审查代码、
  检查安全问题、review diff、评估代码质量时使用。
  输出带严重程度的问题清单,不修改代码。

覆盖常见触发说法

# 审查类技能的常见说法
- "审查代码" "review" "检查安全"
- "看看这段代码有什么问题"
- "评估代码质量"

# 把高频说法都写进 description,提高命中率

描述质量对比

# ❌ 太泛:几乎任何任务都可能误匹配
description: 处理代码任务

# ❌ 太窄:换个说法就触发不了
description: 当用户说"code review"三个英文单词时使用

# ✅ 平衡
description: >
  审查代码质量与安全性。当用户要求审查、review、
  检查代码问题、评估安全性时使用。输出问题清单,
  只审查不修改。

描述中的关键信息

做什么(用途)
什么时候用(触发场景)
输出什么(产出物)
不做什么(边界,防误用)

迭代优化描述

# 实测触发情况
claude "试试各种说法触发技能"
# 发现触发不准 → 调整 description

# 用日志验证
claude --debug "任务" | grep -i skill

描述是技能的"门面"与"索引"。写描述时站在用户角度想:"用户会怎么说出这个需求?"把这些说法都覆盖进去。

Skills 脚本扩展

脚本扩展让技能从"纯文档"升级为"可执行工具":把确定性逻辑封装成脚本,AI 调用脚本获得稳定结果,减少手动步骤与出错。

为什么需要脚本

复杂逻辑用代码表达更可靠(正则、解析、计算)
流程步骤可重复,脚本保证一致性
AI 手动执行多步命令容易出错,脚本一步到位
脚本可被测试,质量可控

脚本目录规范

my-skill/
├── SKILL.md
└── scripts/
    ├── install.sh    # 环境准备(约定名)
    ├── run.sh        # 主流程
    ├── check.py      # 校验
    └── parse.py      # 解析

SKILL.md 中调用脚本

# SKILL.md 正文
## 使用步骤
1. 运行环境准备脚本:
   bash scripts/install.sh
2. 解析输入数据:
   python scripts/parse.py --input <file>
3. 执行主流程:
   bash scripts/run.sh
4. 校验结果:
   python scripts/check.py --output dist/

脚本编写要点

#!/usr/bin/env bash
set -euo pipefail   # 严格模式,失败即停

# 脚本要素:
# 1. 参数校验
# 2. 清晰输出(成功/失败信息)
# 3. 非零退出码表示失败
# 4. 幂等:重复执行结果一致
echo "开始处理..."
# ... 业务逻辑
echo "完成: 产出文件在 $OUTPUT_DIR"

语言选择

# Bash:简单流程、文件操作
# Python:数据处理、复杂逻辑
# Node:前端生态相关
# 选团队最熟悉、环境最通用的语言

错误处理

# 脚本失败时,AI 应能看到清晰错误
echo "错误: 输入文件不存在" >&2
exit 1

# SKILL.md 中说明:
# 脚本失败时,检查 stderr 输出,按 references/errors.md 排查

安全注意

脚本不包含密钥与敏感信息
脚本路径用相对路径(技能可移动)
外部输入做校验,防注入

脚本扩展的正确姿势:文档写"做什么",脚本做"怎么做"。确定性的操作尽量脚本化,AI 专注于判断与决策。

Skills 参数传递与接收

技能在执行时需要接收用户输入与上下文参数。本节介绍技能中参数的传递方式与使用规范。

参数的来源

# 技能执行时的参数来源:
# 1. 用户任务描述中的信息
# 2. 技能目录中的文件(脚本、参考)
# 3. 环境变量
# 4. AI 在执行中收集的信息(文件内容、命令输出)

SKILL.md 中的参数约定

# SKILL.md 中声明参数
---
name: api-testing
description: 接口测试技能
---

# 参数
- target: 待测试的接口地址或文件
- method: 请求方法(GET/POST/PUT/DELETE)
- env: 测试环境(dev/staging/prod)

# 使用步骤
1. 确认参数:
   - target 为空则询问用户
   - env 默认 dev
2. 按参数执行测试...

脚本接收参数

# scripts/run.sh 接收位置参数
#!/usr/bin/env bash
TARGET="${1:?目标参数缺失}"
METHOD="${2:-GET}"
ENV="${3:-dev}"

echo "测试 $ENV 环境的 $METHOD $TARGET"
# 执行业务逻辑

# SKILL.md 中调用
bash scripts/run.sh "$TARGET" "$METHOD" "$ENV"

Python 脚本参数

# scripts/analyze.py
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--input", required=True, help="输入文件")
parser.add_argument("--format", default="md", help="输出格式")
args = parser.parse_args()

print(f"分析 {args.input}, 输出格式: {args.format}")

# 调用
python scripts/analyze.py --input "$FILE" --format md

参数校验

# SKILL.md 中说明校验规则
## 参数校验
- target 必填,且需是存在的文件或合法 URL
- method 必须是 HTTP 标准方法
- env 只能是 dev/staging/prod
- 不满足时,询问用户或使用默认值

上下文传递

# 技能之间/步骤之间传递数据
# 约定:中间产物写入 .skill-tmp/ 目录
# 或通过环境变量传递
export CURRENT_TARGET="$TARGET"
bash scripts/run.sh

# SKILL.md 说明:
# 中间文件放在 .skill-tmp/,结束后清理

最佳实践

参数声明清晰:名称、含义、默认值、必填性
脚本校验参数并给出友好错误
敏感参数(密钥)用环境变量,不落文件
复杂参数让 AI 从文件读取,而非命令行传

参数设计是技能可用性的关键:参数清晰、校验完善、默认合理,技能才能在各种输入下稳定工作。

Skills 触发机制

触发机制决定技能"何时被使用"。理解触发规则,能让你的技能在该出现时出现、不该出现时隐身。

触发方式总览

方式	说明
自动匹配	任务描述与 description 语义匹配,自动加载
显式指定	用户直接说"使用 xx 技能"
关键词	描述中的明确关键词命中(匹配机制之一)
组合触发	多个技能同时加载,协同工作

自动匹配详解

# AI 的匹配逻辑(简化)
1. 读取所有技能 description
2. 将用户任务与每个 description 做语义相似度计算
3. 超过阈值的技能进入候选
4. 选择最相关的(可能多个)加载

# 影响匹配的因素:
# - description 的措辞与任务措辞的相似度
# - 技能数量(越多,单个被选概率越低)
# - 阈值设置(部分工具可调)

显式触发

# 用户明确指定(最可靠)
> 使用 code-review 技能审查这段代码
> 用 python-packaging 技能做发布检查
> /review        # 斜杠命令方式(绑定技能)

# SKILL.md 中建议说明:
# 用户也可以直接说技能名触发

关键词设计

# description 中自然包含关键词
description: >
  审查代码质量与安全性。当用户要求"审查代码"、
  "检查安全"、"review"、"评估质量"时使用。

# 关键词帮助快速匹配,但不要堆砌
# 语义匹配能理解同义表达,关键词是辅助

避免误触发

# 描述中明确"不做"的边界
description: >
  ... 只审查,不修改代码。不适用于格式整理、文档生成。

# 或设置更高的使用门槛
# 关键技能在步骤开头要求确认:
## 使用前
- 确认用户确实需要审查,而非其他操作

调试触发

# 验证触发
claude --debug "任务描述"
# 日志中查看:扫描了哪些技能、是否加载、加载了哪个

# 常见问题:
# - 没触发 → description 措辞不符,优化描述
# - 误触发 → 边界写清楚,加限制条件
# - 优先级低 → 描述更具体,缩小范围

触发机制是技能生态的"调度器"。目标:让 90% 的正确场景自动触发,10% 靠显式指定兜底。

Skills skill-creator

skill-creator 是 Anthropic 官方提供的技能创建器:引导你规范地创建技能,确保结构、描述与内容都符合最佳实践。

skill-creator 是什么

它本身也是一个 Skill(在官方 skills 仓库中),同时定义了"如何写技能"的标准。使用它创建技能,等于有一位导师帮你把好质量关。

获取

git clone https://github.com/anthropics/skills ~/.claude/skills/anthropics

# skill-creator 位于:
~/.claude/skills/anthropics/skill-creator/

使用方式

# 在任意项目启动 claude
claude

# 让 skill-creator 帮你创建技能
> 使用 skill-creator 技能,创建一个用于
> "排查 Docker 容器问题"的技能 docker-debug

skill-creator 会做什么

1. 创建技能目录结构
2. 生成 SKILL.md 模板
3. 引导完善:
   - name: 技能名
   - description: 触发描述(反复打磨)
   - 使用步骤:具体可执行
   - 常见问题:沉淀到 references
4. 检查清单确认:
   - 描述是否清晰?
   - 步骤是否可执行?
   - 是否有验证点?
   - 是否单一职责?
5. 生成最终文件

它生成的质量标准

# 优秀技能的 5 个特征
1. description 精准:一句话说清用途与触发
2. 步骤可执行:每步有具体操作与命令
3. 有验证点:知道何时算完成
4. 边界明确:知道不做什么
5. 有参考资料:常见问题有据可查

批量创建

> 使用 skill-creator 依次创建三个技能:
> 1. db-migration: 数据库迁移规范
> 2. api-testing: 接口测试流程
> 3. release-check: 发版前检查清单

配合审查

# 创建后自查
> 审查我刚刚创建的技能,对照 skill-creator 的质量标准,
> 指出需要改进的地方

skill-creator 的价值:让团队技能"长得一样、质量一致"。新技能一律用它生成,是技能库质量管理的起点。

Skills 调试

技能不生效、行为不对时,需要系统化调试。本节介绍技能调试的完整方法。

常见症状与原因

症状	可能原因
技能没被加载	目录位置不对 / description 不匹配 / 文件格式错误
加载了但不执行步骤	SKILL.md 步骤含糊 / 被其他指令覆盖
步骤执行出错	命令错误 / 脚本 bug / 环境缺失
输出不符合预期	描述与目标偏差 / 参考资料不完整

调试流程

# 步骤1:确认技能位置与格式
ls ~/.claude/skills/my-skill/
cat ~/.claude/skills/my-skill/SKILL.md | head -20
# - frontmatter 是否完整(name/description)
# - YAML 是否有语法错误(引号、缩进)

# 步骤2:验证能被扫描到
claude --debug "触发技能的任务" 2>&1 | grep -i skill

# 步骤3:检查加载与执行
# 观察 debug 输出中的:
# - skill scan: 扫描到的技能列表
# - skill load: 实际加载的技能
# - 执行日志

验证描述匹配

# 用不同说法测试触发
> 任务A(标准说法)
> 任务B(同义说法)
> 任务C(边缘说法)
# 记录哪些能触发,针对性优化 description

脚本调试

# 单独运行脚本排查
bash -x scripts/run.sh      # 跟踪执行
python scripts/analyze.py --debug

# 检查脚本权限
ls -l scripts/*.sh          # 需要 +x 或 bash 调用

# 检查依赖
which python3 node
python3 -c "import 依赖"

日志分析

# AI 工具日志位置(以 Claude Code 为例)
~/.claude/logs/
tail -f ~/.claude/logs/*.log | grep -iE "skill|error"

# 关键日志内容:
# - 技能扫描路径
# - 加载了哪些技能
# - 脚本执行输出与退出码

最小复现法

# 把技能简化到最小,逐步加回
# 1. 只留 SKILL.md(去掉脚本/参考)
# 2. 简化步骤为 1-2 条
# 3. 用最简单的任务触发
# 4. 确认生效后逐步加回复杂度

常见坑

frontmatter 缺少必填字段(description)
YAML 语法错误(冒号后没空格、引号不配对)
脚本没有执行权限
相对路径在技能移动后失效
description 与内容不一致

调试技能的关键:先确认"是否被加载",再排查"执行是否成功",最后优化"结果是否满意"。三步定位,不瞎猜。

Skills 输入/输出

技能的输入输出设计决定了它的可用性与可组合性。本节介绍技能的输入来源、输出形式与规范化建议。

输入来源

# 技能的输入可以来自:
1. 用户任务描述(主要)
2. 文件内容(读取指定文件)
3. 命令输出(运行命令获取)
4. 环境变量(配置参数)
5. 其他技能的输出(组合使用)

SKILL.md 中声明输入

# SKILL.md
---
name: log-analyzer
description: 分析日志文件,提取错误与趋势
---

# 输入
- log_file: 日志文件路径(必填)
- pattern: 过滤模式(默认 ERROR|Exception)
- since: 起始时间(可选)

# 使用步骤
1. 校验 log_file 存在且可读
2. 读取文件,按 pattern 过滤
3. 统计错误类型与频率
4. 输出分析报告

输出形式

# 输出的常见形式:
1. 对话回复(Markdown 报告)
2. 文件产出(报告、转换结果)
3. 脚本输出(结构化数据)
4. 修改后的代码/文件

# SKILL.md 中说明输出位置与格式:
## 输出
- 报告输出到 reports/ 目录,文件名带时间戳
- 控制台输出总结(不超过 20 行)
- 详细数据写入 JSON 文件

结构化输出(脚本)

# scripts/analyze.py 输出 JSON
import json, sys

result = {
    "total_errors": 12,
    "top_errors": [{"type": "TimeoutError", "count": 5}],
}
print(json.dumps(result))

# 调用方(AI)解析 JSON 生成报告
# 结构化中间数据便于组合与测试

输出规范

# SKILL.md 中的输出约定示例
## 输出规范
- 报告格式: Markdown,含摘要与详情
- 摘要: 3-5 行结论
- 详情: 表格/列表,含定位信息
- 状态: 明确"完成/部分完成/失败"

组合时的输入输出契约

# 技能A 输出 → 技能B 输入
# 约定:中间数据落文件 + 声明格式
# A 输出: analysis_result.json
# B 输入: --input analysis_result.json

# SKILL.md 中写明接口:
## 与其他技能协作
- 输出 JSON 到 .skill-tmp/result.json
- 格式: {"errors": [...], "summary": "..."}

最佳实践

输入输出都要在 SKILL.md 中声明清楚
输出带状态标识(成功/失败/部分)
数据类输出用结构化格式(JSON)
人读类输出用 Markdown,简洁有重点

输入输出契约是技能"可组合"的前提。声明清楚、格式稳定,技能才能像积木一样拼接使用。

Skills 错误处理与容错

健壮的技能必须考虑错误场景:输入不合法、命令失败、环境缺失等。本节介绍技能的错误处理与容错设计。

错误类型

# 技能执行中的常见错误:
1. 输入错误:文件不存在、参数非法
2. 环境错误:命令缺失、依赖未装
3. 执行错误:脚本失败、命令超时
4. 业务错误:数据异常、校验不通过

SKILL.md 中的错误处理指引

# SKILL.md 增加错误处理章节
## 错误处理
- 输入文件不存在: 提示用户并提供搜索建议
- 命令缺失: 提示安装方式(build 缺失时 pip install build)
- 脚本失败: 查看 stderr,按 references/errors.md 排查
- 未知错误: 停止并报告,不擅自回退

脚本容错设计

#!/usr/bin/env bash
set -euo pipefail    # 严格模式:任何失败立即退出

INPUT="${1:-}"
if [[ -z "$INPUT" ]]; then
    echo "错误: 缺少输入参数" >&2
    exit 1
fi

if [[ ! -f "$INPUT" ]]; then
    echo "错误: 文件 $INPUT 不存在" >&2
    exit 2
fi

# 正常逻辑
echo "处理 $INPUT ..."

重试与降级

# SKILL.md 中的容错策略
## 容错策略
- 网络请求失败: 重试 3 次,指数退避(1s/2s/4s)
- 构建失败: 检查依赖后重试 1 次
- 部分数据异常: 跳过并记录,继续处理
- 关键步骤失败: 停止,输出已完成的中间结果

# 脚本内实现重试
for attempt in 1 2 3; do
    if curl -s -f "$URL"; then
        break
    fi
    echo "第 $attempt 次失败,重试..." >&2
    sleep $((attempt * 2))
done

错误信息规范

# 好的错误信息:
# - 说明发生了什么
# - 说明原因(可能)
# - 给出解决建议
echo "错误: 无法连接数据库(连接超时)。请检查 DB_HOST 配置。" >&2

# 退出码规范(脚本)
0    成功
1    通用错误
2    输入参数错误
3    依赖/环境错误
4    业务校验失败

兜底行为

# SKILL.md 明确"失败时怎么办"
## 失败兜底
- 技能无法完成时,明确告知用户原因
- 提供部分结果(如果有)
- 建议替代方案(如果有)
- 不假装成功,不生成误导性结果

测试错误路径

# 测试用例
- 空输入 / 缺失文件
- 非法参数
- 依赖缺失
- 网络失败
- 超大输入
# 每个场景都验证:错误信息清晰、不崩溃、可恢复

容错设计的核心:失败要"说得清、退得稳、不装成功"。错误处理写进 SKILL.md,脚本给足错误信息,技能才算健壮。

Skills 上下文

技能在上下文中运行:它需要理解任务背景,同时也要高效利用有限的上下文空间。本节介绍技能上下文的设计与管理。

技能感知的上下文

# 技能执行时可用的上下文:
1. 用户任务描述
2. 当前项目信息(目录、文件)
3. SKILL.md 内容(已加载)
4. references 文档(按需读取)
5. 对话历史(当前会话)
6. 环境信息(操作系统、工具版本)

上下文组织原则

# 1. 分层:SKILL.md 精简,细节放 references
SKILL.md        # 核心步骤(1-3 屏)
references/*.md # 详细文档(按需加载)

# 2. 按需:AI 只在需要时读取 references
# SKILL.md 中说明何时读什么:
## 参考资料
- 常见错误排查: 先读 references/errors.md
- 完整规范: 处理复杂场景时读 references/spec.md

上下文示例

# SKILL.md 中说明所需上下文
---
name: migration-review
description: 审查数据库迁移脚本
---

# 所需上下文
- 迁移文件列表(通过 glob 获取)
- 数据库 schema 当前状态
- 项目使用的 ORM 与迁移工具

# 使用步骤
1. 获取迁移文件: glob "migrations/*"
2. 读取最近的 3 个迁移文件
3. 对照 schema 检查兼容性
4. 输出审查报告

控制上下文消耗

# 技能执行大文件时,避免整体读入
# SKILL.md 指引:
## 效率
- 大文件用 grep 定位关键内容,不全量读取
- 长列表分页处理
- 中间结果写文件,不占对话上下文

# 示例:处理 10 万行日志
grep -E "ERROR|Exception" app.log | head -100

上下文与 CLAUDE.md 的关系

# CLAUDE.md:项目级长期记忆(总是加载)
# Skills:任务级专业知识(按需加载)
# 两者互补:
# - 项目约定 → CLAUDE.md
# - 领域流程 → Skills

多技能共享上下文

# 组合技能时,通过文件传递中间结果
# 技能A输出 → 技能B读取
# 约定统一中间目录 .skill-tmp/
# 并声明文件格式(见"输入/输出"章节)

上下文设计要诀:SKILL.md 给"地图",references 给"手册",按需加载、控制消耗。技能再复杂,AI 也不会迷路。

Skills 多步骤

复杂技能往往需要多个步骤,步骤间有依赖与状态。本节介绍多步骤技能的设计与编排方法。

步骤设计原则

# 1. 步骤粒度:每步一个可验证的结果
# 2. 顺序依赖:前一步输出是后一步输入
# 3. 检查点:关键步骤后验证,失败及时止损
# 4. 可中断:任何步骤可暂停、可恢复

SKILL.md 多步骤示例

---
name: release-pipeline
description: 完整的发版流程
---

# 流程
## 阶段1: 检查
1. 检查 git 状态: git status
2. 运行测试: pytest
3. 检查依赖漏洞: pip-audit
(任一失败则中止,报告原因)

## 阶段2: 构建
4. 更新版本号(pyproject.toml)
5. 构建: python -m build
6. 校验产物

## 阶段3: 发布准备
7. 生成 CHANGELOG
8. 创建 tag: git tag v1.2.0
9. 输出发布确认清单
(推送/发布需要用户确认)

阶段化与门禁

# 阶段之间设置"门禁"
## 门禁规则
- 阶段1 全部通过才进入阶段2
- 阶段2 产物校验失败则中止
- 阶段3 的推送操作必须用户确认

# 好处:
# - 早期失败,减少浪费
# - 关键操作有确认点
# - 责任边界清晰

状态管理

# 多步骤技能的状态记录
# 约定:把状态写入文件
echo "STAGE=build" > .skill-tmp/state
echo "VERSION=1.2.0" >> .skill-tmp/state

# 恢复时读取
source .skill-tmp/state
# STAGE=build VERSION=1.2.0

进度汇报

# SKILL.md 中说明汇报节奏
## 汇报
- 每个阶段完成后汇报: 完成内容 / 结果 / 下一步
- 汇报控制在 3-5 行
- 失败时: 说明原因与建议

# 用户可随时:
# - 暂停: 中断后继续
# - 跳步: 指定从某阶段继续

幂等与重入

# 技能要支持"重跑不坏事"
# 技巧:
# - 构建前清理旧产物
# - 版本号更新前检查当前值
# - 已完成的步骤跳过(检查标记文件)

## 重入
- 检查 .skill-tmp/state 判断进度
- 已完成阶段跳过,从未完成阶段继续

错误恢复

## 错误恢复
- 阶段1失败: 修复问题后重跑该阶段
- 阶段2失败: 保留已构建产物,修复后继续
- 阶段3失败: 检查 tag/CHANGELOG 状态,避免重复创建

多步骤技能的设计要点:阶段化 + 门禁 + 状态可恢复。让技能"敢跑长流程、错了能回头"。

Skills 与工具链集成

技能的价值在于与真实工具链协作:构建工具、测试框架、部署系统、CI 流水线。本节介绍技能与工具链的集成方式。

常见集成对象

# 开发工具
- 构建: npm/pip/maven/gradle
- 测试: pytest/jest/cypress
- 代码质量: eslint/ruff/black
- 版本控制: git

# 外部服务
- CI/CD: GitHub Actions/Jenkins
- 容器: docker/kubernetes
- 云服务: AWS/GCP/阿里云
- 协作: Jira/Slack/飞书

SKILL.md 中集成工具

---
name: frontend-build
description: 前端构建与质量检查
---

# 工具链
- 包管理: pnpm
- 构建: vite
- 测试: vitest
- 检查: eslint + prettier

# 使用步骤
1. 安装依赖: pnpm install
2. 构建: pnpm build
3. 测试: pnpm test
4. 检查: pnpm lint
5. 输出构建报告

# 前置检查
- node >= 18
- pnpm 已安装(否则提示安装方式)

脚本封装工具调用

# scripts/build.sh
#!/usr/bin/env bash
set -euo pipefail

echo "== 安装依赖 =="
pnpm install --frozen-lockfile

echo "== 构建 =="
pnpm build

echo "== 测试 =="
pnpm test

echo "== 检查 =="
pnpm lint

echo "构建完成: dist/ 目录"
# SKILL.md 中调用:
# bash scripts/build.sh

CI 集成

# 技能 + CI:让 AI 在 CI 中按技能执行
# GitHub Actions 示例
- name: AI 构建检查
  run: |
    claude -p --allowedTools "Bash(pnpm:*),Read,Write"       "使用 frontend-build 技能执行构建与检查"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

工具版本与依赖声明

# SKILL.md 中声明工具要求
## 环境要求
- node >= 18
- pnpm >= 8
- 检查方式: node -v && pnpm -v
- 缺失时: 提示安装命令

# 依赖版本尽量在脚本内锁定
pnpm install --frozen-lockfile

与 MCP 集成

# 技能 + MCP:技能指导流程,MCP 提供外部能力
# SKILL.md 中说明:
## 外部依赖
- 需要数据库时,使用 mysql MCP 工具
- 需要浏览器时,使用 playwright MCP 工具

# 技能描述流程,工具提供能力,AI 负责编排

最佳实践

工具调用尽量脚本化,减少 AI 手动拼命令
声明环境要求与版本,失败可快速定位
CI 中用技能时给足超时与权限白名单
工具升级后同步更新技能中的命令

技能与工具链集成 = 流程文档 + 工具封装 + 环境声明。把工具用对、用稳,技能才真正"落地干活"。

Skills 依赖管理

技能可能依赖外部组件:脚本语言、第三方库、系统工具。依赖管理让技能"拿到就能用"。

依赖类型

# 1. 运行时依赖
- 解释器: python3 / node / bash
- 系统工具: git / curl / jq
- 第三方库: requests / pandas / axios

# 2. 技能内部依赖
- 其他技能(组合使用)
- 共享脚本(公共模块)

SKILL.md 声明依赖

# SKILL.md 中声明
---
name: data-analysis
description: 数据分析技能
---

# 依赖
- python3 >= 3.9
- pandas, numpy, matplotlib
- 检查: python3 -c "import pandas"

# 安装方式(缺失时)
pip install pandas numpy matplotlib

依赖检查脚本

# scripts/check_deps.py
import importlib

REQUIRED = ["pandas", "numpy", "matplotlib"]

missing = []
for mod in REQUIRED:
    try:
        importlib.import_module(mod)
    except ImportError:
        missing.append(mod)

if missing:
    print(f"缺少依赖: {', '.join(missing)}")
    print("安装: pip install " + " ".join(missing))
    exit(1)
print("依赖检查通过")
exit(0)

# SKILL.md 中调用
## 使用步骤
1. 检查依赖: python scripts/check_deps.py
   失败时先安装依赖再继续

环境隔离

# 技能使用虚拟环境,避免污染全局
## 环境
- 使用 .venv(技能目录内或项目内)
- 创建: python3 -m venv .venv
- 安装: .venv/bin/pip install -r requirements.txt

# 或使用 uv(更快)
uv venv .venv
uv pip install -r requirements.txt

版本锁定

# requirements.txt 锁定版本
pandas==2.2.0
numpy==1.26.4
matplotlib==3.8.3

# 或范围约束(更灵活)
pandas>=2.0,<3.0

依赖自动安装(install 脚本)

# scripts/install.sh
#!/usr/bin/env bash
set -euo pipefail

# 幂等安装:已存在则跳过
python3 -c "import pandas" 2>/dev/null &&   echo "依赖已就绪" || pip install -r requirements.txt

# SKILL.md 说明:
# 首次使用运行 scripts/install.sh
# 之后每次执行前检查(check_deps)

失败处理

# 依赖问题排查指引(写进 references/errors.md)
## 常见问题
- ModuleNotFoundError: 未安装,运行 install.sh
- 版本冲突: 检查 requirements.txt 版本约束
- 权限错误: 使用虚拟环境,避免全局安装
- 网络超时: 配置国内镜像源(pip -i https://pypi.tuna.tsinghua.edu.cn/simple)

依赖管理口诀:声明清楚 + 自动检查 + 一键安装 + 版本锁定。让技能在任何机器上都能"拿来就跑"。

Skills 版本管理

技能会持续迭代,版本管理让演进可追踪、可回退、可协作。本节介绍技能的版本管理实践。

版本标识

# SKILL.md frontmatter 中声明版本
---
name: my-skill
version: 1.2.0        # 语义化版本
---

# 语义化版本规范
# 1.2.0 = 主版本.次版本.补丁
# 主版本: 破坏性变更
# 次版本: 新增功能(兼容)
# 补丁:   Bug 修复

使用 Git 管理

# 技能作为独立仓库
cd ~/.claude/skills/my-skill
git init
git add .
git commit -m "feat: 增加参数校验"

# 打标签
git tag v1.2.0

# 查看变更
git log --oneline

变更记录 CHANGELOG

# CHANGELOG.md
# 1.2.0
- 新增: 支持 JSON 输出格式
- 新增: 增加依赖自动检查
- 修复: 修复大文件读取超时

# 1.1.0
- 新增: 支持自定义 pattern 参数
- 优化: 精简输出报告

# 1.0.0
- 首个版本

多技能仓库组织

# 方案1: 每个技能独立仓库
skills/code-review/          # 独立仓库
skills/python-packaging/     # 独立仓库

# 方案2: 单仓库多技能(推荐团队)
team-skills/
├── skills/
│   ├── code-review/
│   └── python-packaging/
├── CHANGELOG.md
└── README.md

升级策略

# 技能升级影响面评估:
# - description 变化 → 触发行为变化
# - 步骤变化 → 执行结果变化
# - 脚本变化 → 需重新测试

# 团队升级流程:
1. 在新分支开发
2. 更新版本号与 CHANGELOG
3. 测试验证(见单元测试章节)
4. 合并 main
5. 通知使用者更新(git pull)

兼容性约定

# 与其他技能/工具链的接口变化要谨慎:
# - 输入输出格式变更 = 破坏性变更(升主版本)
# - 新增可选参数 = 兼容(升次版本)
# - Bug 修复 = 补丁版本

# SKILL.md 中记录兼容性说明:
## 兼容性
- v2.0 起,输出格式改为 JSON(不再支持表格文本)

回退

# 技能出问题时回退到旧版本
cd ~/.claude/skills/my-skill
git checkout v1.1.0

# 或保留多个版本目录
~/.claude/skills/my-skill-v1/
~/.claude/skills/my-skill-v2/

版本管理让技能演进"有序可控":语义化版本 + Git + CHANGELOG,团队协作改技能时不再提心吊胆。

Skills 单元测试

测试是技能质量的保障:脚本可测,流程可验。本节介绍技能单元测试的编写与执行。

测试什么

# 1. 脚本单元测试:每个脚本函数的正确性
# 2. 流程测试:SKILL.md 步骤能否执行成功
# 3. 触发测试:description 能否被正确匹配
# 4. 边界测试:异常输入下的行为

脚本测试(以 Python 为例)

# scripts/analyze.py 的可测试化设计
# 把核心逻辑写成可导入的函数

# scripts/analyze_core.py
def count_errors(lines, patterns):
    """统计错误行"""
    return sum(1 for line in lines
               if any(p in line for p in patterns))

# tests/test_analyze.py
import sys, os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "scripts"))

from analyze_core import count_errors

def test_count_errors():
    lines = ["INFO ok", "ERROR bad", "ERROR worse"]
    assert count_errors(lines, ["ERROR"]) == 2

def test_empty_input():
    assert count_errors([], ["ERROR"]) == 0

运行测试

# SKILL.md 中说明测试方式
## 测试
- 运行: python -m pytest tests/
- 或:   bash tests/test_skill.sh

# 脚本形式的冒烟测试
# tests/test_skill.sh
#!/usr/bin/env bash
set -euo pipefail

echo "测试1: 正常输入"
python scripts/analyze.py --input sample.log || exit 1

echo "测试2: 缺失文件"
if python scripts/analyze.py --input /nonexist 2>/dev/null; then
    echo "FAIL: 应失败却成功" && exit 1
fi

echo "全部测试通过"

触发测试

# 验证 description 的触发效果
# 准备一组任务描述,逐个测试:
TEST_CASES=(
  "审查这段代码"
  "帮我 review 一下"
  "检查安全漏洞"
  "评估代码质量"
)

for task in "${TEST_CASES[@]}"; do
  claude --debug "$task" 2>&1 | grep -qi "code-review"     && echo "✅ 触发: $task" || echo "❌ 未触发: $task"
done

测试目录结构

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── tests/
│   ├── test_analyze.py       # 单元测试
│   ├── test_skill.sh         # 冒烟测试
│   └── fixtures/             # 测试数据
│       └── sample.log
└── README.md

CI 自动测试

# GitHub Actions 测试技能
name: skill-test
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - name: 运行测试
        run: |
          pip install pytest
          python -m pytest tests/

测试覆盖清单

[ ] 正常路径:标准输入得到预期输出
[ ] 空输入:空文件/空参数不崩溃
[ ] 错误输入:非法参数有清晰报错
[ ] 依赖缺失:提示安装而非崩溃
[ ] 幂等性:重复执行结果一致
[ ] 触发:常见说法都能触发技能

测试是技能质量的"保险丝"。脚本可测,流程可验,触发可查——三者都过,技能才敢共享给别人用。

Skills 日志与调试进阶

复杂技能需要完善的日志,才能在生产环境排查问题。本节介绍技能的日志设计与进阶调试技巧。

日志设计原则

# 日志三问:
# 1. 记录了关键输入输出吗?
# 2. 失败时有足够信息定位吗?
# 3. 日志不含敏感信息吗?

# 级别约定
DEBUG   调试细节(默认关闭)
INFO    关键步骤(默认开启)
WARN    可恢复的异常
ERROR   导致失败的错误

脚本日志示例

# scripts/run.sh 带日志
#!/usr/bin/env bash
set -euo pipefail
LOG_DIR=".skill-tmp/logs"
mkdir -p "$LOG_DIR"
LOG_FILE="$LOG_DIR/run_$(date +%Y%m%d_%H%M%S).log"

log() { echo "[$(date '+%F %T')] $*" | tee -a "$LOG_FILE"; }

log "INFO 开始处理: 输入=$INPUT"
if [[ ! -f "$INPUT" ]]; then
    log "ERROR 输入文件不存在: $INPUT"
    exit 1
fi
# 业务逻辑...
log "INFO 处理完成, 产出 $OUTPUT"

Python 日志

# scripts/analyze.py
import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s",
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler(".skill-tmp/logs/analyze.log"),
    ],
)
log = logging.getLogger(__name__)

log.info("开始分析: %s", input_file)
try:
    result = analyze(input_file)
    log.info("分析完成: %d 条记录", len(result))
except Exception as e:
    log.error("分析失败: %s", e, exc_info=True)
    raise

SKILL.md 日志约定

# SKILL.md 中说明日志
## 日志
- 日志目录: .skill-tmp/logs/
- 脚本运行自动记录关键步骤与错误
- 排查问题时先查看最新日志文件
- 日志中不得输出密钥/密码(自动脱敏)

进阶调试技巧

# 1. 环境变量控制详细度
DEBUG=1 python scripts/analyze.py   # 输出调试信息

# 2. 定向调试
bash -x scripts/run.sh              # 跟踪每条命令
python -m pdb scripts/analyze.py    # 断点调试

# 3. 重现现场
# 保存失败输入,修复后重放
cp /tmp/bad_input.log .skill-tmp/fixtures/

# 4. 对比测试
# 新版本 vs 旧版本输出 diff
python scripts/analyze.py --old-version ...

AI 工具侧日志

# 查看 AI 执行技能时的完整日志(Claude Code)
tail -f ~/.claude/logs/*.log

# 关注:
# - 技能加载情况
# - 脚本调用与退出码
# - 错误堆栈
# - 权限确认记录

可观测性建议

日志带时间戳与级别
关键数据(输入输出)记录摘要
失败场景自动保存现场(输入+日志)
定期清理旧日志,防磁盘占满

日志是技能的"黑匣子"。设计良好的日志,让技能在别人机器上出问题时,也能快速定位修复。

Skills 描述优化技巧

description 是技能触发的关键,也是技能文档的"门面"。本节给出描述优化的系统方法与案例。

优化目标

# 三个目标:
# 1. 高召回:该触发时一定触发
# 2. 低误报:不该触发时不触发
# 3. 可理解:人类读一眼就知道用途

描述结构模板

description: >
  [一句话:技能做什么]。
  当用户[触发场景1]、[触发场景2]、[触发场景3]时使用。
  [输出特点]。
  注意:[边界/不做什么]。

# 模板展开
description: >
  审查代码质量与安全性。
  当用户要求审查代码、检查安全问题、review diff、
  评估代码质量时使用。
  输出带严重程度的问题清单,只审查不修改。
  注意:不适用于格式整理、文档生成。

触发说法收集

# 收集用户真实说法:
# 1. 回顾历史对话中类似需求的表述
# 2. 问团队成员"你会怎么说这个需求"
# 3. 从同领域工具的 issue/文档中找说法

# 常见说法清单(审查类):
- "审查代码" / "review 一下"
- "看看有没有问题" / "检查安全性"
- "评估代码质量" / "代码体检"
- 英文: review / audit / security check

边界描述技巧

# 明确"不做什么",减少误触发
description: >
  ... 只审查,不修改代码。
  不适用于:格式美化、性能优化(有专门的技能)、
  文档生成。

# 用否定句划边界,匹配更精准

数量与层级

# 单个技能描述不要太长(2-5 句为宜)
# 内容太多就拆分技能:
# code-review-safety(安全审查)
# code-review-quality(质量审查)
# 各自描述更聚焦,匹配更准

实测迭代法

# 优化循环:
# 1. 写 v1 描述
# 2. 用 10 种说法实测触发
# 3. 记录:命中/漏掉/误触发
# 4. 针对问题改 v2
# 5. 回归测试确认没破坏

# 记录测试矩阵:
# 说法         | v1 | v2 | v3
# 审查代码     | ✅ | ✅ | ✅
# 帮我看看     | ❌ | ✅ | ✅
# 写个README  | ❌ | ❌ | ❌  (误触发的要拦截)

其他技巧

关键词自然融入,不堆砌
中英文都写(触发说法跨语言)
每季度回顾一次,补充新说法
团队共用技能,描述对齐团队术语

描述优化的核心方法:模板化 + 说法收集 + 实测迭代。一次写不好很正常,用数据驱动持续打磨。

Skills 组合与编排

单一技能解决单点问题,多个技能组合能完成复杂工作流。本节介绍技能的组合模式与编排方法。

组合模式

# 模式1: 串行(流水线)
A 输出 → B 输入 → C 输出
# 例: 代码审查 → 修复 → 测试

# 模式2: 并行(扇出)
一个任务拆成多个技能并行
# 例: 同时做 安全审查 + 性能分析 + 测试

# 模式3: 嵌套(主从)
主技能调用子技能
# 例: 发版流程中调用 构建技能 + 测试技能 + 文档技能

# 模式4: 分支(按条件)
根据输入选择不同技能
# 例: 是 Python 用 A 技能,是 Node 用 B 技能

SKILL.md 中声明协作

# 主技能中声明子技能依赖
---
name: full-release
description: 完整发版流程(依赖多个技能)
---

# 依赖技能
- build-python: 构建(阶段2)
- test-suite: 测试(阶段1)
- docs-gen: 文档生成(阶段4)

# 流程
1. 使用 test-suite 技能运行测试
2. 使用 build-python 技能构建
3. 使用 docs-gen 技能生成文档
4. 汇总发布清单

数据契约

# 组合技能的数据传递约定(重要!)
# 统一中间格式: JSON 文件 + 声明结构

# 例:审查技能输出
.skill-tmp/review_result.json
{
  "issues": [
    {"severity": "high", "file": "src/a.py", "line": 42,
     "desc": "SQL 注入风险", "suggestion": "使用参数化查询"}
  ],
  "summary": "发现 3 个问题,1 个严重"
}

# 修复技能读取该 JSON 逐项处理

编排方式

# 方式1: 用户一次对话描述,AI 自动编排
> 先审查代码,修复问题,然后跑测试

# 方式2: 显式指定技能序列
> 依次使用: code-review → auto-fix → test-suite

# 方式3: 编排技能(一个技能负责调度)
> 使用 full-release 技能执行完整发版

组合测试

# 组合场景测试
# 1. 各技能独立正常
# 2. A 输出能被 B 正确读取(格式契约)
# 3. 中间失败时流程可控(A 失败则停止)
# 4. 边界数据传递(空结果、异常数据)

# 记录组合依赖图,变更时评估影响
# A → B: A 改输出格式需同步更新 B

最佳实践

技能保持单一职责,组合出复杂能力
数据契约明确(JSON + 文档)
组合关系记录在 SKILL.md 依赖声明中
新增组合先小范围验证,再固化

组合与编排让"技能"变成"平台":几十个小技能,能编排成无数个工作流。设计好数据契约,组合就有无限可能。

Skills API 集成

很多技能需要调用外部 API:LLM 服务、SaaS 平台、内部系统。本节介绍技能与 API 的集成方法与安全实践。

API 集成类型

# 1. 大模型 API: 辅助分析/生成(如调用额外模型)
# 2. SaaS API: 内部系统、第三方服务
# 3. 云服务 API: 存储、计算、监控
# 4. 数据 API: 数据库、数据仓库

SKILL.md 声明 API 依赖

---
name: issue-sync
description: 同步代码问题到工单系统
---

# API 依赖
- 工单系统 API: https://ticket.example.com/api
- 认证: Bearer Token(环境变量 ISSUE_TOKEN)
- 幂等: 相同指纹不重复创建

# 使用步骤
1. 读取审查结果 JSON
2. 转换为工单数据格式
3. 调用创建工单 API
4. 输出工单号与链接

# 环境变量
- ISSUE_TOKEN: 必填,通过环境变量注入

脚本调用 API

# scripts/sync_issues.py
import os, json, urllib.request

TOKEN = os.environ["ISSUE_TOKEN"]   # 从环境变量读取
API = "https://ticket.example.com/api/issues"

def create_issue(title, body):
    req = urllib.request.Request(
        API,
        data=json.dumps({"title": title, "body": body}).encode(),
        headers={"Authorization": f"Bearer {TOKEN}",
                 "Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            return json.loads(resp.read())
    except urllib.error.HTTPError as e:
        print(f"API 错误: {e.code} {e.read().decode()[:200]}", file=sys.stderr)
        raise

if __name__ == "__main__":
    result = create_issue("审查发现严重问题", "见附件")
    print(f"已创建工单: {result['id']}")

环境变量注入

# 配置中注入(settings.json)
{
  "env": {
    "ISSUE_TOKEN": "tk_xxx"
  }
}

# 或系统环境变量
export ISSUE_TOKEN="tk_xxx"

# 密钥绝不写进 SKILL.md 或脚本源码!

错误与重试

# SKILL.md 中的 API 容错
## API 容错
- 超时: 15 秒,失败重试 3 次(1s/2s/4s)
- 429 限流: 等待后重试
- 认证失败(401): 检查环境变量
- 数据校验失败(422): 检查请求格式

# 重试实现
for attempt in 1 2 3; do
    if python scripts/sync_issues.py; then break; fi
    echo "重试 $attempt..." >&2; sleep $((attempt * 2))
done

幂等与安全

# 幂等:防止重复创建
# - 请求带 Idempotency-Key(内容指纹)
# - 或先查询是否已存在

# 安全:
# - 密钥只从环境变量读取
# - 不记录响应中的敏感字段
# - 外部 API 调用前确认目标可信
# - 生产环境的写操作需用户确认

测试 API 集成

# 用 mock 测试,不依赖真实环境
# tests/test_sync.py 中使用 mock 替换网络调用
# 或用测试环境 API(配置 TEST_BASE_URL)

# 冒烟测试
python scripts/sync_issues.py --dry-run
# dry-run 模式:打印将执行的请求,不发真实请求

API 集成让技能连接真实业务系统。核心规范:密钥环境变量、重试容错、幂等设计、dry-run 测试。

Skills 生态系统搭建

单个技能是工具,技能库是资产,技能生态是能力平台。本节介绍团队/组织级技能生态的搭建方法。

生态分层

# 个人层
~/.claude/skills/           # 个人技能

# 团队层
team-repo/skills/           # 团队技能库(入库共享)

# 组织层
/internal/skills/           # 组织强制技能
企业策略文件下发            # 统一权限与技能

团队技能库搭建

# 1. 建仓库
mkdir team-skills && cd team-skills
git init

# 2. 目录结构
team-skills/
├── skills/
│   ├── code-review/
│   ├── python-packaging/
│   ├── deploy-check/
│   └── api-testing/
├── README.md          # 技能清单与使用说明
├── CONTRIBUTING.md    # 如何贡献技能
└── tests/             # 跨技能测试

# 3. 安装脚本
# install.sh: 把 skills/ 链接到 ~/.claude/skills/team
#!/usr/bin/env bash
ln -sfn "$(pwd)/skills" ~/.claude/skills/team

技能治理

# 技能准入标准(进团队库的要求):
# - 有 SKILL.md,描述清晰
# - 有测试(脚本可测)
# - 经过至少一人 review
# - 文档完整(README/CHANGELOG)

# 技能退出机制:
# - 长期未使用
# - 内容过时且无人维护
# - 被更优技能替代

技能目录与索引

# README.md 技能清单
| 技能 | 用途 | 维护人 | 版本 |
|------|------|--------|------|
| code-review | 代码审查 | 张三 | 1.2.0 |
| deploy-check | 发版检查 | 李四 | 0.9.0 |

# 或生成索引文件 skills/index.md(机器可读)

推广与培训

# 让团队成员用起来:
# 1. 新员工 onboarding 时安装团队技能库
# 2. 演示:用技能解决真实痛点
# 3. 设立"技能贡献"机制(贡献者有激励)
# 4. 定期技能分享会

# 指标跟踪:
# - 技能安装数/使用频率
# - 技能节省的时间(估算)
# - 问题反馈与迭代速度

企业级管控

# 企业强制技能与策略
# /etc/claude-code/skills/      (Linux)
# 或 %USERPROFILE%\.claude\skills\enterprise

# 强制技能场景:
# - 安全审查(所有代码必须过)
# - 合规检查(数据处理规范)
# - 发布门禁(关键流程)

生态演进路径

1. 试点: 1-2 个高频技能
2. 规范: 建立准入标准与目录
3. 推广: 全员安装 + 培训
4. 治理: 定期审查 + 淘汰
5. 平台: 内部技能市场/推荐

技能生态搭建的本质:把"AI 使用经验"从个人口袋里拿出来,变成组织的共享资产。从 2 个技能起步,滚雪球式成长。

Skills 权限与安全控制

技能会读写文件、执行命令、调用 API,权限与安全控制是技能使用的底线。本节介绍技能的安全设计。

风险分析

# 技能可能带来的风险:
# 1. 恶意技能:克隆的仓库中可能藏有危险指令
# 2. 误操作:技能步骤中的破坏性命令
# 3. 数据泄露:技能读取/外发敏感数据
# 4. 权限滥用:技能在过高权限下运行

安装前审查

# 从第三方安装技能前必须审查:
# 1. 阅读 SKILL.md:步骤是否有危险命令?
# 2. 检查脚本:scripts/ 下的代码逐行看
# 3. 检查 references:是否诱导外发数据?
# 4. 检查许可证与来源可信度

# 红线命令(技能中出现即警惕):
# rm -rf / curl 外部|sh / 读取 .env 并上传
# base64 解码执行 / 下载并运行未知脚本

权限配置

# 技能运行在 AI 工具的权限框架内
# settings.json 控制:
{
  "permissions": {
    "allow": ["Read(**)", "Edit(**)", "Bash(pytest:*)"],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(.env)",
      "Read(**/*.pem)"
    ]
  }
}

# 技能目录内限制(部分工具支持):
# 敏感技能只允许访问指定目录

SKILL.md 安全声明

# 技能自述安全行为
---
name: deploy-check
description: 发版前检查
---

# 安全声明
- 只读检查,不修改生产环境
- 不读取或上传密钥文件
- 涉及生产操作时需用户确认
- 网络请求仅发往公司内网

# 使用步骤
1. 只读检查配置与代码
2. 输出检查报告
3. 如需生产操作,停下来等用户确认

敏感信息处理

# 技能中不得出现:
# - 明文密钥/密码/token
# - 内网 IP 与敏感路径(除非必要)
# - 用户个人信息

# 需要凭据时:
# - 从环境变量读取
# - 从密钥管理服务获取
# - 提示用户输入(不记录)

审计与监控

# 钩子记录技能执行
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "sh -c 'echo "$(date) $CLAUDE_TOOL_INPUT" >> /tmp/skill-audit.log'"
      }]
    }]
  }
}

# 定期审计日志,发现异常行为

安全清单

[ ] 安装第三方技能前逐行审查脚本
[ ] 技能运行在最小权限下
[ ] 危险命令 deny,生产写操作确认
[ ] 密钥不进技能文件,环境变量注入
[ ] 审计日志开启,定期检查
[ ] 企业强制技能用统一策略管控

安全控制的要诀:来源可信、权限最小、密钥隔离、全程审计。技能是好工具,但安装与使用都要"过安检"。

Skills 性能优化

技能处理大文件、长流程时可能很慢。本节介绍技能的性能优化方法,让技能"快而稳"。

性能瓶颈定位

# 常见瓶颈:
# 1. 大文件全量读取
# 2. 循环内重复 IO
# 3. 脚本启动开销(频繁调用)
# 4. 网络请求串行
# 5. 不必要的重计算

文件处理优化

# 大文件:不要全量读入内存
# ❌ 慢
data = open("big.log").read()
for line in data.split("
"): ...

# ✅ 快(流式处理)
with open("big.log") as f:
    for line in f: ...

# 只取需要的部分
# grep 定位,再精确读取
grep -n "ERROR" big.log | head -50
sed -n '100,150p' big.log

命令效率

# 用高效命令组合,减少多步处理
# ❌ 多次遍历
cat file | grep A | grep B | sort | uniq

# ✅ 一次处理(awk 等)
awk '/A/ && /B/' file | sort -u

# 善用:
# rg/grep 代替 find+xargs
# jq 处理 JSON(比 python 脚本快)
# ripgrep 比 grep 快数倍(大仓库)

脚本优化

# Python 优化要点
# 1. 用内置函数/库(比手写循环快)
result = [x for x in data if x > 0]   # 列表推导
from collections import Counter        # 计数用 Counter

# 2. 避免重复计算(缓存)
from functools import lru_cache
@lru_cache(maxsize=128)
def expensive(x): ...

# 3. 批量操作替代循环
# 数据库: executemany 替代逐条 execute
# 网络: 并发请求替代串行

并发与并行

# 网络请求并发
import concurrent.futures

with concurrent.futures.ThreadPoolExecutor(max_workers=8) as ex:
    results = list(ex.map(fetch, urls))

# 大文件分块并行(谨慎,注意内存)
# 或让 AI 用子代理并行处理多个文件

SKILL.md 性能约定

# SKILL.md 中声明性能要求
## 性能
- 单文件处理上限: 100MB(超限提示分批)
- 命令超时: 60 秒
- 大文件用流式/定位读取,不全量加载
- 网络请求并发 ≤ 8,失败重试

# 报告性能指标:
# 处理时间、处理量、内存峰值(可选)

性能测试

# 基准测试
time python scripts/analyze.py --input big.log
# 或
python -m cProfile scripts/analyze.py   # 找出热点

# 建立基线,优化后对比
# 处理 1GB 日志: 基准 120s → 优化后 45s

性能优化要诀:流式处理大文件、用高效命令、并发做 IO、缓存免重复。先测基线,再优化,用数据说话。

Skills 异步与并发

IO 密集任务(网络请求、文件读写)适合异步与并发处理,大幅缩短技能执行时间。本节介绍技能中的并发设计。

何时需要并发

# 适合并发:
# - 多个独立网络请求
# - 多个独立文件处理
# - 批量 API 调用
# - 并行测试

# 不适合并发:
# - 共享状态修改
# - 有依赖顺序的处理
# - CPU 密集(受 GIL/核心限制)

Python 并发模式

# 模式1: 线程池(IO 密集首选)
import concurrent.futures

def fetch(url):
    return http_get(url)

urls = [...]  # 100 个 URL
with concurrent.futures.ThreadPoolExecutor(max_workers=10) as ex:
    results = list(ex.map(fetch, urls))

# 模式2: 异步(高并发)
import asyncio, aiohttp

async def fetch(session, url):
    async with session.get(url) as resp:
        return await resp.text()

async def main():
    async with aiohttp.ClientSession() as session:
        tasks = [fetch(session, u) for u in urls]
        return await asyncio.gather(*tasks)

results = asyncio.run(main())

Bash 并发

# 并行处理文件
# xargs -P 指定并行度
ls *.log | xargs -P 4 -I{} python scripts/process.py {}

# 或 &
for f in *.log; do
    python scripts/process.py "$f" &
done
wait    # 等待全部完成

SKILL.md 并发约定

# SKILL.md 中说明
## 并发
- 网络请求: 并发 8-10,失败重试 3 次
- 文件处理: 并发 4(避免内存压力)
- 避免并发写同一文件
- 结果收集后统一汇总输出

# 并发安全注意:
# - 各任务独立,不共享可变状态
# - 写文件用唯一文件名(含任务 ID)

进度与取消

# 长任务进度显示
已完成 35/100 个请求(35%)

# 取消支持
# - 响应中断信号(Ctrl+C)
# - 优雅关闭: 停止新任务,等待进行中任务收尾

# Python 实现
try:
    results = list(ex.map(fetch, urls))
except KeyboardInterrupt:
    print("已取消,保留部分结果")
    ex.shutdown(cancel_futures=True)

错误隔离

# 单个任务失败不影响整体
def safe_fetch(url):
    try:
        return fetch(url)
    except Exception as e:
        return {"url": url, "error": str(e)}

# 或收集失败项统一重试
results, errors = [], []
for r in ex.map(safe_fetch, urls):
    (results if "error" not in r else errors).append(r)

资源控制

# 防止并发失控
# - 限制并发数(连接池)
# - 限速(API 频率限制)
# - 内存监控(大结果集分批写文件)
# - 总超时(整体任务超时上限)

# 总超时示例
with concurrent.futures.ThreadPoolExecutor(10) as ex:
    futures = [ex.submit(fetch, u) for u in urls]
    results = []
    for fut in concurrent.futures.as_completed(futures, timeout=120):
        results.append(fut.result())

异步并发的核心:IO 密集才并发、任务间隔离、错误不扩散、资源有上限。用对场景,技能提速数倍不是问题。

Skills 发布

技能做好后可以发布:分享给团队、开源到社区、甚至建立内部市场。本节介绍技能的发布流程与渠道。

发布前的准备

# 发布检查清单:
# 1. SKILL.md 完整(描述/步骤/边界)
# 2. 测试通过(脚本测试 + 触发测试)
# 3. 文档齐全(README + CHANGELOG)
# 4. 无敏感信息(密钥/内网地址)
# 5. 许可证明确
# 6. 版本号正确

发布到团队

# 方式1: 团队 Git 仓库
cd team-skills
git add skills/my-skill/
git commit -m "feat: 新增 my-skill 技能 v1.0.0"
git push

# 方式2: 内部包/安装脚本
# install.sh 支持按需安装
./install.sh my-skill        # 安装单个
./install.sh --all           # 全量安装

开源发布

# 发布到 GitHub
# 1. 独立仓库或提交到技能合集仓库
# 2. 编写 README:
#    - 技能用途与演示
#    - 安装方式
#    - 使用示例
#    - 贡献指南
# 3. 打 tag 发布版本
git tag v1.0.0 && git push --tags

# 4. 提交到技能目录站/合集
# 例如: 提交到 anthropics/skills 的贡献列表
# 或知名的社区技能合集

README 模板

# my-skill

审查代码质量与安全性,输出问题清单。

## 安装
git clone https://github.com/you/my-skill ~/.claude/skills/my-skill

## 使用
当你说"审查代码""检查安全"时自动触发,或显式:
> 使用 my-skill 审查 src/

## 输出示例
| 严重度 | 位置 | 问题 | 建议 |
|--------|------|------|------|

## 开发
- 测试: python -m pytest tests/
- 贡献: 见 CONTRIBUTING.md

## License
MIT

版本发布规范

# 发布流程:
# 1. 更新版本号(SKILL.md frontmatter)
# 2. 更新 CHANGELOG
# 3. 全量测试
# 4. 提交 + 打 tag
# 5. 发布说明(团队群/内部平台)

# 发布频率建议:
# - 重大变更/新技能: 即时发布
# - 小修小补: 攒批发布

发布后运营

# 1. 收集反馈: 使用者遇到的问题
# 2. 跟踪使用: 安装数、触发次数
# 3. 迭代版本: 定期更新(新说法、新场景)
# 4. 淘汰机制: 无人用/过时的技能标记或移除
# 5. 优秀技能推广: 团队分享会展示

内部技能市场

# 大型组织可建设内部技能平台:
# - 技能目录(分类/搜索/评分)
# - 一键安装
# - 使用统计
# - 审核流程
# 从"Git 仓库 + README"起步即可,平台化按需演进

发布是技能价值的放大器:个人技能 → 团队资产 → 社区贡献。发布前过检查清单,发布后持续运营,技能才会越用越值钱。

Skills 监控与可观测性

技能部署到团队后,需要监控其使用情况与健康状况。本节介绍技能的监控与可观测性设计。

监控维度

# 1. 使用情况: 谁在什么时候用了哪个技能
# 2. 执行结果: 成功/失败率
# 3. 性能: 执行时长、资源消耗
# 4. 质量: 输出是否被用户修改/返工
# 5. 健康: 依赖服务是否正常

日志驱动监控

# 技能脚本输出结构化日志(便于采集)
# 日志格式: JSON Lines(每行一个 JSON)
{"ts": "2026-08-17T10:00:00+08:00", "level": "INFO",
 "skill": "deploy-check", "action": "check_config",
 "duration_ms": 120, "result": "pass"}

# Python 输出 JSON 日志
import json, sys

def log(level, **data):
    data.update(ts=__import__("datetime").datetime.now().isoformat())
    print(json.dumps({"level": level, **data}), file=sys.stderr)

log("INFO", skill="deploy-check", action="start")

采集方式

# 方式1: 日志文件 + 定时分析
# 技能日志统一写到 ~/.claude/skills-logs/
# 定时脚本汇总统计

# 方式2: 钩子采集(AI 工具侧)
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "sh -c 'python /opt/skill-metrics/collect.py'"
      }]
    }]
  }
}

# 方式3: 直接上报到监控系统
# 技能关键节点调用上报 API(慎用,注意性能)

关键指标

# 技能健康度指标
- 成功率: 完成任务 / 总执行次数
- 平均时长: 单次执行耗时
- 返工率: 用户要求重新执行的占比(质量代理)
- 触发准确率: 误触发的比例

# 使用情况指标
- 使用频率: 日/周使用次数
- 使用分布: 哪些团队/项目在用
- 技能排行: 最常用/最不常用

告警设置

# 需要告警的场景:
# - 成功率低于 80%
# - 平均时长超过 5 分钟
# - 连续 N 次执行失败
# - 依赖 API 持续报错

# 告警渠道: 群机器人/邮件/IM
# 告警内容: 技能名、指标、时间段、示例日志

可观测性清单

# 每个技能应能回答:
# 1. 上次执行是什么时候?结果如何?
# 2. 最近成功率是多少?
# 3. 失败集中在什么场景?
# 4. 依赖的服务正常吗?

# 实现: 技能状态文件或查询接口
# 技能执行后写状态
echo "last_run=2026-08-17T10:00:00 result=ok" > .skill-tmp/status

监控落地建议

从"日志标准化"开始(JSON 日志)
先做手动查询,再逐步自动化
监控数据用于驱动技能迭代(哪里失败改哪里)
不过度设计:团队 10 个技能以内,简单统计即可

可观测性的目的不是"看仪表盘",而是"发现问题、驱动改进"。监控数据要回流到技能迭代中,形成闭环。

Skills 设计模式

技能开发中有一些可复用的设计模式。本节总结常见模式,帮助你在设计新技能时快速选择方案。

模式1: 检查器(Checker)

# 用途: 输出"是否符合规范"的检查结果
# 结构: 输入 → 逐项检查 → 通过/问题清单
# 示例: 代码审查、配置校验、发布门禁

# SKILL.md 骨架
## 检查项
1. 安全性: ...
2. 正确性: ...
3. 输出: 问题清单(严重度+位置+建议)

模式2: 转换器(Transformer)

# 用途: A 格式 → B 格式
# 结构: 输入 → 解析 → 转换 → 输出
# 示例: 文档转 Markdown、数据格式转换、代码迁移

# 关键: 声明输入输出格式契约
## 输入: JSON(字段说明)
## 输出: Markdown(结构模板)

模式3: 流水线(Pipeline)

# 用途: 多阶段处理,每阶段一个产出
# 结构: 阶段1 → 阶段2 → 阶段3(带门禁)
# 示例: 发版流程、CI 检查链、数据处理链

# 关键: 阶段隔离 + 状态可恢复(见"多步骤"章节)

模式4: 生成器(Generator)

# 用途: 根据输入生成新内容
# 结构: 需求 → 骨架 → 填充 → 校验
# 示例: 生成测试、生成文档、生成组件

# 关键: 校验生成结果,防止幻觉
## 校验
- 生成代码后必须运行测试
- 生成文档后抽查关键信息准确性

模式5: 调查员(Investigator)

# 用途: 诊断问题根因
# 结构: 现象 → 收集信息 → 假设 → 验证 → 结论
# 示例: CI 失败排查、性能问题定位、报错分析

# SKILL.md 骨架
## 诊断流程
1. 收集信息(日志/配置/环境)
2. 列出可能原因(排序)
3. 逐项验证
4. 输出结论与修复建议

模式选择指南

| 任务类型         | 推荐模式     |
|------------------|--------------|
| 评估/把关        | 检查器       |
| 格式转换         | 转换器       |
| 多阶段流程       | 流水线       |
| 创建新内容       | 生成器       |
| 找原因           | 调查员       |

# 复杂技能可组合多个模式
# 例: 发版技能 = 检查器(门禁) + 流水线(流程)

模式实现要点

每个模式都要定义:输入契约、输出契约、失败行为
检查器/门禁放最前面,早失败早止损
生成器必须带校验步骤
调查员要"假设-验证"而非"猜了就说"

设计模式让技能开发"有套路":看到任务先分类,选对模式,再填细节。技能质量与开发速度都会提升。

Skill 代码审查

代码审查是最经典的技能场景:把资深工程师的审查经验固化为技能,让 AI 按统一标准检查代码。

审查技能设计

---
name: code-review
description: 审查代码质量与安全性,输出问题清单
---

# 审查维度
## 1. 安全性(优先)
- 注入: SQL/命令/路径注入
- 认证授权: 越权、硬编码凭据
- 敏感信息: 密钥、个人数据泄露
- 输入校验: 未校验的外部输入

## 2. 正确性
- 边界条件: 空值、零值、极端值
- 并发: 竞态、死锁
- 资源: 泄漏、未关闭的连接

## 3. 性能
- 复杂度: 明显的高复杂度算法
- 重复计算: 可缓存的结果
- N+1 查询等典型问题

## 4. 可维护性
- 命名、注释、函数长度
- 重复代码、死代码
- 与项目规范的一致性

# 输出格式
| 严重度 | 文件:行号 | 问题描述 | 修改建议 |
|--------|----------|----------|----------|
- 严重度: 严重/一般/建议
- 只审查不修改

审查流程

# 审查步骤
1. 获取代码(diff 或文件)
2. 理解上下文(相关文件、调用关系)
3. 逐维度检查
4. 按严重度排序输出
5. 附上总结与优先级建议

# 结合项目规范
# 有 CLAUDE.md 时,按其中约定审查

审查范围控制

# 按场景调整范围
- 全量审查: 新接手项目
- diff 审查: 每次提交/PR
- 文件审查: 指定文件深入看
- 焦点审查: 只查安全 / 只查性能

# 在 SKILL.md 中支持参数
# 审查范围: {{$ARGUMENTS:全量|diff|文件|焦点}}

审查技巧

# 1. 让 AI 先理解再审查
"先读取相关文件理解功能,再审查"

# 2. 分级输出,先看严重的
"按严重度排序,严重问题放最前面"

# 3. 给出修改建议而非只报问题
"每个问题附一行修改建议"

# 4. 不确定的标注
"不确定的问题标注(需确认)"

输出示例

# 审查报告(示例)
## 严重问题(2)
| 文件:行号 | 问题 | 建议 |
|-----------|------|------|
| src/api.py:42 | SQL 注入(字符串拼接) | 用参数化查询 |
| src/auth.py:88 | 硬编码密钥 | 移入环境变量 |

## 一般问题(5)
...

## 总结
整体质量中等,安全性有两个必须修复的问题。
建议优先修复 SQL 注入,然后处理硬编码密钥。

与修复技能联动

# 审查 → 修复 → 复检 闭环
> 使用 code-review 审查,然后对严重问题
> 使用 auto-fix 技能修复,最后再审查确认

# 技能间数据传递:
# 审查输出 JSON → 修复技能逐项处理

代码审查技能的价值:标准统一(不再依赖个人经验)、随时可用(深夜也能审)、可度量(问题清单可跟踪)。建议团队把审查技能 + 修复技能 + 复检流程固化。

Skill 数据清洗与分析

数据清洗与分析是数据类技能的典型场景:把脏数据变成可用数据,输出洞察报告。本节介绍此类技能的设计。

技能设计

---
name: data-cleaning
description: 数据清洗与基础分析。当任务涉及脏数据、
  CSV/Excel 处理、数据去重、异常值处理时使用。
---

# 输入
- 数据文件: CSV/Excel/JSON(路径)
- 清洗要求: 可指定(默认全量)

# 清洗步骤
1. 读取数据,预览结构与样本
2. 处理缺失值(策略: 删除/填充/标记)
3. 处理重复值(去重,保留规则说明)
4. 处理异常值(范围校验、类型纠正)
5. 标准化(格式统一、单位统一)
6. 输出清洗报告与干净数据文件

清洗报告

# 清洗报告内容
## 数据概况
- 原始记录数: 10000
- 清洗后: 9850(删除 150 条)

## 处理明细
| 类型 | 数量 | 处理方式 |
|------|------|----------|
| 缺失值 | 320 | 数值列填充中位数 |
| 重复值 | 45 | 保留最早一条 |
| 异常值 | 80 | 超出 3σ 标记并删除 |
| 格式错误 | 120 | 统一为 YYYY-MM-DD |

## 质量提示
- 列 order_date 有 10% 空值,建议上游修复

分析技能

---
name: data-analysis
description: 数据分析与可视化。当任务涉及统计、
  趋势分析、图表生成时使用。
---

# 分析步骤
1. 数据概览(describe、类型、分布)
2. 按用户需求分析(趋势/对比/构成)
3. 生成可视化(matplotlib/plotly)
4. 输出: 图表文件 + 结论摘要

# 输出
- 图表: output/charts/*.png
- 报告: output/report.md(结论先行)

脚本封装

# scripts/clean.py(核心清洗逻辑可测)
import pandas as pd

def clean_data(df, strategy="median"):
    """执行清洗,返回 (df, report)"""
    report = []
    # 缺失值
    na_count = df.isna().sum().sum()
    df = df.fillna(df.median(numeric_only=True))         if strategy == "median" else df.dropna()
    report.append(("缺失值", int(na_count), strategy))
    # 去重
    dup = df.duplicated().sum()
    df = df.drop_duplicates()
    report.append(("重复值", int(dup), "保留最早"))
    # ... 更多
    return df, report

# 测试文件 tests/test_clean.py 覆盖各策略

数据处理最佳实践

# 1. 先备份原始数据
cp raw.csv raw_backup.csv

# 2. 清洗规则可配置可复现
# 清洗参数写入配置,同数据可复现

# 3. 大文件分块处理(见性能章节)
# pandas: read_csv(chunksize=10000)

# 4. 敏感数据脱敏
# 姓名/手机号脱敏后再分析

质量保障

# 清洗后验证
# - 无重复(唯一性校验)
# - 无空值(完整性校验)
# - 类型正确(模式校验)
# - 抽样人工检查

# 输出"清洗前后对比"供用户确认
# 数据类技能宁可多确认,不可擅自丢弃数据

数据清洗与分析技能的价值:重复性清洗自动化、规则标准化、结果可复现。适合有规律数据处理需求的团队沉淀。

多 Skill 协作工作流

真实场景往往需要多个技能协作:审查 → 修复 → 测试 → 发布。本节设计一个完整的"多技能协作工作流"实例。

示例:AI 驱动的修复流水线

# 目标: CI 失败时,AI 自动分析并修复
# 技能组合: 4 个技能协作

流水线:
1. ci-diagnose  (调查员模式) 分析 CI 失败原因
2. code-review  (检查器模式) 审查待改代码
3. auto-fix     (生成器模式) 修复问题
4. test-verify  (检查器模式) 验证修复

编排技能

# 编排技能:负责调度整个流水线
# .claude/skills/ci-repair/SKILL.md
---
name: ci-repair
description: 自动修复 CI 失败。当 CI 失败、测试失败、
  构建报错时使用,执行完整的分析与修复流程。
---

# 依赖技能
- ci-diagnose
- code-review
- auto-fix
- test-verify

# 流程
1. 使用 ci-diagnose 技能: 定位失败原因
2. 输出诊断报告给用户确认
3. 用户确认后:
   - 使用 code-review 审查相关代码
   - 使用 auto-fix 修复
4. 使用 test-verify 验证
5. 输出修复报告

# 门禁
- 诊断不明确时,不盲目修复
- 涉及大改动,先出方案再动手

数据流转

# 技能间通过文件传递中间数据
.skill-tmp/
├── diagnosis.json      # ci-diagnose 输出
├── review_result.json  # code-review 输出
├── fix_summary.md      # auto-fix 输出
└── test_result.json    # test-verify 输出

# 各技能在 SKILL.md 声明:
## 输出
- 写入 .skill-tmp/xxx.json,格式: {...}

# 编排技能读取各阶段结果,汇总最终报告

使用方式

# 用户只需一个指令
> 使用 ci-repair 技能处理 CI 失败

# 或直接描述需求,AI 自动组合
> CI 挂了,分析原因并修复,最后跑测试确认

# 编排技能让复杂流程"一键执行"

协作规范

# 1. 技能间契约文档
# 在编排技能 SKILL.md 中写明:
# 各子技能的输入输出格式

# 2. 失败处理
# - 某阶段失败: 记录原因,停止或跳过
# - 允许用户跳步: 跳过审查直接修复

# 3. 权限
# - 流水线技能运行在适当权限下
# - 推送/发布等操作必须确认

工作流版本管理

# 工作流也会演进:
# - 新增技能阶段
# - 调整执行顺序
# - 修改门禁规则
# 用版本号 + CHANGELOG 记录

# 工作流测试: 端到端跑一遍全流程
# 用 mock 环境验证各阶段衔接

多技能协作工作流的本质:编排技能 + 子技能 + 数据契约。先画流程图,再实现各技能,最后用编排技能串起来。

Superpowers

Superpowers 是社区知名的 Claude Code 技能合集,由 Jesse Vincent(obra) 创建,包含 100+ 个技能,是学习技能生态与提升开发效率的宝库。

Superpowers 是什么

# 一个系统化的技能集合,理念:
# "给 AI 超级能力" = 技能 + 工作流 + 脑力工具
# 包含:
# - 100+ 个技能(逐步增加)
# - 技能之间的协作工作流
# - brainstorming/planning 等思维工具
# - 自动加载机制(核心技能常驻)

安装

# 方式1: git clone
git clone https://github.com/obra/superpowers ~/.claude/skills/superpowers

# 方式2: 插件市场(如支持)
# Claude Code 插件市场搜索 Superpowers

# 安装后重启会话生效

核心特性

# 1. 自动加载的思考技能
# - brainstorming: 头脑风暴(发散)
# - planning: 计划制定(收敛)
# - problem-solving: 问题解决框架

# 2. 子技能依赖机制
# 技能可声明依赖其他技能,自动组合

# 3. 工作流模板
# 完整的工作流: 需求 → 计划 → 实现 → 测试 → 复盘

# 4. 模块化技能
# 按需启用,避免加载过重

典型用法

# 复杂任务自动触发 planning 工作流
> 我们要做一个新的搜索功能,帮我规划一下

# 触发 brainstorming
> 头脑风暴一下订单模块的优化方向

# 手动调用具体技能
> 使用 superpowers 的 write-tests 技能为模型层写测试

工作流示例

# planning 工作流的典型流程:
1. 澄清需求(提问确认)
2. 收集上下文(读取相关文件)
3. 生成计划(任务分解)
4. 用户确认
5. 分步执行(每步验证)
6. 复盘总结

学习价值

# 对技能开发者来说,Superpowers 是绝佳教材:
# - 看 SKILL.md 怎么写(描述/步骤/依赖)
# - 看技能如何协作(依赖声明)
# - 看工作流如何设计(阶段/门禁)
# - 看思维工具如何结构化

# 建议: 安装后通读几个核心技能的 SKILL.md

注意事项

技能量大,首次加载可能较慢,按需启用
部分技能与工具版本相关,注意兼容
社区项目,更新频繁,关注 release 说明
参考其模式,但按团队实际定制自己的技能库

Superpowers 展示了"技能生态"的完整形态:技能 + 工作流 + 思维方式。即使不用它,也值得学习它的设计思路。

Taste Skill

"Taste"(品味/审美)是 AI 编程中常被忽视却极其重要的能力:代码是否优雅、方案是否合适、取舍是否合理。Taste Skill 尝试把这种"软能力"结构化。

什么是 Taste

# 在编程语境下,Taste 指:
# - 代码是否简洁优雅(而非堆砌)
# - 命名是否传神(而非随意)
# - 架构是否恰当(而非过度设计)
# - 方案是否符合项目风格
# - 知道"什么时候不该写代码"

Taste Skill 做什么

# 一个帮助 AI 提升代码品味的技能:
# - 提供代码审美检查清单
# - 引导权衡取舍(简单 vs 灵活)
# - 对齐项目风格(读现有代码的风格)
# - 评审时加入"品味"维度

# SKILL.md 示例骨架
---
name: taste-review
description: 从代码品味角度评审:优雅性、简洁性、
  一致性、取舍合理性
---

# 品味检查
## 简洁
- 是否可以用更少代码表达?
- 是否有过度抽象/过度工程?

## 命名
- 命名是否表意?是否误导?
- 是否符合项目命名风格?

## 一致性
- 与项目现有代码风格一致吗?
- 同类型问题是否同样处理?

## 取舍
- 方案复杂度与收益匹配吗?
- 是否引入了不必要的依赖/抽象?

应用场景

# 1. 代码审查中加入品味维度
> 用 taste-review 技能审查,重点关注代码是否优雅

# 2. 生成代码时对齐品味
> 参照 src/ 现有代码的风格与品味,实现新功能

# 3. 方案评审
> 评估这两个方案:哪个更符合我们的代码风格?

如何培养 AI 的品味

# 1. 提供好样例
# CLAUDE.md 中给"好代码示例"与"坏代码示例"

## 风格参考
- 好: 见 docs/examples/good_practice.py(简洁优先)
- 避免: 过度封装、隐式魔法、冗长命名

# 2. 明确品味偏好
# CLAUDE.md 或技能中声明:
# - 偏好小函数(≤20行)
# - 偏好显式优于隐式
# - 优先标准库,少引依赖

# 3. 反馈循环
# 用户不满意时明确说"这里太绕了,改简洁"
# AI 记录偏好,下次遵守

Taste 的价值

# 为什么品味重要:
# - 代码是给人读的: 优雅代码维护成本低
# - 风格一致: 团队可读性提升
# - 避免过度设计: 减少不必要的复杂度
# - AI 产出更接近"好工程师"而非"能跑的代码"

实践建议

把品味偏好写进 CLAUDE.md(团队共享)
审查类技能加入品味维度
用真实案例校准: 指出哪里好/哪里差
品味是迭代的: 持续反馈,持续校准

Taste Skill 的本质:把"代码审美"从玄学变成可检查、可对齐、可迭代的标准。让 AI 不只写出"能跑的代码",而是写出"好看的代码"。

Skills(技能)

Skills 教程总结

恭喜你完成了 Skills 教程的学习!本节回顾核心知识,并给出从"会用"到"会造"的行动路线。

核心知识地图

是什么:Skills 是 AI 的"专业能力包",用标准化文件让 AI 按流程执行任务
结构:SKILL.md(核心)+ scripts(脚本)+ references(参考)
触发:description 语义匹配,写得好才"找得到"
质量:调试、测试、版本管理保证可靠
扩展:脚本、API、工具链、MCP 让技能能干实事
协作:组合、编排、多技能工作流解决复杂问题
生态:团队库、发布、监控、治理,从个人到组织

技能开发者成长路径

L1 使用者: 安装现成技能,会用
L2 写手:   能写简单 SKILL.md(检查器/生成器)
L3 工程师: 脚本+测试+版本管理,质量可控
L4 架构师: 组合编排、生态治理、团队落地

行动计划

# 今天就做
1. 用 skill-creator 创建第一个技能
2. 把最常用的"审查/测试"流程技能化
3. 安装 Superpowers 学习优秀技能写法
4. 给技能写测试(触发测试 + 脚本测试)
5. 把技能库提交到团队仓库

# 本周
- 挑选 3 个高频工作流做成技能
- 建立团队技能库与准入标准

常见误区

❌ 把技能当 prompt 收藏夹 → ✅ 结构化、可测试
❌ 描述随便写 → ✅ 描述是触发关键,反复打磨
❌ 一步到位写大技能 → ✅ 小步迭代,先简后繁
❌ 只写文档不带脚本 → ✅ 确定性逻辑脚本化
❌ 技能不做测试 → ✅ 测试是共享的前提

核心心法

Skills 的本质是"把经验变成可复用的资产"。写技能时问自己:这个流程值得重复 10 次吗?值得团队其他人用吗?值得的话,就把它做成技能。

AI 工具在进化,技能生态会越来越重要。现在开始积累你的技能库,就是为未来的 AI 协作方式提前布局。

第 1 / 40 节