以claude-blog为样本学习Agent Skills开发：从编排路由到代码级质量门禁的完整指南
【免费下载链接】claude-blogClaude Code blog skill suite: 30 sub-skills, 5 agents, 5-gate v1.9.0 Blog Delivery Contract, dual-optimized for Google rankings and AI citations. Active development at AI-Marketing-Hub/claude-blog (AI Marketing Hub Pro community); public releases ship here.项目地址: https://gitcode.com/gh_mirrors/cl/claude-blog
对于想开发 AI Agent Skills 的新手来说，claude-blog 是一个难得的完整样本：32 个技能目录（1 个编排器 + 31 个子技能）、5 个专职 Agent、5 道代码级质量门禁，全部开源可读。本文带你从编排路由、按需加载到质量门禁，拆解它构建 Agent Skills 的 5 个核心方法。
1. 架构总览：技能、Agent、脚本三层协作
打开 docs/ARCHITECTURE.md，你会发现整个系统分三层：
| 层级 | 数量 | 位置 |
|---|---|---|
| 技能目录 | 32 | skills/blog+skills/blog-* |
| 专职 Agent | 5 | agents/blog-*.md |
| Python 脚本 | 14 | scripts/*.py |
| 参考文档 | 22 | skills/blog/references/*.md |
核心思想一句话：Markdown 负责"教"，脚本负责"管"。SKILL.md 用自然语言写清工作流程，而所有关键校验都由 Python 脚本强制执行，不依赖模型"自觉"。
2. 编排路由：一个入口解析全部 30 个命令
学习 Agent Skills 开发，第一步是理解路由。主编排器 skills/blog/SKILL.md 承担了四件事：
- 解析命令：用户输入
/blog <子命令>，编排器根据路由表分发，比如write→blog-write、analyze→blog-analyze、geo→blog-geo - 平台检测：根据文件后缀和项目结构（如
hugo.toml、wp-content/）自动识别博客平台，适配输出格式 - 按需加载参考文档（下节详述）
- 执行质量门禁：任何子技能产出的内容都必须过门禁才能交付
给用户的只是 30 个/blog命令（完整清单见 docs/COMMANDS.md），而blog-chart这类内部子技能不暴露——命令面越收敛，用户心智负担越低，这是新手最容易忽略的设计点。
3. 按需加载：用 RAG 模式控制上下文体积
30 个子技能、22 篇参考文档如果全部塞进上下文，既贵又慢。claude-blog 的做法是"任务映射表"：
/blog write→ 只加载content-rules.md、visual-media.md、quality-scoring.md/blog schema→ 只加载schema-stack.md/blog analyze→ 只加载quality-scoring.md
这套"RAG 式按需加载"模式（映射表写在 docs/ARCHITECTURE.md 的 On-Demand Reference Loading 一节）值得直接抄：每个 SKILL.md 里维护一张"任务 → 参考文件"的表，用到才读。
4. 多 Agent 分工：最小权限原则
5 个 Agent 定义在agents/目录下，每个都有独立的 YAML frontmatter 声明职责和受限工具集：
| Agent | 角色 | 可用工具 |
|---|---|---|
blog-researcher | 找统计数据和来源 | WebSearch, WebFetch, Read, Grep |
blog-writer | 撰写正文 | Read, Write, Edit |
blog-seo | 页面 SEO 校验 | Read, Grep |
blog-reviewer | 100 分制质量评审 | Read, Grep |
blog-translator | 多语言翻译 | Read, Write, Edit |
两个新手要点：
- 评审者只读：agents/blog-reviewer.md 没有 Write 和 Bash 权限，保证它只能打分、不能改稿，评审与写作彻底隔离
- 写作 → 评审 → 打分是标准流水线：
/blog write的执行顺序是"解析 → 研究 → 大纲 → 写作 → SEO 校验 → 评分 → 门禁交付"（见 skills/blog/SKILL.md 的 Execution Flow 一节）
5. 代码级质量门禁：5-Gate 交付契约
这是 claude-blog 最有价值的部分。它的 v1.9.0 交付契约（完整规格见 skills/blog/references/blog-delivery-contract.md）在"内容生成"和"交付用户"之间插了 5 道自动门禁：
| 门禁 | 校验内容 | 执行者 |
|---|---|---|
| Gate 1 能力探测 | 工具、Agent、依赖是否齐备 | scripts/blog_preflight.py |
| Gate 2 格式完整 | .md+.html+.pdf+ 封面图四件套齐全 | scripts/blog_render.py |
| Gate 3 视觉验证 | 三种视口截图、无 SVG 溢出、JSON-LD 合法 | blog_preflight.py --gate 3 |
| Gate 4 内容评审 | 评分 ≥ 90 且无 P0 问题，阻断式 | blog-reviewer输出BLOCKING:行 |
| Gate 5 资源与链接 | 图片可解析、链接 200、字数与 schema 误差 ≤ 5% | blog_preflight.py --gate 5 |
三条关键设计，建议逐条记住：
- 门禁失败触发迭代循环：任何门禁失败都自动打回重写，最多 3 轮；第 3 轮仍失败则停止，向用户展示诊断报告而不是强行交付。循环计数器由编排器持有，子技能不许自己循环
- 阻断式评审：
blog-reviewer输出以机器可读的BLOCKING: true|false行结尾，由脚本解析，不靠模型自由发挥 - 绕过必须显式：只有
--no-strict才能跳过门禁，且会大声打印警告日志——草稿 frontmatter 无权禁用门禁
此外还有第二道防线：scripts/quality_gate.py 作为 pre-commit 钩子，在git commit时自动拦截评分低于 70 的博客文章。"生成时门禁 + 提交时门禁"双层防护，是代码级质量管理的完整形态。
6. 用测试锁住"文档与实现不漂移"
最后一个新手容易忽视的环节：Agent Skills 的文档本身也需要 CI。仓库的 tests/ 目录有 250+ 个用例，其中几个针对 Skill 工程本身：
- tests/test_blog_delivery_contract.py：断言交付契约文档与其脚本实现保持一致
test_reference_count_coherence：断言 SKILL.md 声称的参考文档数量与实际文件数一致test_command_coherence：断言编排器路由表与 docs/COMMANDS.md 声明的命令集完全相同scripts/lint_prose.py：连行文规范（如禁止 em dash）都有脚本强制
动手清单：构建你自己的 Agent Skills
对照 claude-blog，一个合格的 Skills 项目应该包含：
- 一个主编排器 SKILL.md：命令路由表 + 平台/输入检测 + 任务 → 参考文档映射
- 单一职责子技能目录：每个
skills/<name>/SKILL.md自带 frontmatter、流程、质量检查 - 受限工具的专职 Agent：评审者只读，写作者最小写权限，一律去掉 Bash
- 代码级门禁脚本：把"规则"翻译成可执行断言（
preflight式），失败进迭代循环，而非靠提示词约束 - 一致性测试：用 pytest 锁死文档、路由表、脚本三者不漂移
把这套方法搬过去，你的 Skill 就不再是一堆提示词，而是一条可审计、可回归的流水线。
【免费下载链接】claude-blogClaude Code blog skill suite: 30 sub-skills, 5 agents, 5-gate v1.9.0 Blog Delivery Contract, dual-optimized for Google rankings and AI citations. Active development at AI-Marketing-Hub/claude-blog (AI Marketing Hub Pro community); public releases ship here.项目地址: https://gitcode.com/gh_mirrors/cl/claude-blog
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
