多 Skill 协同：如何系统性地组织与管理多个 Claude Skill

{动词}-{操作对象}[-{修饰语}]

{命名空间}/{skill-name}

content/write-post-hugo
content/write-newsletter
content/rewrite-seo
content/translate-zh-en

data/clean-csv
data/analyze-excel
data/generate-chart

code/review-security
code/generate-tests
code/refactor-python

skills/
├── pdf-converter/
│   └── SKILL.md
├── report-generator/
│   └── SKILL.md
└── code-reviewer/
    └── SKILL.md

skills/
├── public/                    # 团队共享的通用 Skill
│   ├── document/
│   │   ├── docx/
│   │   ├── pdf/
│   │   └── xlsx/
│   ├── code/
│   │   ├── review/
│   │   └── generate/
│   └── content/
│       ├── hugo-writer/
│       └── newsletter/
├── private/                   # 个人定制 Skill
│   └── my-workflow/
└── shared-resources/          # 跨 Skill 共享资源
    ├── scripts/
    │   ├── file_utils.py
    │   └── format_converter.sh
    ├── references/
    │   └── style-guide.md
    └── assets/
        └── company-logo.png

## 执行步骤

1. 使用共享格式转换脚本处理输入文件：
   ```bash
   python /mnt/skills/shared-resources/scripts/file_utils.py \
     --input $INPUT_PATH \
     --format docx
   
   （此脚本由团队统一维护，位于 shared-resources/scripts/）

2. 参考团队写作风格指南（仅在需要调整语气时读取）：
   路径：`/mnt/skills/shared-resources/references/style-guide.md`

skills/
└── public/
    └── report-generator/
        ├── SKILL.md           # 当前版本
        ├── CHANGELOG.md       # 变更日志
        └── snapshots/
            ├── v1.0/
            │   └── SKILL.md
            └── v1.5/
                └── SKILL.md

# report-generator 变更日志

## v2.0（2026-03-22）
- 重写 description，触发率从 62% 提升至 89%
- 添加 Excel 数据源支持
- 拆分参考文档到 references/ 子目录

## v1.5（2026-01-10）
- 修复空数据集时的崩溃问题
- 优化输出文档的页眉格式

## v1.0（2025-11-01）
- 初始版本

# Skill A
description: >
  处理财务类报告文档（损益表、资产负债表、现金流量表等）。
  触发词：财务报告、年报、季报、财务分析文档。
  注意：通用报告请使用 report-generator Skill，本 Skill 专用于财务场景。

# Skill B  
description: >
  生成通用业务报告（项目报告、运营报告、进度报告等）。
  触发词：业务报告、项目总结、运营周报。
  注意：财务相关报告请使用 financial-report Skill。

# 通用 Skill（兜底）
description: >
  用于生成各类文档报告。如果有更专门的 Skill（如 financial-report、
  legal-brief、technical-spec），优先使用专门的 Skill。
  本 Skill 作为通用兜底，处理没有专门 Skill 覆盖的报告类型。

# 专用 Skill（优先）
description: >
  专门用于法律文书起草（合同、诉状、协议、法律意见书）。
  遇到任何法律文书相关请求，优先使用本 Skill 而非通用文档 Skill。

# Skill A
description: >
  从 Excel (.xlsx) 文件生成数据报告。当用户提供的是 Excel 文件时触发。

# Skill B
description: >
  从 CSV 文件生成数据报告。当用户提供的是 CSV 或 TSV 文件时触发。

# Skill 触发边界地图

## 文档类 Skill

| Skill 名称 | 触发场景 | 不触发场景 |
|-----------|---------|-----------|
| docx | Word文档创建/编辑、专业报告、带格式的长文档 | PDF、纯文本、演示文稿 |
| pdf | PDF创建/读取/合并/分割 | Word文档、表格 |
| xlsx | Excel文件操作、数据表格 | Word文档、CSV清洗 |
| pptx | 演示文稿、幻灯片 | 文档报告 |

## 内容创作类 Skill

| Skill 名称 | 触发场景 | 不触发场景 |
|-----------|---------|-----------|
| hugo-writer | Hugo博客文章、带frontmatter的Markdown长文 | 简单文本回答、短段落 |
| newsletter | 邮件通讯、营销邮件 | 博客文章 |
| seo-rewrite | 现有内容的SEO优化改写 | 原创内容创作 |

## 决策树

遇到"写文章"类请求：
→ 需要发布到Hugo博客？→ hugo-writer
→ 需要发布为邮件通讯？→ newsletter  
→ 改写现有文章提升SEO？→ seo-rewrite
→ 都不是？→ 使用通用写作能力，无需Skill

原始数据 → [data-cleaner] → 清洁数据 → [report-generator] → 报告草稿 → [docx-formatter] → 最终文档

## 输出规范

本 Skill 的输出文件保存为 `/tmp/pipeline/{task-id}/clean-data.json`，
格式遵循 `shared-resources/references/data-schema.md` 中定义的标准结构。
下游 Skill（如 report-generator）可以直接读取此文件。

多源数据集
├── [analyze-sales-data]    → 销售分析
├── [analyze-user-data]     → 用户分析
└── [analyze-ops-data]      → 运营分析
                    ↓
            [synthesis-skill] → 综合报告

## 文档生成决策逻辑

检查请求类型：
- 如果目标格式是 .docx → 使用 docx Skill
- 如果目标格式是 .pdf → 使用 pdf Skill  
- 如果目标是 Hugo 博客 → 使用 hugo-writer Skill
- 如果目标是 PowerPoint → 使用 pptx Skill
- 如果格式不明确 → 询问用户

---
name: document-router
description: >
  当用户需要创建任何类型的文档，但没有明确指定格式或工具时触发。
  本 Skill 分析请求意图，将任务路由到最合适的专门 Skill。
  触发词：创建文档、生成文件、写报告（当格式不明确时）。
---

## 路由逻辑

分析用户请求，确定最合适的目标 Skill：

### 判断维度
1. **格式信号**：用户提到了 Word/PPT/PDF/Excel/Markdown？
2. **用途信号**：博客/演讲/分析报告/通讯/合同？
3. **规模信号**：单页/多页/完整演示/长文？

### 路由规则
| 判断结果 | 路由到 |
|----------|-------|
| Word / 专业文档 / 需要精确格式 | docx Skill |
| 演讲 / 汇报 / 幻灯片 | pptx Skill |
| 数据表格 / 财务数据 | xlsx Skill |
| 博客 / Hugo / Markdown长文 | hugo-writer Skill |
| 格式无明确要求的短文本 | 直接生成，无需专门Skill |

### 执行
确认路由方向后，告知用户"我将使用[Skill名称]来处理这个任务"，
然后按照对应 Skill 的规范执行。

shared-resources/
├── scripts/              # 可执行脚本
│   ├── file_utils.py     # 文件读写工具函数
│   ├── format_check.sh   # 格式验证脚本
│   └── README.md         # 脚本说明（包括参数文档）
│
├── references/           # 参考文档
│   ├── style-guide.md    # 写作风格指南
│   ├── brand-voice.md    # 品牌语调规范
│   ├── data-schema.md    # 中间数据格式定义
│   └── api-docs/         # 外部 API 文档快照
│
├── assets/               # 静态资源
│   ├── logo.png
│   ├── template.docx     # Word 模板
│   └── fonts/
│
└── MANIFEST.md           # 共享资源清单与使用说明

# 共享资源清单

## 脚本

### file_utils.py
用途：统一的文件读写工具，处理路径规范化、编码检测、格式验证
使用方法：`python /mnt/skills/shared-resources/scripts/file_utils.py --help`
被以下 Skill 使用：docx, pdf, xlsx, report-generator

### format_check.sh
用途：验证输出文件是否符合格式规范
使用方法：`bash /mnt/skills/shared-resources/scripts/format_check.sh <file_path>`
被以下 Skill 使用：所有文档生成类 Skill

## 参考文档

### style-guide.md（全量加载：约 80 行）
何时读取：任何需要调整写作语气、格式规范的场景
覆盖内容：标题层级规范、标点用法、术语表

### data-schema.md（按需读取：约 150 行，含目录）
何时读取：当 Skill 需要产生或消费管道中间数据时
覆盖内容：标准 JSON 结构、字段类型定义、示例数据

# file_utils.py 版本管理示例

def convert_file(input_path, output_format, **kwargs):
    """
    v2.0 新增 encoding 参数，但默认值保证向后兼容
    v1.x 的调用方式仍然有效
    """
    encoding = kwargs.get('encoding', 'utf-8')  # 新参数，有默认值
    # ...

scripts/
├── file_utils.py          # 当前版本（v2.0）
├── file_utils_v1.py       # 保留旧版本，供仍依赖它的 Skill 使用
└── MIGRATION.md           # 从 v1 迁移到 v2 的指南

# 向 Skill 库贡献新 Skill

## 提交前检查清单

- [ ] 命名符合 `{动词}-{名词}[-{修饰语}]` 规范
- [ ] description 字段包含至少 3 个具体触发场景
- [ ] 包含至少 5 个测试用例（覆盖正常路径和至少 1 个边界情况）
- [ ] 与现有 Skill 的边界已明确（在 description 中写明不处理哪些场景）
- [ ] 共享资源通过 shared-resources/ 引用，而非复制
- [ ] CHANGELOG.md 已创建，记录初始版本信息
- [ ] 已在 SKILL-MAP.md 中更新边界说明

## 提交后流程

1. 通知团队审查
2. 等待至少 24 小时，收集反馈
3. 处理审查意见
4. 合并后通知所有 Skill 使用者

description: >
  [已废弃，请使用 new-report-generator Skill]
  原有 report-generator Skill，2026-06-01 后将不再维护。

skills/
├── writer/           # "通用写作"，description 极其宽泛
├── blog-helper/      # "帮助写博客"，与 writer 高度重叠
├── formatter/        # 格式化文档，但不清楚支持哪些格式
├── seo/              # SEO 相关，但包含了写作和优化两个功能
├── translator/       # 翻译
├── newsletter2/      # newsletter 的 v2，旧版 newsletter 也还在
└── newsletter/       # 旧版，已废弃但没有标记

shared-resources/
├── references/
│   ├── brand-voice.md      # 从 writer、newsletter 里提取的品牌语调
│   └── style-guide.md      # 从 formatter 里提取的格式规范
└── assets/
    └── templates/
        └── newsletter-template.html  # 从 newsletter2 里提取

skills/
├── public/
│   ├── write-post-hugo/
│   ├── write-newsletter/
│   ├── rewrite-seo/
│   ├── rewrite-tone/
│   ├── translate-content/
│   └── format-document/
├── shared-resources/
│   ├── references/
│   └── assets/
└── archived/             # 旧 Skill 归档
    ├── writer/
    ├── blog-helper/
    ├── formatter/
    ├── seo/
    ├── translator/
    ├── newsletter/
    └── newsletter2/