Skill 作者指南

当你想给团队加一个新 skill / 改一个既有 skill 时读。

---

1. 何时该加 skill

✅ 加：

• 同样的问题在团队里被问过 3 次以上
• 一个项目特有的"易错点"还没沉淀
• IFinmate / czerp-console 出了新能力，开发还没意识到
• 一个跨人多次踩坑的工作流

❌ 不要加：

• 个人偏好（不是团队共识）
• Superpowers 已有的通用能力（brainstorming/TDD/etc.）
• 一次性的内容（写成 docs 就行，不用 skill）

2. Skill 结构

plugins/<plugin-name>/skills/<skill-name>/
├── SKILL.md                # 必需，含 YAML frontmatter
├── references/             # 可选，长引用文件
└── scripts/                # 可选，可执行脚本（如 Bash）

3. SKILL.md 模板

---
name: <kebab-case-name>
description: 一句话说清"这 skill 做什么 + 什么时候被触发"，把触发词融进描述（40-160 字）。Claude 只靠 description 匹配。
version: 1.0.0
---

# <kebab-case-name>

## 何时调用

具体场景描述（避免泛泛）。

## 核心模式 / 即用代码

```语言
// 最小可用代码示例

易错点

• 错误模式 1 → 正确做法
• 错误模式 2 → 正确做法

源文档

• 路径或链接（绝对路径或 PingCode URL）

关联

• 上下游 skill

  > **关于 frontmatter**：Claude Code 触发**只看 `description`**（外加可选 `allowed-tools`），所以触发词必须融进 `description`（见 4.2）。本仓库**不使用 `triggers` 字段**（它不参与匹配，已从全部 skill 移除）；`version` 仅供人阅读、可省略。
  
  ## 4. 写好的 6 条原则
  
  ### 4.1 指针 + 范式 + 易错点，不复制原文
  
  skill 是**导航 + 即用模板 + 警示**，不是抄文档。让 AI 通过 skill 知道"去哪查 + 怎么用 + 别踩坑"。
  
  ### 4.2 触发词要具体
  
  ❌ `description: "处理订单"`
  ✅ `description: "OMS 订单导出多币种功能：用 IExchangeRateClient 拉汇率，缓存 5min，FMS 故障降级为仅 CNY。当用户说'订单导出'、'多币种 Excel'时触发。"`
  
  ### 4.3 给最少可用代码
  
  不要写 50 行 demo；写**最关键的 5-10 行**让 AI 抓得住。
  
  ### 4.4 易错点必须真实
  
  写"易错点 1：忘记加 `@Service`" 这种没人会犯的不要写。
  写"易错点 1：Feign 调用支撑服务 fallback 返回 `null` 时没空值保护导致 NPE" 这种真踩过的。
  
  ### 4.5 链向源文档
  
  源文档是权威。skill 必须指向源文档（`ifinmate-document/...` / PingCode page id / czerp-console docs / Github URL）。
  
  ### 4.6 关联其他 skill
  
  skill 之间是**网络**不是孤岛。在底部列出上下游 skill。
  
  ## 5. 提 PR 流程
  

• fork 本仓库（如外部协作）/ 创建分支（内部）
• 在 plugins//skills// 下加 SKILL.md
• 确保 SKILL.md frontmatter 的 description 含明确触发关键词（两端唯一触发源，见 §4.2）
• 更新对应 plugin 的 README.md skill 列表
• 跑本地验证：让 Claude Code 加载该 skill 跑一次典型对话
• 提 PR，关联到对应的痛点（最好是 PingCode 上的具体讨论）
• 至少 1 名同事 + Tech Lead approve
• 合并
• 团队成员 /plugin update 拿到新版

  ## 6. 反例：什么样的 skill 会被打回
  
  - 重复 Superpowers 已有能力
  - description 模糊到不知道什么时候触发
  - 大段抄 ifinmate-document 原文
  - 没有"易错点"段（皮没痛痒就没价值）
  - 触发词太宽（"代码 / 编程" 这种）
  
  ## 7. 维护责任
  
  谁加的 skill 谁维护：
  
  - 框架行为变了 → 源文档更新 + 同步本 skill
  - 反复有人在 skill 里踩坑 → 把易错点加进来
  - 触发词不准 → 调整
  
  skill 是**活的**，不是写完就丢。
  
  ## 8. Slash Command 怎么加
  
  slash command = 在 plugin 的 `commands/` 下放 markdown，YAML frontmatter 声明 `description / allowed-tools`。
  
  ```markdown
  ---
  description: "一句话说清。"
  allowed-tools: ["Bash", "Read", "Write"]
  ---
  
  # /<command-name>
  
  详细行为描述。
  

输入参数从用户消息里识别，由 LLM 自己解析。

命名：统一用裸命令名 /<command-name>（团队命令均唯一）；多 plugin 下如需消歧，用官方 /<plugin-name>:<command-name>（如 /czerp-workflow:openspec-new）。不要用 /czerp: 这类非 plugin 名前缀（无效，不会触发）。

9. 上线后的"用前几次"测试

• 让 3 名团队成员实际用一次
• 收集"触发不稳定"/"代码示例不准"/"易错点没覆盖到"的反馈
• 一次性修正后再宣传

10. 与外部 plugin 的关系

• Superpowers：通用能力，不重复
• Anthropic 官方：official marketplace 的 plugin，按需引用，不重复
• 本仓库：czerp 项目特有

发现有重叠 → 用 plugins/czerp-workflow/skills/openspec-superpowers-bridge 模式：显式声明衔接关系，不互相替代。