Skills
skills/liuzhengdongfortest/easysdd/skill-master

skill-master

Installation
SKILL.md
Contains Shell Commands

This skill contains shell command directives (!`command`) that may execute system commands. Review carefully before installing.

skill-master

0. 读完这一节你要做什么

先搞清楚用户现在处于三种场景里的哪一种，然后跳到对应小节：

  • 要做一个新的 skill → 读 §2 "创建新 skill"
  • 已有 skill 要改（描述不触发、行为不对、该拆文件了） → 读 §3 "优化已有 skill"
  • 用户让你优化 skill-master 自己 → 读 §4 "自我优化"

如果判断不出来，就问一句。不要靠猜。

§1 是 skill 的心智模型，任何分支都要熟，但不用每次都重新读——只在你对某个概念把不准时回来翻。

1. 心智模型：一个 skill 到底是什么

一个 skill 是 <skill-name>/SKILL.md，外加同目录下的可选辅助文件。Claude Code 启动时把所有 skill 的名字 + description 收进上下文，Claude 读到用户问题后自己决定要不要拉某个 skill 的正文进来。用户也可以 /skill-name 直接触发。

关键是"渐进加载"——description 始终在上下文（贵），SKILL.md 正文只在触发时进来（触发才花钱），辅助文件只在 SKILL.md 里提到、Claude 判断要看时才读（几乎免费，直到要用）。所以写 skill 最贵的是 description 的每个字，最便宜的是 reference/ 里面的长文。这决定了怎么分配内容：description 像广告语，正文像说明书首页，reference 像附录。

一次会话里一个 skill 只会被加载一次——它作为一条消息进来之后就一直留着，不会随着对话重读。所以里面要写的是"整段任务期间都成立的原则"，不是"这一步做完就扔掉的步骤"。

SKILL.md 的构造

---
name: my-skill                 # 小写、连字符、<=64 字符；不写就用目录名
description: 一句话说清楚做什么 + 什么时候用  # 关键字段
---

正文（Markdown）

frontmatter 里实际会用到的字段（其他的用到再查 reference/anatomy.md）：

字段 什么时候写
description 永远写。Claude 靠这个决定要不要拉你进来
when_to_use description 塞不下更多触发语时用，和 description 拼起来共享 1536 字符上限
argument-hint skill 需要参数时，给用户看 autocomplete 提示
disable-model-invocation: true 只想让用户手动 / 调用（有副作用的 deploy、commit 之类）
user-invocable: false 只想让 Claude 后台自动用，不想出现在 / 菜单（背景知识类）
allowed-tools 某几个工具不想每次都弹权限问
context: fork + agent 任务独立、不需要看主会话历史，派到子 agent 跑
paths 只在编辑匹配文件时才自动触发（packages/api/**/*.ts 这种）

安放位置

层级 路径 谁能用
用户级 ~/.claude/skills/<name>/ 这台机器所有项目
项目级 <project>/.claude/skills/<name>/ 这个仓库
Plugin <plugin>/skills/<name>/ 装了这个插件的地方

同名时 enterprise > 用户 > 项目。写 skill 前先问用户装哪一层——通用工具放用户级，只和某个项目相关的约定放项目级。

字符替换

$ARGUMENTS（全部入参）、$0/$1/...（位置参数）、${CLAUDE_SKILL_DIR}（skill 自己的目录，引用同目录脚本时用）、${CLAUDE_SESSION_ID}。

