Skill Authoring Workflow

Skill Authoring Workflow

Overview

不规范的 skill 是静默的错误指导——agent 加载后可能漏步骤、用错工具、或跳过关键校验。这套工作流确保每个 SKILL.md 的触发条件精确、步骤可执行、检查项可验证，避免"写完但不知道怎么用"的烂尾。

两套流程写 skill。简单 skill（单领域、≤5 步、边界清晰）走快速通道（3 步，~500 token 流程开销）。复杂 skill（多分支、含铁律、跨领域）走完整 6 阶段（见 references/full-workflow.md）。

> ⚠️ ~500 token 指流程开销，不含正文写作。 > 正文按下方 Token Budget 表算——Reference 最少 2K、Technique 最少 5K。 > 快速通道省的是完整 6 阶段的 3K+ token 决策流程，不是正文内容。

本 skill 支持多平台（Hermes Agent / Claude Code / Codex CLI / Cursor）。工具名和路径因平台而异——详见 references/platform-adapters.md。

When to Use

| Use When | Don't Use When | |----------|----------------| | 用户说"写个 skill""帮我创建 SKILL.md""把这个流程写成 skill" | 只是修改现有 skill 的一小段（直接编辑即可） | | 用户说"这个工作流应该变成 skill""帮我封装成 skill" | 用户只是问"skill 格式是什么""description 怎么写"（直接回答，不需要走流程） | | 用户给了一份设计文档，要求实现为 skill | 写 skill 之外的代码（如实现功能本身） | | 新 skill 写完准备交付，需要验证质量 | 用户说"随便写写，不用规范"（质量要求由用户取消） | | 需要把 skill 从 Hermes 迁移到 Claude Code / Cursor | 只是查询已有的 skill 怎么用（加载解释即可） |

快速通道 vs 完整流程（先看这里）

你的 skill 特征是？
  │
  ├── 简单 skill（满足 ≥3 项）
  │     ├── 单引擎/单领域、边界清晰、步骤 ≤ 5、无多分支
  │     └── → 快速通道：分类 → 草稿 → 一键验证（~500 token 流程开销，正文另算）
  │
  └── 复杂 skill（满足 ≥2 项）
        ├── 多引擎/跨领域、含铁律、步骤 > 5、需查重
        └── → 完整流程（6 阶段，~3k token）
              详见 references/full-workflow.md

快速通道

快1：分类

用下方 Phase 0 类型决策树判定类型，输出 1 行结论。

用户的 skill 是用来______？
  ├─ 强制执行规则/纪律 → Discipline-enforcing（特征词：必须、禁止、不能）
  ├─ 教怎么做一件事 → Technique（特征词：怎么做、步骤、流程、命令）
  ├─ 提供思维框架 → Pattern（特征词：思路、框架、模型、判断）
  └─ 查阅信息/规范 → Reference（特征词：参考、速查、字段、参数）

Expected Output: 类型: + 一句话理由

快2：草稿

从 references/body-templates.md 选对应模板，直接填。保留 section：Overview / When to Use / Core Workflow / Common Pitfalls / Verification Checklist。跳过的 section：Rationalization Table / No Exceptions / 5×5 Trigger 矩阵。

命名规则（硬性）：- 或 -，全小写+连字符，≤ 64 字符。禁止 how-to-、skill-、-helper、-tool 前缀/后缀。Category 从 16 个枚举值选（见 references/full-workflow.md §Phase 2.3）。

Expected Output: SKILL.md 草稿文件（含 frontmatter + 5 个必选 section）

快3：一键验证

# 所有平台通用：终端中运行
python3 scripts/validate-skill.py 

8 项全过 → 跳到「交付」。有失败 → 修复后重跑。

Expected Output: validate-skill.py 8/8 通过，或具体失败项清单

---

核心规则（快速通道和完整流程都要遵守）

Frontmatter

---
name:                     # ≤ 64 chars, 全小写+连字符
description: Use when .     # ≤ 1024 chars, 只写 WHEN，不写 WHAT
version: 1.0.0
metadata:
  tags: [3-5个名词标签]
  related_skills: [真实存在的 skill 名]
---

Description 铁律

只写触发条件，不写流程。 Agent 扫描 skill 时，如果 description 已经写了怎么做（如 "Use when X — step1: check config, step2: build"），agent 用 description 信息执行，不再读正文——所有精心内容白费。

❌ BAD: "Use when debugging Python — use pdb, check logs, isolate the bug, fix it"
   → agent 看到 pdb/check/isolate/fix，以为全懂了，跳过正文

