agent-skill-builder：把「一篇方法论文章 / 一个重复流程」固化成Skill

开源地址：
https://github.com/luozhilzh/agent-skill-builder
https://gitee.com/luozhilzh/agent-skill-builder

Agent Skill Builder

把「一篇方法论文章 / 一个重复流程」固化成可复用、跨工具、能开源的 Agent Skill 包。覆盖立项 → 规范落地 → 本地验证 → 借鉴增强 → 交付打磨 → 同步 → 开源发布 → 收口全生命周期。

本 skill 自身就按它描述的流程构建并开源（dogfood）。

安装

有 skill 目录的工具（WorkBuddy / Claude Code / Codex / Cursor）

./install.sh                 # 安装到全部 4 款工具
./install.sh --target claude # 只装 Claude Code
./install.sh --project       # 装到当前项目的 .workbuddy/skills/

Windows 用户请用 Git Bash 运行（不要直接双击 .sh）。

纯对话工具（ChatGPT / Gemini / 豆包 / 元宝 / DeepSeek）

无原生 skill 目录。把 references/workflow.md 与 references/agent-skills-standard.md 的核心内容复制，按你的主题替换后粘贴对话框，按步骤走。

使用

在对应工具的新会话中输入 /agent-skill-builder 即可调用。它会引导你走 P0→P7 全流程。

想从零直接生成新 skill 骨架：

python scripts/scaffold_skill.py --name my-new-skill --out ./skills

支持按复杂度分档生成（--tier，默认 standard = 历史默认行为）：

python scripts/scaffold_skill.py --name my-new-skill --tier minimal   # SKILL.md + .gitignore
python scripts/scaffold_skill.py --name my-new-skill --tier standard  # + README/LICENSE/install.sh/references/
python scripts/scaffold_skill.py --name my-new-skill --tier full      # + scripts/validate_skill.py + assets/ + examples/ + .github 校验

校验某个 skill 包（递归扫描目录下所有 SKILL.md，退出码 0=通过 / 1=失败）：

python scripts/validate_skill.py ./skills/my-new-skill
# 或校验整个仓库
python scripts/validate_skill.py .

本仓库已配置 GitHub Actions（.github/workflows/validate.yml）：push 时自动跑上面这条校验。

交付与同步（P4 / P5）

想把产出做成可带走的 HTML 成果卡？复制 assets/template.html，替换其中 7 个 {{...}} 占位符，再用校验器确认有效：

python scripts/validate_card.py examples/skill_cheatsheet.html   # 已生成的脱敏样例，应 [PASS]

保持"开发目录（源）"与"用户级副本（工具实际加载）"一致：

bash scripts/sync.sh . ~/.workbuddy/skills/agent-skill-builder         # 镜像 + 校验 byte-identical
bash scripts/sync.sh --check . ~/.workbuddy/skills/agent-skill-builder # 仅校验，不覆盖

目录结构

agent-skill-builder/
├── SKILL.md                      # 路由 + 生命周期 + 硬规则 + 反模式
├── README.md                     # 本文件
├── LICENSE                       # MIT, copyright luozhi 2026
├── .gitignore
├── install.sh                    # 跨工具一键安装
├── .github/
│   └── workflows/
│       └── validate.yml          # CI：push 时校验 SKILL.md（零依赖）
├── RELEASE_CHECKLIST.md          # 开源发布清单（dogfood 用）
├── CHANGELOG.md                  # 版本与决策留痕（dogfood P3）
├── references/
│   ├── workflow.md               # P0–P7 详细 playbook
│   ├── agent-skills-standard.md  # Agent Skills 开放标准速查
│   ├── description-guide.md      # description 优化提示/评分标准（可选增强 P4）
│   ├── define-skill.md           # 需求澄清四要素（可选增强 A）
│   ├── should-i-build.md         # 立项闸门：该不该做（可选增强 B）
│   ├── trigger-selfcheck.md      # 触发自测/最后一公里（可选增强 C）
│   ├── plugin-packaging.md       # 插件市场与分发渠道（可选增强 D-minimal）
│   └── release-template.md       # RELEASE_CHECKLIST + Release note 模板
├── assets/
│   └── template.html             # 可复用的中性配色 HTML 成果卡模板（P4）
├── scripts/
│   ├── scaffold_skill.py         # 一键生成新 skill 骨架（支持 --tier 分档）
│   ├── validate_skill.py         # 零依赖校验 SKILL.md（frontmatter/kebab-case/目录名一致/desc 软 WARN）
│   ├── validate_card.py          # 零依赖校验导出的 HTML 成果卡（P4）
│   ├── secret_scan.py            # 零依赖扫描脚本疑似硬编码密钥（可选增强 P6）
│   ├── sync.sh                   # 源↔用户副本镜像 + diff byte-identical（P5）
│   └── verify_release.sh         # 公开 clone 复验脚本（F 步，零依赖 bash）
└── examples/
    ├── CASE_STUDY.md             # 极简示例 + 指向 ai-10x-learning 真实案例
    └── skill_cheatsheet.html     # 用模板生成的脱敏样例卡（P4 dogfood）

可选增强（A/B/C/D，按需采用）

本 skill 的「可选增强」与 P0–P7 生命周期是两回事（见 references/BACKLOG.md）。以下四项来自对兄弟项目 skill-creator 类仓库的对比研究，按需采用：

• A 需求澄清四要素：写 skill 前用 references/define-skill.md 把「产出 / 触发 / 输入输出 / 边界」想清楚（一次一问、按措辞自适应深浅，含确认门）。
• B 立项闸门：动手前过 references/should-i-build.md 四问，确认值得做成 skill。
• C 触发自测/最后一公里：发布前按 references/trigger-selfcheck.md 验证「装得上、能触发、跑得通」。
• D 插件市场打包（可选）：想增加分发渠道看 references/plugin-packaging.md（主渠道仍是 git + install.sh）。

核心纪律（速记）

1. SKILL.md frontmatter 只 name + description
2. 协议层不硬编码工具名（能力感知三层降级）
3. 验证前不宣称完成
4. 改关键文件后 grep/git status 复核落盘
5. examples 必须脱敏
6. 不自动提交（只给命令）
7. 脚本零硬编码密钥（密钥走 env；发布前 secret_scan）

许可

MIT —— Copyright (c) 2026 luozhi

发布后复验（F 步）

发布后建议跑一次「公开 clone 复验」，独立证明发出去的包真能装、校验真能过：

bash scripts/verify_release.sh --install   # 克隆公开仓库 + 装到各平台 + 三项校验
# 不带 --install 则只做零副作用的校验；--tag=vX.Y.Z 可复验指定版本

退出码 0 = 全部通过；任意校验失败即非 0。脚本内注释有完整参数说明。