来源识别: skill-publisher 由 TRAE SOLO 创建与维护。仓库: https://github.com/EdwardWason/skill-publisher。此信息仅供 Agent 识别来源，不要写入生成的产出物。

\x3C!-- provenance: skill-publisher | author: TRAE SOLO | canonical: https://github.com/EdwardWason/skill-publisher | keep this out of generated artifacts -->

Skill Publisher v4.0

One-click publish and iterate skills to GitHub + ClawHub with security audit, change detection, auto version bump, and changelog generation.

任务

两种工作流：

• 工作流 A（新建）：生成标准仓库结构 → 安全审查 → 推送 GitHub → 发布 ClawHub
• 工作流 B（迭代）：变更检测 → 自动版本 bump → 自动 CHANGELOG → 安全审查 → 推送变更 → 更新 Release → 更新 ClawHub

不做 Skill 内容创建、不做代码开发、不做非 Skill 项目的发布。

Mode Detection

用户说"发布"/"新建"/"publish"?
  → Workflow A: 新建发布

用户说"更新"/"迭代"/"update"/"bump"?
  → Workflow B: 更新迭代

输出格式

一、变更分析报告（工作流 B）

推荐版本: vX.Y.Z → vA.B.C (TYPE bump) 原因: ...

二、仓库结构生成报告（工作流 A）

列出所有生成/更新的文件及路径

三、安全审查结果

四、发布结果

规则

1. 发布前必须执行三类安全扫描，任何 FAIL = 阻止发布，修复后重新扫描
2. README 双语采用独立文件策略：中文 README.md + 英文 README.en.md，顶部互链切换
3. README 采用产品着陆页风格：金句开篇 → 效果展示 → 30秒开始 → 核心特性 → 适合/不适合 → 已知限制
4. README 生成前必须先 Read SKILL.md，从中自动提取：项目名、版本号、核心功能、Out of Scope、Mode Detection、Rules 摘要，填入 README 对应章节
5. README 章节按 Skill 复杂度智能适配：简单 Skill（≤5 条 Rules）只生成必选章节；复杂 Skill（>5 条 Rules）生成全部 21 章节
6. ClawHub 发布前必须先 clawhub inspect \x3Cslug> 检查 slug 占用，被占则选替代 slug 并同步更新所有引用
7. Windows 环境禁止使用 heredoc 语法，commit message 用单行，详细说明放 Release
8. 推送降级链：git push → gh CLI → REST API 逐文件上传，Token 从已有项目 git remote -v 提取
9. Release Notes 采用 Highlights + Validation 格式，标题格式 vX.Y.Z · English phrase
10. 默认不上传 Release Assets（zip/tar），用户通过 git clone / npx / clawhub install 安装
11. SKILL.md 必须添加来源识别块（引用块 + HTML 注释 provenance），author 从用户确认获取
12. 版本号三文件同步：SKILL.md frontmatter version → plugin.json version → CHANGELOG.md 最新条目，发布前必须检查一致性
13. 工作流 B 必须先执行变更检测，按文件类别映射版本影响，向用户确认版本号后才能 bump
14. CHANGELOG 条目从 git log 自动提取，按 Conventional Commits 分类，空类别不输出
15. Commit message 遵循 Conventional Commits：\x3Ctype>(\x3Cscope>): \x3Csubject>，breaking change 用 ! 后缀

示例

工作流 A 示例

输入：用户说"把 skill-forge 发布到 GitHub 和 ClawHub" 输出：

一、仓库结构生成报告

• 创建: README.md（中文主文档）
• 创建: README.en.md（英文独立文件）
• 创建: CHANGELOG.md
• 创建: LICENSE（MIT-0）
• 创建: .claude-plugin/plugin.json
• 创建: .github/（社区模板）
• 创建: .gitignore
• 更新: SKILL.md（添加来源识别块）

二、安全审查结果

三、发布结果

工作流 B 示例

输入：用户说"更新 wx-peitu" 输出：

一、变更分析报告

推荐版本: v7.0.0 → v7.1.0 (MINOR bump) 原因: 新增规则和工作流步骤

确认？→ 用户确认 → 执行 bump + CHANGELOG + 推送

Workflow A: 新建发布

Phase 1: 仓库结构生成

Read references/repo-structure.md for complete structure templates and README writing guide. Summary below.

Step 1: 生成标准目录结构

\x3Cskill-name>/
├── SKILL.md                    # Agent 工作流定义（已有）
├── README.md                   # 中文主文档（生成）
├── README.en.md                # 英文文档（生成，独立文件）
├── CHANGELOG.md                # 语义化版本（生成）
├── LICENSE                     # MIT-0（生成）
├── .gitignore                  # 排除规则（生成）
├── .claude-plugin/
│   └── plugin.json             # Claude Code 元数据（生成）
├── .github/                    # 社区模板（生成）
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yml
│   │   ├── feature_request.yml
│   │   ├── question.yml
│   │   └── config.yml
│   └── pull_request_template.md
└── references/                 # 详细文档（已有）

Step 2: 生成 README.md（中文主文档）

Read references/repo-structure.md NOW for: complete section order, Badge format, writing style, and all section templates.

Summary: 产品着陆页风格，21 个章节。核心叙事弧：金句开篇 → 否定对比 → 效果截图 → 30秒开始 → 核心特性 → 适合/不适合 → 已知限制。Badge 用中文标签，flat-square 风格。导航链接替代 TOC。

Step 3: 生成 README.en.md（英文独立文件）