✅ GOOD: "Use when a Python process crashes with an unclear traceback or hangs indefinitely"
   → agent 只知道什么时候触发，必须读正文

自查：description 出现破折号+操作动词（runs/checks/builds/creates）、逗号分隔步骤、工具名（pdb/kubectl）、流程术语（pipeline/workflow）→ 重写。

When to Use 格式

| Use When | Don't Use When |
|----------|----------------|
| 场景（含触发关键词） | 反场景（含排除关键词） |

每条 Use When 含 ≥1 个可匹配关键词。Don't Use When 列 ≥ 3 条。

风格选择

你的 skill 是什么类型？
  │
  ├── Reference / Pattern / Discipline-enforcing → Hermes 原生
  │     （5 字段 frontmatter，Markdown 表格，Bad/Good 对照）
  │
  └── Technique / 混合型，> 8k chars，有分支决策
        │
        └── → Addyosmani 极简（见 references/addyosmani-minimalist-style.md）
              （2 字段 frontmatter，ASCII 决策树，验证信号对照表）

先对标再下笔。 去 GitHub 找 1-2 个同领域爆火 skill（addyosmani/agent-skills、ComposioHQ/awesome-claude-skills），git clone --depth 1 拉下来读 2-3 个 SKILL.md。风格差距大 → 调整模板选择，别等写完再推倒。

Token Budget

| 类型 | 目标 | 上限 | |------|------|------| | Discipline | 5-10k | 12k | | Technique | 5-12k | 15k | | Pattern | 8-14k | 16k | | Reference | 2-10k | 12k |

缩短口诀：砍 Expected 输出 → 首句传核心 → 补或删无修复的 Pitfall → 合并重复信息。

---

参考模型速查

写新 skill 时，找 1-2 个已完成的高质量 skill 做结构参照。优先选同类型的——Technique 参照 Technique，Discipline-enforcing 参照 Discipline-enforcing。

推荐外部参考（GitHub）：

• addyosmani/agent-skills — 30+ 生产级 skill，Addyosmani 极简风格发源地
• ComposioHQ/awesome-claude-skills — 精选 skill 索引

用你项目里已有的高质量 skill： 用 skill_view(name) 加载 1-2 个同类型的查看结构，分析它们的 description 写法、章节顺序、代码块风格、验证方式，然后对标。

---

Common Pitfalls

| # | 错误 | 修复 | |---|------|------| | 1 | When to Use 太泛 | 具体化："Use when about to run kubectl apply against production" | | 2 | 命令缺完整路径 | 写完整：./scripts/deploy.sh --check | | 3 | Expected 模糊："应该显示成功" | 给样例："Build ID: abc123" | | 4 | 步骤间没依赖说明 | 每步加 Why（1 句） | | 5 | Pitfall 只有"可能出错"，没收尾 | 三段式：错误现象 → 原因 → 修复命令 | | 6 | 跳过分类直接写 | 强制先走类型决策树 | | 7 | 只有正面指导，没 Red Flags | 针对每种自我欺骗加一条 Red Flag | | 8 | description 抄了另一个 skill 句式 | 为每个 skill 从头设计触发条件 | | 9 | related_skills 编造不存在的 skill 名 | Phase 2 查重时验证 | | 10 | 交付前没跑验证，凭感觉说"没问题" | 跑 scripts/validate-skill.py | | 11 | 闭门造车，不知道外面流行什么风格 | 先对标外部标杆再下笔 | | 12 | 简单 skill 走了完整 6 阶段 | 先判断复杂度，选快速通道 | | 13 | 以为快速通道能省正文 token | 流程开销 ≠ 正文开销。正文按类型 budget 算，不因快速通道变少 |

---

Red Flags

脑子里出现以下想法——停下来：

| # | Red Flag | 为什么危险 | |---|---------|-----------| | 1 | "太简单了，不需要走完整流程" | 简单 skill 结构更需要精确 | | 2 | "我先写了再说，写完再分类" | 先写后分类 = 先盖房再画图 | | 3 | "验证可以跳过，反正看起来是对的" | Skill 的 bug 是静默的错误指导 | | 4 | "description 写了流程但 agent 也会读正文的" | Agent 不会。desc 有流程 = 正文白写 | | 5 | "再加一个 Worked Example" | 第 3 个 example 边际价值趋近零 | | 6 | "用户没提边界条件，我就不写了" | Agent 会遇异常——你得替它想 | | 7 | "和已有 X 有点像但我懒得引用" | Agent 不知道该用哪个，可能选错 | | 8 | "写得优雅一点而不是那么啰嗦" | 优雅 = 模糊。正确性 > 优雅性 | | 9 | "这步简单，不需要 Expected 输出" | 没有 Expected = agent 不知道做对了没 |

