SKILL使用样例

基本概念

Skills 本质上就是教 AI 按固定流程做事的操作说明书，一旦写好，就能像函数一样反复调用。

我们可以把 Skills 看成把某类事情应该怎么专业做这件事，封装成一个可复用、可自动触发的能力模块。

Skills 以 Markdown 文件形式存在，不执行功能，而是通过按需、渐进式加载，实现高效且可复用的经验传递。

Skills 与 MCP 的区别

Skills 用于知识复用，MCP 用于能力扩展。

存放位置

位置	路径	适用范围
个人	~/.claude/skills//SKILL.md	所有项目
项目	.claude/skills//SKILL.md	仅当前仓库
插件	/skills//SKILL.md	启用该插件的项目

skill定义

目录结构

my-skill/
├── SKILL.md # 必需：指令 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：文档资料
└── assets/ # 可选：模板、资源

格式

SKILL.md 完整格式：

---                                 #  YAML frontmatter 开始（顶格）
name: code-comment-expert           # 必填：技能名（也是 /slash 命令名）
description: >-                     # 必填：最关键一行！Claude 靠它判断是否加载
  为代码添加专业、清晰的中英双语注释。
  适合缺少文档、可读性差、需要分享审查的代码。
  常见触发场景：加注释、注释一下、加文档、explain this、improve readability

trigger_keywords:                   # 强烈推荐（大幅提升自动触发率）
  - 加注释
  - 注释
  - 加文档
  - explain code
  - document
  - comment this
  - readability

version: 1.0                        # 可选
author: yourname                    # 可选
---                                 # ← YAML 结束

# 这里开始是正文（Markdown）—— Claude 真正执行时的指令

你现在是「专业代码注释专家」。

## 核心原则
- 只在缺少注释或可读性明显不足处添加
- 优先使用英文 JSDoc / TSDoc 风格
- 复杂逻辑 / 非明显意图处额外加一行中文解释
- 注释精炼，每行不超过 80 字符
- 绝不修改原有逻辑

## 输出格式（严格遵守）
1. 先输出完整修改后的代码块（用 ```语言 包裹）
2. 再用 diff 形式展示只改动注释的部分
3. 最后说明加了哪些注释、理由

进阶文件结构（技能变复杂时推荐）

当技能超过 500–800 行，或需要模板/脚本/参考资料时，推荐以下组织方式：

~/.claude/skills/react-component-review/
├── SKILL.md # 核心指令 + 元数据（建议控制在 400 行内）
│
├── templates/ # 常用模板（Claude 按需读取）
│ ├── functional.tsx.md
│ └── class-component.md
│
├── examples/ # 优秀/反例（给 Claude 看标准）
│ ├── good.md
│ └── anti-pattern.md
│
├── references/ # 规范、规则、禁用词表
│ ├── hooks-rules.md
│ └── naming-convention.md
│
└── scripts/ # 可执行脚本（需开启 code execution）
├── validate-props.py
└── check-cycle-deps.sh
在 SKILL.md 中引用方式示例：

Markdown需要给出标准函数组件时，参考 templates/functional.tsx.md 的结构。

如果违反 Hooks 规则，对照 references/hooks-rules.md 第 3–5 条说明。

如需校验 propTypes，可执行 scripts/validate-props.py "{代码片段}"。
Claude 看到路径引用后，会按需加载对应文件，而不是一次性全部塞入上下文，极大节省 token。

设计原则

简洁至上
- 上下文窗口是公共资源。
- Skills 与 Claude 所使用的其他上下文是共享的：系统提示、对话历史、其他 Skills 的元数据，以及最终的用户请求，都会一并纳入。
- 默认假设：Claude 已经很聪明了。仅提供 Claude 缺失的上下文信息。
- 对每一条信息都要保持怀疑态度：
  「Claude 真的需要这个解释吗？」
  「这个段落值得花费 token 吗？」
- 专业技巧：
  优先使用简洁示例，而非冗长说明。精心设计的示例比整段描述传达更多信息，同时消耗更少 token。

设定合适的自由度

确保示例和说明的具体性与任务的脆弱性及变异性相匹配：

自由度级别	何时使用	实现方式
高	多种有效方法，依赖上下文的决策	基于文本的指令
中	存在首选模式，允许一些变化	伪代码或参数化脚本
低	脆弱操作，一致性至关重要	特定脚本，少量参数

渐进式披露
Skills 使用三级加载系统来高效管理上下文：
- 第一级 - 元数据（始终加载）
  YAML 前置元数据中的名称和描述
  每个 Skill 约 100 token
  支持发现而不消耗上下文
- 第二级 - SKILL.md 主体（触发时加载）
  主要指令和程序
  目标控制在 500 行 / 5k token 以下
  当 Claude 判定 Skill 相关时加载
- 第三级 - 打包资源（按需加载）
  脚本、参考资料、资产
  无限容量
  脚本可以在不加载到上下文的情况下执行
注意：保持 SKILL.md 精简，最好不要超过 500 行。如果快到上限，可以把内容拆到单独的参考文件，这样既防止上下文膨胀，也不影响功能。

创建skill

以Claude Code下执行为例, opencode或者别的ai agent都是类似的.

手写

基于skill文件结构定义手动实现skill定义

skill-creator

在claude中使用内置的skill创建工具创建,即输入skill-creator,之后按提示步骤执行

安装skill

选择一个存放位置，比如.claude/skills/，将新下的skill文件整目录拷贝过去
然后新建一个Claude控制台(skill发生变化,需要Claude重启后才能生效)，输入/skills，即可看到新安装的skill

样例