publish-skill

将技能发布到站点

自动执行将技能发布到 claude-skills-site Astro 网站的完整流程。

路径

• 技能仓库： ~/ai_projects/claude-skills/
• 站点仓库： ~/ai_projects/claude-skills-site/
• 站点技能： ~/ai_projects/claude-skills-site/src/content/skills/*.mdx
• 站点捆绑包： ~/ai_projects/claude-skills-site/src/content/bundles/*.mdx

调用

/publish-skill <skill-name>              # New skill — generates a hero image by default
/publish-skill <skill-name> --update     # Regenerate existing .mdx (+ hero image)
/publish-skill <skill-name> --dry-run    # Show what would be written, no commits, no image
/publish-skill <skill-name> --no-image   # Skip hero-image generation

工作流

按顺序执行以下阶段。遇到任何错误时，停止并报告。

阶段 1 — 定位并读取源文件

1. 检查 ~/ai_projects/claude-skills/<skill-name>/SKILL.md 是否存在。也检查 ~/.claude/skills/<skill-name>/SKILL.md。
2. 如果两者都不存在，报告错误："未找到 <skill-name> 的 SKILL.md。请确保技能目录存在于技能仓库或 ~/.claude/skills/ 中。"
3. 如果两者都存在，则进行比较。如果 ~/.claude/skills/ 中的版本较新（按修改时间判断），使用 rsync -av --exclude='*.egg-info' --exclude='__pycache__' 将其同步到技能仓库，提交更改并推送。这可确保技能仓库始终包含最新版本。
4. 读取 SKILL.md（如已同步，优先使用技能仓库中的副本）。提取：
   • YAML frontmatter 中的 name
   • YAML frontmatter 中的 description
   • 正文内容（frontmatter 结束标记 --- 之后的所有内容）
5. 另外，检查 ~/ai_projects/claude-skills/<skill-name>/README.md 是否存在；如果存在，读取它以获取补充背景信息。

阶段 2 — 检查是否已有 MDX 文件

1. 检查 ~/ai_projects/claude-skills-site/src/content/skills/<skill-name>.mdx 是否已存在。
2. 如果该文件存在且未传入 --update：停止并请求确认。"站点上已存在技能 <skill-name> 的 .mdx 文件。传入 --update 以重新生成，或确认覆盖。"
3. 如果该文件存在且传入了 --update：读取现有的 .mdx 文件。保留该文件中的以下字段（不要重新生成）：
   • apothecary_name
   • hero_image
   • auto_activity
   • auto_last_synced（将更新为今天）

阶段 3 — 生成 MDX Frontmatter

生成以下字段：

name — 使用技能目录名称（kebab-case）。必须与文件名一致。

tagline — 一句话，不超过 80 个字符。用通俗语言概述技能的作用。以句号结尾。不要以“A skill that...”开头；应以动作动词或产出内容引出。

apothecary_name — 起一个富有诗意的 2-4 词名称，风格仿照古老的药剂师商铺。遵循现有模式：

• “The Listener's Ear”（meeting-intelligence）
• “The Scholar's Deep Draught”（deep-research）
• “The Artificer's Bench”（developer-tools）
• “The Therapist's Grimoire”（cognitive-toolkit）
• 使用 “The [Noun]'s [Noun]” 或 “[Noun] of [Noun]” 模式。

bundle — 根据技能的用途，从以下类别中选择最合适的 bundle：

Bundle key	Name	Covers
meeting-intelligence	Meeting Intelligence	转录稿、会议、录音、行动事项、视频/音频处理
communication	Communication	电子邮件、消息、Telegram、Google Workspace、Zoom
research	Research	网络研究、搜索、图片来源、知识检索
content-publishing	Content & Publishing	图像生成、演示文稿、PDF、报告、品牌素材、可视化工具
personal-analytics	Personal Analytics	健康数据、听写分析、浏览历史、自我反思、硬件信号、知识可视化
thinking-strategy	Thinking & Strategy	决策框架、JTBD、对话模式、认知工具、自我设计
developer-tools	Developer Tools	TDD、LLM CLI、问题跟踪、会话搜索、代码工具
lab-consulting	Lab & Consulting	实验室会议、客户需求探索、回顾、演示

如果技能适用于多个 bundle，优先选择最能体现其独特价值的类别。如果确实无法确定，请询问用户。

tags — 使用 3-6 个小写 kebab-case 标签。根据技能领域、所用工具和输出类型确定。检查现有技能，尽量复用已有标签。

accent_color — 从已验证的集合中选择：amber（默认）、blue、cyan、green、orange、purple、violet。除非技能有充分的主题理由选择其他颜色（例如硬件/信号 → cyan、心理健康 → violet、自然/策略 → green），否则使用 amber。

auto_description — 原样复制 SKILL.md frontmatter 中的 description 字段。如果超过 200 个字符，则截断。

auto_triggers — 从 SKILL.md 描述中提取 0-3 个触发短语（例如 “queries like”、“check my email”）。如果没有明确的触发短语，则留空 []。

auto_tools — 留空 []。

auto_last_synced — 使用今天的日期，格式为 YYYY-MM-DD。运行 date +"%Y-%m-%d" 获取日期。

auto_last_commit — 运行 git -C ~/ai_projects/claude-skills log -1 --format="%Y-%m-%d" -- <skill-name>/，获取该技能目录的最后提交日期。

auto_activity — 新技能留空 []。使用 --update 时，从现有 .mdx 保留原值。

install_command — 留空 ""。

repo_path — 技能目录名称（与 name 相同）。

dependencies — 从 SKILL.md 的 requirements/prerequisites 部分提取所需的 Python 包、CLI 工具或 API。如果没有，则使用 []。

hero_image — 此阶段将其注释掉（# hero_image:）。默认情况下，阶段 6.5 会生成主图并将此字段改写为生成的路径。仅当传入了 --no-image，或生成失败且仓库中没有截图时，才保留注释状态。

阶段 4 — 生成 MDX 正文

按照以下精确结构编写正文：

## What it does

[2-3 sentences describing the skill's primary function. Be specific about what it produces or enables. Reference concrete tools, APIs, or protocols if relevant.]

## Key features

[Bulleted list of 4-6 distinguishing features. Each bullet: **Bold label** — explanation. Focus on what makes this skill interesting, not obvious capabilities.]

## When to use

[1-2 sentences describing the trigger scenarios. Start with "When..." to match the existing pattern.]

仅在相关时添加以下章节：

• ## Signals 或 ## Modes — 如果技能有命名的操作模式或信号类型
• ## How it works — 如果技能使用了不常见的协议（MIDI、MCP 等）

请勿包含：安装说明、快速入门命令、代码块或依赖项列表。这些内容应放在 SKILL.md 和 README 中，而不是网站的 .mdx 中。

阶段 5 — 验证

写入前，请确认：

1. Bundle 存在： 确认 ~/ai_projects/claude-skills-site/src/content/bundles/<bundle>.mdx 存在。
2. 没有重复项： 如果未指定 --update，确认尚无 .mdx 文件（已在阶段 2 处理）。
3. 强调色有效： 必须是以下之一：amber、blue、cyan、green、orange、purple、violet。
4. 名称匹配： name 字段、repo_path 和文件名必须全部匹配。
5. 标语长度： 必须少于 100 个字符。

如果任何检查失败，请报告具体错误并停止。

阶段 6 — 写入文件

1. 写入 .mdx 文件至 ~/ai_projects/claude-skills-site/src/content/skills/<skill-name>.mdx。
2. 更新 bundle： 读取目标 bundle .mdx。如果技能名称尚未包含在 skills: 数组中，则将其添加到数组末尾。
3. 如果指定了 --dry-run：不要写入文件，而是显示完整的 .mdx 内容和 bundle 变更，然后停止。

阶段 6.5 — 生成主视觉图片（默认；使用 --no-image 跳过）

默认运行此阶段。仅当传入 --no-image 或处于 --dry-run 模式（只显示计划输出，不生成图片）时跳过。

使用 /codex 技能生成主视觉图片。Codex 内置了 image_gen 工具，无需 API 密钥即可生成图片。图片应遵循原始 Codex 设计会话确立的网站药剂师视觉风格。**备用方案：**如果 /codex 不可用或其 image_gen 生成失败，请使用 gpt-image-2 或 nano-banana 技能，以相同提示词和相同的 16:9 目标尺寸／路径重新生成。

提示词模板 — 填入 SKILL_NAME、APOTHECARY_NAME、SCENE_BACKDROP、SUBJECT、COMPOSITION_DETAIL 和 AVOID_EXTRA：

Use case: stylized-concept
Asset type: 16:9 skill hero image for the Claude Skills site
Primary request: Create a skill-specific hero artwork for the skill "SKILL_NAME", apothecary name "APOTHECARY_NAME". No readable text.
Style reference: Match the existing main site hero style: dark apothecary workbench fused with developer terminal artifacts, hand-tinted copperplate engraving, technical diagram overlays, tactile paper grain, oxidized copper, medicinal green, ink brown, warm bone, tiny electric-blue signal accents.
Scene/backdrop: SCENE_BACKDROP
Subject: SUBJECT
Composition: Wide 16:9, COMPOSITION_DETAIL, quiet dark negative space left, no border.
Lighting: Low raking desk light, sharp engraving detail, warm copper highlights.
Avoid: no readable words, no logos, no human figures, AVOID_EXTRA, no stock-photo look, no neon sci-fi.

现有主视觉图片的精确提示词（用作风格／结构参考）：

tdd（“测试铁砧”）：

• 场景：药剂师柜内一张厚重的工作台，上面摆放着黄铜测量仪器、抽屉、玻璃小瓶和半透明命令卡片。
• 主体：一座小型铁匠铁砧，用作测试工作站；以红色封蜡、绿色试剂光芒和抛光黄铜重构工具呈现三个不同阶段；金属上刻有微型清单便签和代码括号符号。
• 构图细节：铁砧和三阶段测试仪式位于画面右侧中央
• 避免元素：不要通用奇幻锻炉，不要烟雾弥漫的场景

jtbd（“招聘罗盘”）：

• 场景：研究人员的药剂师书桌，上面有访谈卡片、机会地图、微型样品瓶、黄铜罗盘，以及仅以抽象符号表示的抽屉标签。
• 主体：一枚黄铜罗盘，指向由客户任务构成的星群；旁边有带注释的评价挖掘卡片、用于评估机会的小型天平，以及带抽象括号的半透明终端卡片。
• 构图细节：罗盘和机会地图位于画面右侧中央
• 避免元素：不要企业风格的图库图片，不要通用图表，不要明亮扁平的 UI，不要模糊的光效

skill-studio（“自动化架构师”）：

• 场景：精密的药剂师绘图工作台，上面有黄铜卡尺、小抽屉、描图纸工作流地图、索引卡片和半透明终端配方卡片。
• 主体：建筑师罗盘、访谈问题卡片、流程图地图和小型瓶状模块，排列成结构化的自动化蓝图。
• 构图细节：画面下方和右侧区域细节丰富，并留出一些安静的留白，以便按需叠加页面文字
• 避免元素：不要现代图库照片风格，不要模糊的光效，不要可读的 UI 文本 telegram-telethon（“守护灵的中继器”）：
• 场景：炼金药剂师的通信工作台，上面有中继线圈、黄铜开关、标有抽象符号的抽屉、密封消息管和玻璃药剂瓶。
• 主体：守护灵中继装置：黄铜电报键、蚀刻在半透明卡片上的纸飞机状消息符号、音频波形药剂瓶，以及在抽屉与终端卡片之间延伸的蓝色信号线。
• 构图细节：中继装置和消息管位于中间偏右，左侧留出较暗的负空间
• 避免额外元素：不要出现 Telegram 徽标、品牌标记或现代手机模型

agency-docs-updater（“出版者的引擎”）：

• 场景：一台紧凑的炼金药剂师出版印刷机，连接着终端配方卡、档案抽屉、卷轴和文件托盘。
• 主体：一台黄铜引擎，将会议文字稿卷轴转换为三种输出：视频卷轴符号、装订好的文档页和简洁的索引卡；配有传送带、齿轮、遮蔽条，以及同步的蓝色轨迹线。
• 构图细节：出版引擎位于中间偏右
• 避免额外元素：不要出现 YouTube 徽标、品牌标记、现代 UI 截图或通用打印机

vision-bench（“裁判的放大镜”）：

• 场景：昏暗的炼金药剂师评判工作台，上面有对比托盘、样本抽屉、半透明图像板和黄铜光学仪器。
• 主体：一把大型裁判放大镜正在检查并排放置的两块图像板，旁边有小型评分砝码和校准药剂瓶；视觉模型符号以抽象眼睛图示呈现，蓝色信号轨迹连接评估卡片。
• 构图细节：放大镜和图像对比板位于中间偏右
• 避免额外元素：不要出现逼真的眼球、现代 UI 截图或通用相机素材图

主体设计指南：

• 将技能的核心操作映射为实体的炼金药剂师／工坊隐喻
• 每个主体应包含：一个中心物件（铁砧、罗盘、放大镜、引擎）、辅助细节物件（卡片、药剂瓶、符号）和微妙的数字痕迹（蓝色信号线、终端括号）
• 熟悉该技能用途的人应能立即看懂这一隐喻
• 主体描述控制在 1–2 句话

步骤：

1. 根据技能用途编写所有模板字段（场景、主体、构图、避免元素）
2. 使用组合后的提示词调用 /codex 技能，请求生成一张 16:9 图片并保存到 ~/ai_projects/claude-skills-site/public/images/SKILL_NAME-hero.jpg
3. 确认图片已创建，且尺寸约为 1672x941 像素（现有主图的标准尺寸）
4. 更新 .mdx frontmatter：将 # hero_image: 改为 hero_image: "/images/SKILL_NAME-hero.jpg"
5. 在第 8 阶段将图片文件与 .mdx 一同暂存

如果 Codex 不可用或图像生成失败，请告知用户并继续，不生成图片也可以。即使没有主图，该技能也能正常发布。

阶段 7 — 显示差异并确认

1. 运行 git -C ~/ai_projects/claude-skills-site diff 显示所有更改。
2. 向用户展示差异。
3. 询问：“发布这些更改吗？这将提交并推送到 claude-skills-site。”等待确认。

阶段 8 — 提交并推送

1. 暂存已更改的文件（默认包括生成的主图）：

   git -C ~/ai_projects/claude-skills-site add \
     src/content/skills/<skill-name>.mdx \
     src/content/bundles/<bundle>.mdx \
     public/images/<skill-name>-hero.jpg   # omit only if --no-image / no image was produced
   

2. 使用提交说明：feat: add <skill-name> skill to site
   • 对于 --update：feat: update <skill-name> skill on site
3. 推送：git -C ~/ai_projects/claude-skills-site push
4. 报告提交哈希并确认成功。

错误恢复

错误	恢复方法
未找到 SKILL.md	检查两个路径，并报告尝试过哪些路径
未找到 Bundle .mdx	列出可用的 Bundle，并请用户选择
.mdx 已存在（未使用 --update）	询问用户是否确认覆盖，或是否传入 --update
Git 推送失败	显示错误，并建议先执行 git pull --rebase
accent_color 无效	默认设为 amber，并告知用户
技能已在 bundle 数组中	跳过 Bundle 更新；这不算错误

MDX 模板

---
name: "<skill-name>"
tagline: "<tagline>"
apothecary_name: "<apothecary_name>"
bundle: <bundle>
tags: [<tags>]
accent_color: <color>
# hero_image:
auto_description: "<description>"
auto_triggers: [<triggers>]
auto_tools: []
auto_last_synced: "<date>"
auto_last_commit: "<date>"
auto_activity: []
install_command: ""
repo_path: "<skill-name>"
dependencies: [<deps>]
---

## What it does

<body>

## Key features

<features>

## When to use

<when>