---

Verification Checklist

交付前逐项确认：

格式

• [ ] 文件以 --- 开头（无 BOM）
• [ ] Frontmatter 闭合，YAML 有效
• [ ] name ≤ 64 chars，全小写+连字符
• [ ] description ≤ 1024 chars，"Use when" 开头，无流程摘要
• [ ] 文件长度在类型上限以内

Trigger

• [ ] 5 该触发场景全部匹配
• [ ] 5 不该触发场景全部拦截
• [ ] Don't Use When ≥ 3 条

Content

• [ ] Overview ≤ 3 句
• [ ] 所有命令精确可执行
• [ ] 关键步骤有 Expected 输出
• [ ] 无模糊词：应该、可能、通常、一般、大概
• [ ] Common Pitfalls ≥ 3 条，每条有完整事件→原因→修复链路
• [ ] related_skills 引用真实存在
• [ ] 没落入 8 个反模式（见 references/full-workflow.md）

---

Interaction with Other Skills

本 skill 是 pipeline 的起点——写完后自动进入审查和部署流程。

| 下游 Skill | 触发时机 | 加载方式 | |------------|---------|---------| | skill-review-workflow | SKILL.md 草稿完成、validate-skill.py 通过后 | 自动进入 Stage 2 | | agent-security-guard | skill-review 发现安全相关问题时 | skill-review 自动触发 | | skill-pipeline-orchestrator | 审查通过后，用户说"一键发布" | 用户主动触发 Stage 1-5 |

Pipeline 入口：

写 skill → skill-authoring-workflow（本 skill）
         → validate-skill.py 通过
         → skill-review-workflow（23 项审查）
         → skill-pipeline-orchestrator（一键发布）

---

交付

将 SKILL.md 写入对应平台的 skills 目录：

| 平台 | 路径 | |------|------| | Hermes Agent | ~/.hermes/skills///SKILL.md | | Claude Code | ~/.claude/skills//SKILL.md | | Codex CLI | ~/.codex/skills//SKILL.md | | Cursor | ~/.cursor/skills//SKILL.md |

目标已存在 → 先问用户。保存后输出 Quality Scorecard：

Trigger Precision:  _/5 ×2 = __
Actionability:     _/5 ×3 = __
Completeness:      _/5 ×2 = __
Conciseness:       _/5 ×1 = __
Verifiability:     _/5 ×2 = __
总分: __/50（≥20 可交付，≥40 优秀）

---

Step 6: 迭代（Iterative Refinement）

Skill 交付后不是终点——实际使用中会发现遗漏和偏差。

交付完成 → 实际使用 → 发现问题
                          │
                          ├── 触发词漏了 → 更新 description
                          ├── 步骤有歧义 → 加 Expected Output 或示例
                          ├── 平台工具错 → 检查 references/platform-adapters.md
                          ├── 新增场景 → 补 When to Use 和 Common Pitfalls
                          └── 用户反馈"不对" → 回溯步骤，改正文或 Iron Law

迭代触发条件：

• 同一问题被问 3 次以上 → description 漏了触发词
• 用户说"这不是我想要的"→ Overview 或 When to Use 不准确
• validate-skill.py 发现新失败项 → 更新验证清单
• 用户明确说"帮我把这个 skill 改一下"→ 走 skill-authoring-workflow 全流程

迭代原则：

• 小改直接编辑，不用走完整 6 阶段
• 大改（新增章节、改类型、加 Iron Law）走完整流程
• 每次迭代后重新跑 validate-skill.py

---

延伸阅读

• references/full-workflow.md — 完整 6 阶段流程（Phase 0-5、Iterative Refinement、8 反模式、Quality Scorecard）
• references/body-templates.md — 4 种类型的写作模板
• references/addyosmani-minimalist-style.md — Addyosmani 极简风格指南
• references/platform-adapters.md — 多平台工具/路径映射（Claude Code / Codex / Cursor）
• scripts/validate-skill.py — 8 项格式一键检查

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 2702207741-dev
• Source: 2702207741-dev/agent-skills-pipeline
• License: MIT
• Homepage: https://github.com/2702207741-dev/agent-skills-pipeline/blob/main/docs/README.md

Install and usage instructions live in the source repository linked above.