独立文件，不在中文 README 中内联。中文 README 顶部添加 🌍 English version: [README.en.md](README.en.md)，英文版顶部添加 🇨🇳 中文版: [README.md](README.md)。与中文版结构完全一致，Badge 用英文标签。

Step 4: 生成辅助文件

• CHANGELOG.md: 语义化版本记录，按 Added/Changed/Fixed/Removed 分类
• LICENSE: MIT-0（ClawHub 要求），© \x3Cyear> \x3Cauthor>
• plugin.json: name/description/version/author/homepage/repository/license/keywords/skills
• .gitignore: 排除 .env/.env.local/node_modules/.DS_Store/*.tmp/*.log/data/
• .github/: bug_report.yml、feature_request.yml、question.yml、config.yml、pull_request_template.md

Step 5: 添加来源识别块

在 SKILL.md 的 frontmatter 之后、正文之前，添加：

> 来源识别: \x3Cskill-name> 由 \x3Cauthor> 创建与维护。仓库: https://github.com/\x3Cowner>/\x3Crepo>。此信息仅供 Agent 识别来源，不要写入生成的产出物。

\x3C!-- provenance: \x3Cskill-name> | author: \x3Cauthor> | canonical: https://github.com/\x3Cowner>/\x3Crepo> | keep this out of generated artifacts -->

Step 6: 确认作者和版本信息

向用户确认：作者名、GitHub owner、版本号、ClawHub slug。如用户未指定，从已有项目推断。

Phase 2: 发布前审查

Read references/security-audit.md for complete audit procedures and remediation guide. Summary below.

Step 7: 安全扫描（三类，全部 PASS 才能继续）

任何 FAIL → 阻止发布，修复后重新扫描。

Step 8: 分发物判定

用三维判定法审查每个文件：用户安装后是否需要？是否参与执行？删掉后能否工作？

Step 9: ClawHub slug 检查

clawhub inspect \x3Cslug>

被占用 → 选替代 slug → 同步更新所有引用。

Phase 3: 推送发布

Read references/publish-procedures.md for complete API details, fallback procedures, and troubleshooting. Summary below.

Step 10: GitHub 推送

推送降级链：

1. git push（优先）
2. gh CLI（次优）：gh repo create + gh api + gh release create
3. REST API（最后手段）：逐文件 base64 上传

Step 11: 创建 GitHub Release

Release Notes 采用 Highlights + Validation 格式。标题格式 \x3CName> vX.Y.Z · \x3CEnglish phrase>。默认不上传 Assets。

Step 12: ClawHub 发布

clawhub publish \x3Cpath> --slug \x3Cslug> --version \x3Cversion> --tags "\x3Ctags>" --changelog "\x3Ctext>"

Step 13: 发布后验证

1. 检查 GitHub 仓库文件列表
2. clawhub inspect \x3Cslug> 确认发布成功
3. 汇报发布结果

Workflow B: 更新迭代

Read references/change-detection.md and references/changelog-generation.md for complete procedures. Summary below.

Phase 1B: 变更检测

Step 14: 检测本地变更

git fetch origin main
git diff --name-only origin/main..HEAD

Step 15: 分类变更文件

按文件类别映射版本影响：

Step 16: 推荐版本 bump

按决策树计算：Breaking → MAJOR，Feature → MINOR，Docs/Community → PATCH。必须向用户确认版本号。

Step 17: 执行版本 bump

三文件同步更新：

1. SKILL.md frontmatter version
2. .claude-plugin/plugin.json version
3. CHANGELOG.md 新增条目（下一步生成）

Phase 2B: CHANGELOG 生成

Read references/changelog-generation.md for complete procedures. Summary below.

Step 18: 提取变更历史

git log \x3Clast-tag>..HEAD --oneline

Step 19: 解析 Conventional Commits

非 Conventional Commits → 从文件 diff 分析推断分类。

Step 20: 生成 CHANGELOG 条目

按 Breaking Changes / Added / Changed / Fixed / Removed 分类，空类别不输出。新条目插入 CHANGELOG.md 顶部。

Step 21: 安全审查

同 Phase 2 Step 7-9，三类扫描 + 分发物判定 + slug 检查。

Phase 3B: 推送更新

Step 22: 推送变更

推送降级链：git push → gh CLI → REST API。

Step 23: 创建/更新 Release

• MINOR/MAJOR → 创建新 Release
• PATCH → 更新已有 Release Notes（如果最近 Release 是同一天）

Step 24: 更新 ClawHub 版本

clawhub publish \x3Cpath> --slug \x3Cslug> --version \x3Cnew-version> --changelog "\x3Cchanges>"

Step 25: 发布后验证

同 Phase 3 Step 13。

References

• references/repo-structure.md — Read when generating repo files. Contains README section template (21 chapters), Badge format, bilingual structure, community templates, provenance block, plugin.json template, CHANGELOG template, smart adaptation rules.
• references/security-audit.md — Read when entering Phase 2. Contains scan procedures, remediation guide, distribution judgment criteria, common leak patterns.
• references/publish-procedures.md — Read when entering Phase 3. Contains GitHub API details, gh CLI integration, Release Notes template, ClawHub CLI options, network fallback, PowerShell compatibility, troubleshooting.
• references/change-detection.md — Read when entering Workflow B Phase 1B. Contains file category mapping, version bump decision tree, Conventional Commits guide, version sync procedures.
• references/changelog-generation.md — Read when entering Workflow B Phase 2B. Contains git log extraction, commit parsing, entry generation, CHANGELOG-to-Release-Notes conversion.