两个预处理语法

  • 行内 !`gh pr diff`：在 skill 正文送给 Claude 之前执行这个 shell，结果替换掉占位符。这是预处理，不是让 Claude 执行。用来把动态数据（PR 差异、环境信息、当前分支）拼进 prompt。
  • 多行 ! ``` 代码块：上面的多行版本。

如果你看见自己写的 skill 一上来就让 Claude "先运行 xxx 命令看一下"，停一下——通常应该改成 !xxx`` 预先喂给它，省一轮工具调用。

2. 创建新 skill

2.1 先把意图钉死

问用户（每一条都要明确）：

  1. 这个 skill 让 Claude 做什么事？ 一句话回答——如果描述不出来，要么需求还不清楚，要么其实是多个 skill。
  2. 什么时候该触发？ 让用户给 3-5 条真实场景的原话，比如"我想做 X"、"帮我 Y"。这是 description 的原材料。
  3. 什么时候不该触发？ 找 2-3 条相邻但不该触发的情况。skill 越强大，"别乱触发"越重要。
  4. 装哪一层？ 用户级还是项目级。不清楚就默认项目级。
  5. 有没有副作用？ 比如会 push、会发消息、会改共享资源。如果有，默认 disable-model-invocation: true，只让用户手动 / 触发。

用户答完了重复一遍，让他确认。不要边猜边写。

2.2 起骨架

<name>/
├── SKILL.md          # 必须
└── reference/        # 可选，SKILL.md 超过 400 行再拆
    └── <topic>.md

Skill 第一版尽量只有 SKILL.md。拆文件是为了给"正文里不想塞但又想让 Claude 需要时能查到的东西"找地方，太早拆只是增加理解成本。

2.3 写 description——这是整个 skill 最重要的一行

description 是 Claude 判断要不要加载你的唯一依据。写错它，skill 再好也等于没有。

结构建议：<做什么> + <什么时候用>。把最典型、用户最可能的触发语原话塞进去——Claude 的匹配是语义的，但原话命中率更高。

反例：

  • "Helps with code review" ← 太抽象，任何写代码的场景都可能触发，也可能都不触发
  • "Code review assistant" ← 把自己介绍得像个产品，不是说明什么时候该用

正例：

  • "用户想对 PR 或代码改动做 code review 时进入——读 diff、点出问题、给出修改建议。常见触发：'帮我 review 下这个 PR'、'看看我这次改动有没有问题'、'我改完了你扫一眼'。"

要点：

  • 用动词开头描述动作，别用名词短语当介绍
  • 列 2-4 条具体触发语（用户真实会说的话，不是官样描述）
  • 如果它和别的 skill 容易混，在 description 里明确边界（"要做 X 的时候用别的，这个只管 Y"）
  • 别怕"推一点"——Claude 的默认倾向是少触发 skill，不是多触发。如果这个 skill 确实在某个场景下有用，就写明确，别含糊
  • 全部（description + when_to_use）合起来会被截到 1536 字符，所以把关键触发语放前面

2.4 写正文

默认目标：300 行以内，500 行是上限。超过了要么内容真的需要，要么该拆 reference/ 了。

结构模板（不是必须照抄，是思考顺序）：

  1. 这个 skill 什么时候该读哪一段——如果正文里有分支（"新建场景走 A，优化场景走 B"），在最上面给个分发指引，Claude 不用每次都把整篇读完
  2. 心智模型 / 背景——解释"为什么这么做"，不是"怎么做"。Claude 很聪明，给理由比给 MUST 管用
  3. 工作流 / 步骤——真正的指令。用命令式（"读 X"、"问用户 Y"），不是宾语缺失的被动语态
  4. 参考文件指路——reference/xxx.md 里有什么、什么时候去翻

写作风格的几条硬要求：

  • 少用全大写 MUST / NEVER。看到自己写这种词停一下，问：能不能改成解释原因的一句话。能的话就改。只有"跳过这步会真的导致错误"的场合才保留硬性语气
  • 解释为什么。"做这一步是因为 X"比"必须做这一步"更能迁移到边界情况
  • 别过度具体化。skill 是要被用成千上万次的，只围着某 3 个示例打转写出来的指令对真实世界没用。如果只能想出针对具体例子的规则，那就先别写，等 eval 暴露问题再补
  • 别加冗余"如果 X 就做 Y"。那种每种情况都穷举的列表 Claude 不会真按它跑，反而会让正文膨胀。把核心原则讲透就行

2.5 什么时候加辅助文件

加 reference/<topic>.md：某类参考材料（API 规格、长表格、详细规则）正文吃不下，但又要让 Claude 需要时能查。写法：在 SKILL.md 里一句话指路——"要查完整字段列表见 [reference/fields.md]"。

加 scripts/<xxx>.py：任务里有确定性的、重复的计算或转换（扫目录、拼 HTML、跑数据清洗）。写一次比让 Claude 每次都现写强——Claude 每次写的版本不一样，又费 token。用 ${CLAUDE_SKILL_DIR}/scripts/xxx.py 引用。

加 assets/<xxx>：模板、示例文件、图片素材。

判断标准：如果某段内容只有 20% 的调用会用到，它就该在辅助文件里，不在 SKILL.md 里。

2.6 自测——最低限度

写完之后至少做一次：

  1. 读一遍 description，假装你就是读到用户问题的 Claude，问自己"我会拉这个 skill 吗"
  2. 跑一个真实触发场景，看 Claude 实际的行为和你预期是否一致
  3. 跑一个不该触发的场景，看会不会误触发

大多数问题在这一步会暴露。发现问题改，改完再跑。

2.7 告诉用户

交付时说清楚：skill 装在哪（路径）、怎么触发（用户原话的哪一类 / 或 /<name>）、有没有副作用、下一步怎么迭代（跑一段时间后回来调）。不要长篇总结正文——他能打开看。

3. 优化已有 skill

用户带着"这个 skill 有问题"来，先别急着改，先搞清楚是哪一类问题。

3.1 分类

症状 大概率原因 改哪里
该触发的时候没触发 description 没覆盖用户真实说法 改 description，加用户原话
不该触发的时候触发了 description 太泛，或关键词和别的场景重叠 改 description，加边界说明或明确排除
触发了但行为不对 正文指令模糊、或者缺关键步骤、或者有矛盾 改正文
跑得特别慢 / 吃特别多 token 正文太长、或者让 Claude 现写本该是脚本的事 拆 reference/ 或加 scripts/
多轮对话里 skill 好像"失效了" 大概率没失效，只是被别的上下文盖过。见 §3.5 加强 description，或改成正文里用"原则式"语言

3.2 改 description 的典型操作

  • 加触发语：问用户最近一次想用它但没触发时说了什么原话，塞进 description
  • 加排除：description 末尾加一句"（不要和 X 搞混——X 用另一个 skill 处理）"
  • 缩短：如果超过 1536 字符会被截，把最关键的触发条件前置

3.3 改正文的典型操作

  • 删冗余：读一遍，每一段问"拿掉这段会怎样？"——如果答案是"没怎样"或"Claude 也会做对"，就删
  • 把 MUST/NEVER 改成解释："NEVER skip step 3" → "第 3 步如果跳过，X 会因为 Y 而失败"。Claude 理解原因之后在边界情况下判断更准
  • 把具体例子上升为原则：如果发现只有针对某几个具体案例的规则，想一下它们共同的底层原则是什么，用原则替换

3.4 什么时候该拆文件

  • SKILL.md 逼近 500 行
  • 正文里有明显的"A 情况 / B 情况"大段分叉，而单次调用只会走其中一个
  • 有大段参考材料（表格、字段列表、示例集）正文其实不需要，只是怕 Claude 找不到

拆完了记得在 SKILL.md 留指路句，不要让 Claude 不知道这些文件存在。

3.5 "skill 失效了" 其实不是失效

一次会话里 skill 只加载一次，加载进来之后不会重读。所以用户说"后面几轮它没照着 skill 做"——内容其实还在，只是 Claude 选了别的路径。改法：

  • 在正文加强"什么时候该回到 skill 的原则"的表述
  • 把"步骤式"指令改成"原则式"指令——原则在整段对话里都成立，步骤只在当下那一轮成立
  • 实在不行用 hooks 硬性保证某些行为

4. 自我优化（skill-master 改自己）

这是一个特殊分支——用户说"skill-master 自己优化下"或"你来改自己"时走这条路。

4.1 前提意识

你现在要改的文件就是你刚读进上下文的这份 SKILL.md 及同目录文件。改完之后当前会话里你还是按旧版本跑——skill 内容不会在同会话重读。所以改完告诉用户"下次会话生效"。

4.2 流程

  1. 读自己所有文件。${CLAUDE_SKILL_DIR} 下的 SKILL.md、reference/、scripts/，全读一遍。别凭记忆改，你当前上下文里的那份可能已经被压缩过
  2. 让用户说清楚不满在哪。"哪次调用觉得不对？说了什么、希望是怎样？"——没有具体场景就别动，瞎改只会更糟
  3. 按 §3 的分类法归因：是 description 问题、正文问题还是文件组织问题
  4. 提出改动方案先讲。别直接改——你是 skill-master，改自己是高权重操作，让用户确认方案再动手
  5. 改完自陈改了什么、为什么。一两句话就够

4.3 自我优化的反模式

  • 扩大 scope——用户只是抱怨 description 不触发，你顺便把正文也重写了。别这样，改需要最小化
  • 加更多规则——遇到一个边界情况就加一条 MUST。规则会膨胀，理解成本越来越高。优先改底层解释、不是加补丁
  • 放弃心智模型——skill-master 的价值来自它对 skill 的原理性理解。每次自我优化都要保住 §1 的清晰度，别让它退化成一堆 checklist

5. 常见陷阱

  • description 写成"这个 skill 能做 X"——描述的是能力不是触发条件。改成"用户想 X 时用"
  • 正文塞一堆 MUST/ALWAYS/NEVER——Claude 不是按规则引擎跑的，原因比规矩管用
  • 把教程当 skill——如果内容是"怎么在 Vue 里用 X"这种普适教程，它该在用户级 skill 或文档里，不该绑项目
  • 一个 skill 想做 3 件事——description 会写不清，触发会出错。拆成多个 skill，或者做一个只负责"路由到哪个子 skill"的入口
  • 为了"全面"写一堆不会用到的字段——每个 frontmatter 字段都是认知成本。只写你实际需要的
  • 忘了 skill 是要被迁移和分享的——写的时候想想"别人读到这个会懂吗"，而不是"我现在看得懂就行"

6. 参考

  • reference/anatomy.md——frontmatter 全字段速查、字符替换、lifecycle 细节、!command`` 语法
  • reference/techniques.md——description 调优模式、progressive disclosure 的实际案例、bundled scripts 的写法、subagent / context fork 什么时候用

官方文档：https://code.claude.com/docs/en/skills

Weekly Installs
2
Repository
liuzhengdongfor…/easysdd
GitHub Stars
147
First Seen
4 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
amp2
cline2
opencode2
cursor2
kimi-cli2
warp2