将已有技能重构为 Hermes-Agent 规范格式

将超大或不合规的技能逆向工程为同行匹配格式，使 SKILL.md 控制在 8-15k 范围内，详细内容分解到 references/。当技能自然增长（实战笔记、内联 CSS、嵌入代码）导致 SKILL.md 膨胀到 25-50k 字符时尤为有用。

何时使用

• 技能的 SKILL.md 超过 20k 字符（同行范围为 8-15k）
• 用户要求"按规范整理"、"标准化"、"提炼成标准 skill"或"总结提炼"
• 内容自然增长，大量内联代码块本应属于 scripts/
• 多个"决策树"或"规则表"跨章节重复
• 技能的 SKILL.md 难以快速浏览或更新（每次修改都要触碰一个巨大的文件）

不要用于：
- 新建技能（请直接使用 hermes-agent-skill-authoring）
- 已在规范内的技能（SKILL.md 8-15k、references/ 已分解、验证通过）
- 有意保持密集的技能（如安全/合规类引用）

工作流

1. 调查现有技能

SKILL_DIR=~/.hermes/skills/<category>/<skill-name>
ls -la $SKILL_DIR/
wc -c $SKILL_DIR/SKILL.md $SKILL_DIR/references/*.md $SKILL_DIR/scripts/*.py

完整阅读现有 SKILL.md。注意：
- 所有 ## 章节及其长度
- 可移至 scripts/ 或 references/ 的代码块
- 被多处引用的表格（需要去重的候选）
- 出现多次的"决策树"（需要单源真相的候选）

2. 加载规范（hermes-agent-skill-authoring）

skill_view name=hermes-agent-skill-authoring

规范中的关键约束：
- SKILL.md 必须以 --- 开头，以 \n---\n 结尾
- name ≤ 64 字符，小写+连字符
- description ≤ 1024 字符，必须以"Use when ..."开头
- 必须包含 version、author、license、metadata.hermes.{tags, related_skills}
- 总文件 ≤ 100,000 字符
- 同行范围：8-15k 字符（仓库内 software-development/ 技能的标准）
- 结构：# 标题 → ## 概述（或介绍段落）→ ## 何时使用 → 正文 → ## 常见陷阱 → ## 验证清单 → ## 参考资料（表格）

3. 规划拆分

找出现有 SKILL.md 中 3-5 个最大的独立主题。每个候选移至 references/*.md 的条件：
- 是一个连贯的主题（不是随意拼凑的章节）
- 在新 SKILL.md 中按名称引用
- 至少 2-3k 字符（否则拆分的开销超过节省的成本）
- 有自然的前言/边界（如"CSS 修复"、"降噪器"、"IMA 错误码"）

常见的拆分模式：

4. 编写新的 SKILL.md（目标 8-15k）

结构（严格按此顺序）：

---
name: <skill-name>
description: "<trigger-class description, ≤ 1024 chars, 'Use when ...'>"
version: 2.0.0  # bump from 1.x
author: <original author>
license: <original license>
platforms: [<original platforms>]
metadata:
  hermes:
    tags: [<original tags>]
    related_skills: [<original related>]
---

<!--
📋 以下为新 SKILL.md 的**模板示例**（英文版，供国际化参考）
   实际章节见上文"## 何时使用"（L22）和"## 工作流"（L35）
   本模板的目的是让读者看到"完整 SKILL.md 长什么样"
   不是本技能的章节内容
-->

# <Skill Name>

<One-paragraph overview. Lead with what it does + why it matters. End with a battle-tested quote if available.>

## When to Use

- <Trigger 1>
- <Trigger 2>
- <Trigger 3>

**Don't use for:**
- <Counter-trigger 1>
- <Counter-trigger 2>

## Quick Start

### Mode 1: <Self-contained mode>

```bash
<short command>

Mode 2: <Batched / dependent mode>

<short command sequence>

Required fields: <list>

Filtering rule: <the actual selector, e.g. media_id.startswith('wechatarticle_')>

How It Works (Architecture)

<ASCII art diagram or short prose. 5-10 lines max.>

Two/three key design decisions:
- <bullet 1>
- <bullet 2>
- <bullet 3>

The N Mechanisms (injected / applied / etc.)

Detail table (if levels exist, e.g. noise stripper):

Why X over Y: <one sentence about the design rationale>

Common Pitfalls

1. <Symptom> — <one-line cause + fix>. → full table in references/<topic>.md
2. <Symptom> — <one-line cause + fix>. <Recovery options.>
...

(7-9 pitfalls, each 1-3 lines, deduplicated. Move topic-specific deep-dives to references.)

Verification Checklist

Per <unit>:
- [ ] <Check 1>
- [ ] <Check 2>

Automated smoke test:

<short script>

Per <rule> (after modifying):

→ full pattern in references/injection-testing.md (of the target skill, not this one)

Per <batch>:
- [ ] <Check 1>
- [ ] <Check 2>

References

Scripts

Related Skills

• <other-skill> — <why it's related>

vX.X Changelog (this version)

Restructured for peer-matched format:
- <Bullet 1>
- <Bullet 2>
- ...

No behavior change: <list the things that didn't change>

### 5. 编写引用文件（每个 2-9k）

为每个拆分出的引用文件使用以下模板：

```markdown
# <Topic Name>

<One-paragraph intro.>

## <Subtopic 1>

<content>

## <Subtopic 2>

<content>

## <Pitfall (if topic-specific)>

<content>

## <Reusable code / regex (if any)>

```python
<code with comments>

Related

• SKILL.md §"<section name>" — <one-line pointer>
• <other-ref>.md — <why related>

每个引用文件保持在 **2-9k 字符**（足够小以在一屏内阅读，足够大以保证有用）。

### 6. 验证新结构

运行验证脚本（本技能提供）：

```bash
python scripts/validate_skill.py /path/to/SKILL.md

失败处理（按错误类型，触发条件 → 一线修复 → 兜底）：

• Frontmatter 解析失败 → 检查首行是否为 ---（无 BOM/无前置空白）→ 用编辑器重写 frontmatter
• 缺少必需字段 → 在 frontmatter 中补全 6 个字段（name/description/version/author/license/metadata）→ 复制本技能 frontmatter 模板
• name 格式错误 → 仅允许小写字母+连字符+数字（1-64 字符）→ 下划线/大写/中文会触发，改成 kebab-case
• description 超 1024 字符 → 精简 description，保留触发关键词 → 把详细说明移到 description 之外
• SKILL.md 超 15K 字符 → 进一步拆分到 references/*.md → 参见 Step 3-4 拆分模式
• 缺必需章节 → 补 ## When to Use/## Common Pitfalls/## Verification Checklist → 参考 v2.0 更新日志前的章节结构
• 引用的 references 文件不存在 → 拆分时遗漏，新建占位文件 → 更新链接或删除引用

脚本本身跑不动（极少见）：

• 脚本无外部依赖（纯 stdlib），如报 ModuleNotFoundError → 用 python3 重试
• 如挂起（>5s 无输出）→ 按 Ctrl+C 中断，检查 Python 版本 ≥3.8

查看源码（scripts/validate_skill.py）— 约 140 行 stdlib Python（无外部依赖），运行 <100ms。检查逻辑故意设计为可直接复制粘贴，方便你根据项目特定需求进行适配。

7. 升级版本 + 添加更新日志

在新的 SKILL.md 中：
- version: 2.0.0（升级主版本号 — 结构重组对直接依赖文件大小的使用者是破坏性变更）
- 在末尾添加 ## v2.0 更新日志（当前版本） 章节，列出：
- 重构为同行匹配格式： 要点
- 行为无变化： 要点

示例：wechat-article-fetcher v1.4 → v2.0

重构前： SKILL.md 31,790 字符（单文件，16 章节，4 个包含完整 CSS 代码的内联修复，11 个陷阱，2 个内联 H5 组件表）

重构后：
- SKILL.md：13,258 字符（10 章节，4 个修复以表格形式汇总，9 个陷阱，6 个引用表）
- references/css-fixes.md：8,692 字符（3 个修复包含完整 CSS 代码）
- references/noise-stripper.md：9,347 字符（3 级×12 规则表，堆栈匹配器代码）
- references/injection-testing.md：8,604 字符（4 个 H5 表单夹具，结构正则模式）
- references/ima-api-codes.md：3,194 字符（未变）
- references/wechat-discovery.md：5,620 字符（未变）
- references/wechat-h5-components.md：7,276 字符（未变）
- 4 个脚本（未变）

缩减效果： SKILL.md 31,790 → 13,258（缩小 58%，100% 符合规范）
信息： 完整保留在拆分后的引用文件中
行为： 未变

重构后：考虑发布

将技能重构为同行格式是发布到 SkillHub 的好时机（新结构 + 版本升级 = 有意义的发布）。工作流：

1. 添加两个仓库内 hermes 验证器不要求但 SkillHub 需要的 frontmatter 字段：
   yaml slug: my-skill-name # URL 安全标识符（在 SkillHub 中唯一） displayName: "My Skill Name" # 人类可读名称，通常本地化
2. skillhub auth login --token skh_...（一次，本地）
3. skillhub publish <skill-dir> --version 2.0.0 --changelog "..." --dry-run
4. 如果 dry-run 通过，skillhub publish <skill-dir> --version 2.0.0 --changelog "..." --json（正式发布）
5. 如果 slug 与上游 clawhub 源冲突，重命名 slug（保留 name），重新 dry-run
6. 发布任务完成后轮换 token

完整工作流 + 3 种 dry-run 失败模式 + token 安全指南见 publish-skill-to-skillhub 技能。

常见陷阱（重构本身）

1. 拆分时丢失内联代码

将代码块从 SKILL.md 移至引用文件时，确保代码仍然可以复制粘贴并运行。不要只说"参见脚本"——引用文件应包含实际的代码/正则，并附注释。

2. SKILL.md 与引用文件内容重复

SKILL.md 应概括（一行、一个表格行）。引用文件应详述（完整代码、完整表格、完整示例）。如果 SKILL.md 包含与引用文件相同的内容，那是重复而非拆分。

3. 行为未变却升级版本至 2.0

结构重组对依赖文件大小的使用者（CI lint 检查、diff 审查）是破坏性变更，因此升级主版本号。如果行为也同时改变，则升级两次。更新日志中的"行为无变化"行使其明确。

4. 忘记更新 metadata.hermes.related_skills

如果新 SKILL.md 引用了现有 related_skills 中没有的技能，请添加。反之亦然：如果引用文件引用了其他技能，它们也应出现在 metadata 中。

5. "只超了一点" 15k 同行范围

如果你的新 SKILL.md 是 18k，它就不在同行范围内。要么将更多内容拆分为引用文件，要么接受该技能确实需要更大的空间（很少见——通常表明需要进一步拆分）。

验证清单

• [ ] 新 SKILL.md 在同行范围内（8-15k 字符）
• [ ] 所有 6 个必需的 frontmatter 字段存在（name、description、version、author、license、metadata）
• [ ] description ≤ 1024 字符
• [ ] 全部 3 个关键章节存在（When to Use、Common Pitfalls、Verification Checklist）
• [ ] 所有链接的 references/*.md 文件存在
• [ ] SKILL.md 与引用文件之间无内容重复（概括 vs 详述）
• [ ] 版本升级至 2.0.0 并包含 ## vX.X 更新日志 章节
• [ ] metadata.hermes.related_skills 已更新
• [ ] 验证脚本通过（参见工作流 §6）
• [ ] 总内容（SKILL.md + 引用文件）≈ 原始内容（无信息丢失）

v3.0 更新日志（当前版本）

鲁班 Quick 模式 3 轮打磨：

• 修 dim8 实测表现 bug（+3.5）：validate_skill.py 改用绝对路径解析，修复相对路径传入时 parent.name='' 误报
• 补 dim3 失败模式编码（+1.5）：Step 6 新增 7 种验证失败的 fallback 路径（frontmatter 解析/缺字段/name 格式/description 超长/超 15K/缺章节/引用文件缺失）+ 2 种脚本跑不动的兜底
• 精简 dim7 整体架构（+0.6）：合并"无外部依赖"重复表述，英文模板前加 HTML 注释让结构更清晰

总分提升： 78.4 → 85.0（+6.6）

行为无变化：
- 7 步工作流不变
- 所有现有拆分模式不变
- scripts/validate_skill.py 检查项不变（仅修路径处理 bug）
- 所有引用文件路径不变

v2.0 更新日志（此前版本）

重大中文化更新：
- displayName 改为中文「技能重构助手」
- description 改为中文描述
- 标签改为中文标签
- 正文所有英文内容（标题、描述、步骤、表格等）全部转换为中文
- 验证脚本中的代码注释改为中文

行为无变化：
- 所有工作流步骤、结构、拆分模式、验证逻辑不变
- 代码块、CLI 命令、文件名、技术参数保持原文

v1.2 更新日志（此前版本）

国际化：
- 将 displayName 从中文改为英文
- 版本从 1.1.0 升级至 1.2.0

行为无变化：
- 所有工作流步骤、结构和内容不变

v1.1 更新日志（此前版本）

规范合规修复（遵循 Anthropic Agent Skills 开放标准 2025-12-18）：
- 在顶层添加了 tags 字段（之前仅在 metadata.hermes.tags 中）
- 添加了 compatibility 字段，声明验证脚本需要 Python 3.8+
- 在 platforms 中添加了 windows（之前仅 linux/macos）
- 版本从 1.0.0 升级至 1.1.0

结构改进：
- 创建了 scripts/validate_skill.py——第 6 步中的内联 28 行验证代码现在是一个实际的、可运行的 140 行脚本（仅 stdlib，<100ms）
- 将 3 个占位符 markdown 链接（<topic>.md、<file>.md、<other-ref>.md）替换为内联代码，避免文件存在性检查器对模板示例产生误报
- 更新了 ## Scripts 表格中的真实脚本条目

行为无变化：
- 7 步工作流不变
- 所有同行匹配原则不变
- 实战示例（wechat-article-fetcher v1.4 → v2.0）不变

v1.0 更新日志（初始发布）

首次发布。包含 7 步工作流、拆分模式表、新 SKILL.md 模板、验证脚本（内联）、实战示例。