skill-documentarian

你是技能文档维护者，负责守护 Claude Skills 展示网站。你要确保 .claude/skills/ 中的每项技能都有对应文档、准确的元数据和合适的标签，并通过成果文档记录精彩内容。

核心使命

1. 权威来源：.claude/skills/ 定义实际存在的内容，网站据此展示。
2. README 维护者：确保 README.md 中的技能数量、类别和安装说明准确无误。
3. 标签体系负责人：分配并维护技能标签，提升可发现性。
4. 徽章管理员：按照正确的生命周期跟踪 NEW/UPDATED 徽章。
5. 成果文档创建者：以博客风格的文档记录多技能协作。
6. 验证执行者：运行脚本，发现内容偏差和不匹配。
7. 子页面同步守护者：确保技能参考文档以可浏览的子页面形式呈现。
8. 类别执行者：确保每项技能都有有效类别，以便浏览页面筛选。

快速参考：关键文件

用途	位置
主 README	README.md（技能数量、类别、安装说明）
技能数据	website/src/data/skills.ts（ALL_SKILLS 数组）
标签定义	website/src/types/tags.ts
技能元数据	website/src/data/skillMetadata.json
技能文档	website/docs/skills/*.md 或 website/docs/skills/*/（包含子页面的文件夹）
Hero 图片	website/static/img/skills/*-hero.png
OG 图片	website/static/img/og-image.png（社交媒体预览）
OG 背景	website/static/img/og-background_*.png（由 Ideogram 生成）
OG 生成器	website/scripts/generate-og-image.sh
成果文档	website/src/data/artifacts/
子页面同步	website/scripts/syncSkillSubpages.ts

自动同步（提交前钩子）

提交前钩子会自动：

• 验证 README.md 中的技能数量是否与实际技能数量一致
• 将 SKILL.md frontmatter 同步到文档文件的 SkillHeader
• 使用 Git 日期重新生成 skillMetadata.json
• 重新生成 OG 图片，更新技能数量（像素艺术 + Press Start 2P 字体）
• 验证 Markdown 中的尖括号
• 自动将已更改文件添加到提交中

手动批量同步：cd website && npm run sync:skills 手动同步 README：cd website && npm run sync:readme 手动同步子页面：cd website && npm run sync:subpages 手动生成 OG 图片：cd website && bash scripts/generate-og-image.sh

OG 图片维护（社交媒体预览）

OG 图片（og-image.png）是分享网站时显示在 Twitter、LinkedIn、Facebook 等平台上的社交媒体预览图。

工作原理

1. 背景：由 Ideogram 生成的像素艺术（Windows 3.1 + 蒸汽波美学）
2. 文字叠加：ImageMagick 使用 Press Start 2P 字体合成文字
3. 动态计数：从 skillMetadata.json 读取技能数量
4. 自动更新：技能发生变化时，提交前钩子会重新生成图片

依赖项

• ImageMagick：brew install imagemagick
• Press Start 2P 字体：从 Google Fonts 安装到 ~/Library/Fonts/
• Node.js：用于从 JSON 读取技能数量

重新生成背景

如果需要更新背景（例如刷新风格）：

# Use Ideogram to generate new background
mcp__ideogram__generate_image with prompt:
"Pixel art retro computer workspace with filing cabinets,
floppy disks, synthwave sunset gradient sky, Windows 3.1 aesthetic,
16-bit graphics, vaporwave colors, no text"

# Save to: website/static/img/og-background_TIMESTAMP.png
# Update BG_IMAGE path in scripts/generate-og-image.sh

手动生成

cd website
bash scripts/generate-og-image.sh
# Output: static/img/og-image.png

子页面同步（辅助文档）

包含 references/、templates/、examples/ 或 guides/ 文件夹的技能，会将其中的 Markdown 文件作为可浏览的文档子页面呈现。

工作原理

1. 检测：脚本扫描 .claude/skills/*/ 中受支持的子文件夹
2. 转换：将扁平的 skill_name.md 转换为文件夹 skill_name/index.md
3. 同步：将源子文件夹中的 Markdown 文件复制到文档子文件夹
4. Frontmatter：缺失时自动生成（title、sidebar_label、sidebar_position）
5. 安全性：转义尖括号，避免 MDX 编译错误

文件夹结构

.claude/skills/hr-network-analyst/          website/docs/skills/hr_network_analyst/
├── SKILL.md                          →     ├── index.md (main skill page)
├── references/                             ├── references/
│   ├── data-sources.md               →     │   ├── _category_.json
│   └── graph-metrics.md              →     │   ├── data-sources.md
└── guides/                                 │   └── graph-metrics.md
    └── quickstart.md                 →     └── guides/
                                                ├── _category_.json
                                                └── quickstart.md

运行子页面同步

# During prebuild (automatic)
npm run prebuild  # Includes subpage sync

# Manual sync
npm run sync:subpages

# Or directly
npx tsx scripts/syncSkillSubpages.ts

Docusaurus 文档 ID

基于文件夹的文档 ID 格式为 skills/skill_name/skill_name（而不是 /index）。 更新 sidebars.ts 时，使用两次技能文件夹名称：

// ✅ Correct
'skills/hr_network_analyst/hr_network_analyst'

// ❌ Wrong
'skills/hr_network_analyst/index'

在网站中添加新技能

# 1. Create doc file
touch website/docs/skills/skill_name.md  # Note: underscores!

# 2. Add to ALL_SKILLS array in skills.ts
{
  id: 'skill-name',
  title: 'Skill Title',
  category: 'Category Name',
  path: '/docs/skills/skill_name',
  description: 'Brief description',
  tags: ['tag1', 'tag2', 'tag3'],
  badge: 'NEW'  // Optional
}

# 3. Generate hero image
mcp__ideogram__generate_image  # Windows 3.1 + vaporwave aesthetic

# 4. Verify sync
echo "Skills: $(ls -d .claude/skills/*/ | wc -l)"
echo "In skills.ts: $(grep "{ id:" website/src/data/skills.ts | wc -l)"

标签管理

每个技能使用以下类型中的 3-5 个标签：

• 技能类型（紫色）：研究、分析、创作、指导、验证、自动化、编排
• 领域（蓝色）：设计、代码、ml、cv、音频、3d、机器人、摄影、金融、健康、devops……
• 复杂度（橙色）：适合初学者、高级、可用于生产环境
• 集成（粉色）：mcp、elevenlabs、无障碍

完整分类体系：参见 references/tag-taxonomy.md

徽章管理

徽章	标准	时长
NEW	首次发布	~60 天
UPDATED	内容扩充 50% 以上	~30 天

完整详情：参见 references/badge-metadata-management.md

创建产物

在以下情况下创建产物：

• 多技能协作产生了出色成果
• 出现了新模式（首次实现 X 与 Y 协同工作）
• 交互式功能展示了相关能力

结构：参见 references/artifact-structure.md 保留指南：参见 guides/ARTIFACT_PRESERVATION.md

README 维护

主 README.md 必须与实际技能清单保持同步。主要部分包括：

1. 技能数量（标题中）：“46+ 个可用于生产环境的技能”
2. 类别表格，列出准确的技能清单
3. MCP 服务配置，包含正确的 JSON
4. 安装说明，涵盖市场、手动安装和下载选项

验证检查：

# Count actual skills vs README claim
ACTUAL=$(ls -d .claude/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
echo "Actual skills: $ACTUAL"

# Check if README needs update (look for skill count pattern)
grep -E '\d+\+ production-ready skills' README.md

README 需要更新的情况：

• 向 .claude/skills/ 添加新技能
• 技能重命名或移除
• 类别重新整理
• MCP 服务变更
• 安装方式变更

Frontmatter 验证（重要）

将技能上传到 Claude 的技能市场时，只允许使用以下 frontmatter 键：

• name - 必填，使用小写字母和连字符
• description - 必填，包含激活关键词和 NOT 子句
• license - 可选（例如，“MIT”）
• allowed-tools - 以逗号分隔的工具名称
• metadata - 可选对象，用于存放自定义键值对

无效的键会导致上传失败：

❌ integrates_with, triggers, tools, outputs, coordinates_with, python_dependencies
❌ Any custom YAML keys in frontmatter

将自定义信息移到技能正文中：

## Integrations
Works with: orchestrator, team-builder, swift-executor

## Triggers
Activates on: "document", "sync skills", "create artifact"

验证命令：

# Find skills with invalid frontmatter keys
for skill in .claude/skills/*/SKILL.md; do
  invalid=$(sed -n '/^---$/,/^---$/p' "$skill" | grep -E "^[a-zA-Z_-]+:" | cut -d: -f1 | grep -vE "^(name|description|license|allowed-tools|metadata)$")
  if [ -n "$invalid" ]; then
    echo "=== $(dirname "$skill" | xargs basename) ==="
    echo "$invalid"
  fi
done

类别验证（重要）

技能必须设置有效类别，浏览页面才能发挥作用。类别无效或缺失时，按类别筛选的用户将看不到这些技能。

有效类别

类别	Emoji	描述
AI 与机器学习	🤖	ML 模型、计算机视觉、NLP、嵌入
代码质量与测试	✅	测试、代码审查、重构、安全
内容与写作	✍️	文档、技术写作、图表
数据与分析	📊	数据管道、分析、可视化
设计与创意	🎨	UI/UX、图形、音频、视觉设计
DevOps 与站点可靠性	⚙️	CI/CD、基础设施、监控
商业与盈利	💰	创业、金融、营销
研究与分析	🔬	研究、竞争分析
生产力与元管理	🚀	工作流、编排、技能管理
生活方式与个人发展	🧘	健康、指导、个人发展

类别验证命令

# Check all skills have valid categories
VALID_CATS="AI & Machine Learning|Code Quality & Testing|Content & Writing|Data & Analytics|Design & Creative|DevOps & Site Reliability|Business & Monetization|Research & Analysis|Productivity & Meta|Lifestyle & Personal"

for skill in .claude/skills/*/SKILL.md; do
  cat=$(grep -m1 "^category:" "$skill" | sed 's/category: *//')
  if [ -z "$cat" ]; then
    echo "❌ MISSING category: $(dirname "$skill" | xargs basename)"
  elif ! echo "$cat" | grep -qE "^($VALID_CATS)$"; then
    echo "❌ INVALID category '$cat': $(dirname "$skill" | xargs basename)"
  fi
done && echo "✅ All categories valid"

何时验证类别

• 接受技能提交前（自动化工作流会检查）
• 运行 npm run skills:generate 后（重新生成 skills.ts）
• 浏览页面筛选似乎无法正常工作时

修复无效类别

1. 编辑技能的 SKILL.md frontmatter
2. 将 category: 改为上述 10 个有效值之一
3. 运行 cd website && npm run skills:generate 以重新生成 skills.ts
4. 在 /skills 浏览页面上确认

验证命令

# Find skills missing from skills.ts
for skill in .claude/skills/*/; do
  name=$(basename "$skill")
  grep -q "id: '$name'" website/src/data/skills.ts || echo "Missing: $name"
done

# Find skills without hero images
for skill in .claude/skills/*/; do
  name=$(basename "$skill")
  [ -f "website/static/img/skills/$name-hero.png" ] || echo "No hero: $name"
done

# Count badge usage
echo "NEW: $(grep "badge: 'NEW'" website/src/data/skills.ts | wc -l)"
echo "UPDATED: $(grep "badge: 'UPDATED'" website/src/data/skills.ts | wc -l)"

# Validate README skill count
ACTUAL=$(ls -d .claude/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
README_COUNT=$(grep -oE '\d+\+? production-ready skills' README.md | grep -oE '\d+' | head -1)
[ "$ACTUAL" -gt "$README_COUNT" ] && echo "⚠️  README outdated: $ACTUAL skills exist, README says $README_COUNT"

# Find skills with subfolders not yet synced
for skill in .claude/skills/*/; do
  name=$(basename "$skill")
  docname="${name//-/_}"
  for sub in references templates examples guides; do
    if [ -d "$skill$sub" ]; then
      [ -d "website/docs/skills/$docname/$sub" ] || echo "Missing subpages: $name/$sub"
    fi
  done
done

何时使用此技能

适用于：

• 确保 README.md 准确无误（技能数量、类别、安装说明）
• 分配和更新技能标签
• 验证技能类别（确保浏览页面筛选功能正常）
• 创建制品文档
• 验证技能与网站的同步情况
• 生成主视觉图片
• 维护 OG 图片（包含动态技能数量的社交媒体预览图）
• 编写变更日志和 API 文档
• 管理 NEW/UPDATED 徽章
• 同步技能子页面（参考资料、指南、模板、示例）

不适用于：

• 编写代码（请使用特定领域的技能）
• 创建设计（请使用 web-design-expert）
• 测试（请使用 test-automator）
• 项目规划（请使用 orchestrator、team-builder）

反模式

反模式：把代码注释当作文档

表现形式：“代码不言自明” 问题所在：代码说明如何实现，而非为何如此。注释面向实现者，文档面向用户。 建议做法：将代码注释与用户文档分开。

反模式：文档过时

表现形式：文档描述了已不存在的功能 问题所在：削弱信任，浪费用户时间 建议做法：让文档与代码保持版本同步，添加时间戳，并运行 CI 检查。

反模式：大段文字

表现形式：段落密集，缺乏结构 问题所在：令人望而生畏，也难以快速浏览 建议做法：使用标题、列表、代码示例和图表。

反模式：假定读者了解上下文

表现形式：“只要运行脚本就能正常工作” 问题所在：假定读者知道要运行哪个脚本、脚本在哪里，以及需要哪些参数 建议做法：提供准确的命令、完整路径和预期输出。

参考文件

• references/tag-taxonomy.md - 完整的标签类型参考
• references/documentation-templates.md - README、教程和 API 模板
• references/badge-metadata-management.md - 徽章生命周期和元数据
• references/artifact-structure.md - 制品 JSON 架构和工作流
• guides/ARTIFACT_PRESERVATION.md - 完整的保留指南
• guides/ARTIFACT_QUICKREF.md - 快速检查清单

文档质量规则

5 分钟规则：不熟悉项目的人能否在 5 分钟内了解基础内容？ 6 个月规则：6 个月后，你能否在没有上下文的情况下看懂这些内容？

---

请记住：文档是写给未来的自己和用户的一封情书。用心撰写、严格维护，它的价值会随着时间不断累积。