从零构建高精度 AI Agent Skill：Tech Blog Generator 实战指南

摘要：为什么同样是写技术博客，有的 AI 能输出高质量内容，有的却满屏 “In today’s digital landscape”（在当今的数字景观中）？答案往往不在模型本身，而在于 Skill（技能） 的设计质量。本文将以 tech-blog-generator 为例，深度解析如何构建一个符合 OpenClaw/Codex 标准的高精度 AI Skill，并手把手教你将其发布到 GitHub。

标签：OpenClaw AI Agent Skill Development Prompt Engineering GitHub

---

1. 引言：为什么你的 Skill 不够“智能”？

在 AI Agent（人工智能代理） 生态中，Skill（技能） 是赋予通用大模型特定领域能力的核心插件。然而，许多开发者在编写 Skill 时，往往陷入“写给人类看”的误区，导致 AI 执行效果不稳定。

1.1 传统 Skill 的三大顽疾

顽疾	典型表现	后果
触发模糊	触发条件隐藏在大段正文中	AI 无法在加载前判断是否激活，导致误触发或静默失效
指令冗余	包含版本历史、作者介绍、安装指南	浪费宝贵的 Context Window (上下文窗口)，稀释核心指令
行为发散	使用“要专业”、“要有帮助”等抽象指令	AI 自由度失控，输出风格不稳定，充满“AI 味”

传统模式的失败流程：

[用户输入] --> [AI 模型] --> [Skill: "请保持专业语气"]
                                    ↓
                            输出："In today's digital landscape, 
                                   let me help you unlock the power of..."
                                   （在当今的数字景观中，让我帮你解锁...的力量）

1.2 解决思路：机器指令级设计

要构建高精度 Skill，必须转变思维：你不是在写文档，而是在写代码逻辑。

核心三原则：

1. 触发即决策：触发条件必须前置（Frontmatter），AI 在加载正文前就能判断是否相关。
2. 负向约束优先：告诉 AI“不要做什么”比“要做什么”更精确，能有效收窄行为空间。
3. 结构即协议：采用 L1(触发) + L2(执行) + L3(资源) 三级架构，分离关注点，按需加载。

---

2. 技术实现：三级架构详解

一个成熟的 Skill 应遵循严格的分层架构，以最大化 Token 利用率并确保执行确定性。

2.1 架构图解

┌─────────────────────────────────────────────┐
│ L1 Frontmatter (触发层)                     │
│   name + description (Use when / NOT for)  │
│   ~100 tokens, 始终在上下文中               │
├─────────────────────────────────────────────┤
│ L2 Body (执行层)                            │
│   Role + Constraints + Workflow            │
│   <5k tokens, 仅在触发后加载                │
├─────────────────────────────────────────────┤
│ L3 Resources (资源层，按需加载)              │
│   references/ (文档) + scripts/ (脚本)      │
│   无上限，零 Token 成本 (脚本执行不读入)     │
└─────────────────────────────────────────────┘

2.2 L1：Frontmatter 触发器设计

这是 Skill 的“门禁系统”。AI 每次对话都会扫描所有已安装技能的 Frontmatter（文件头元数据）。

---
name: tech-blog-generator
description: >-
  Generates high-quality technical blogs from source code and documentation.
  Use when: Users upload code files (.py, .go, .js) or tech docs and request 
            "write a blog", "generate tutorial", or "explain code".
  NOT for: General chat, non-technical writing, or when no code/files are provided.
license: MIT
---

关键点：

• Use when (何时使用) 和 NOT for (非适用场景) 必须同时存在：明确边界，防止误触。
• 位置至关重要：必须放在 description 字段。如果写在 Body (正文) 里，AI 决定触发后才看到，为时已晚。

2.3 L2：负向约束与工作流

在 Body 部分，摒弃客套话，直接使用祈使句和反模式清单。

负向约束设计 (Anti-Patterns)

约束类型	示例	效果
正向 (弱)	“Be professional” (要专业)	❌ 模糊，AI 自由发挥，结果不可控
负向 (强)	“NO AI Fluff: Never use ‘In today’s…’” (禁止废话：绝不用“在当今…”)	✅ 明确边界，精确执行，直接切断错误路径

实战代码片段：

# Constraints & Anti-Patterns (CRITICAL)
- **NO Pedagogical Tone**: Never use "let's learn", "beginners", "I hope this helps"
  (禁止说教语气：绝不用“让我们学习”、“初学者”、“希望这对你有帮助”)
- **NO AI Fluff**: Never use "In today's digital landscape", "Unlock the power of"
  (禁止 AI 废话：绝不用“在当今数字景观中”、“解锁...的力量”)
- **NO Unexplained Code**: Every code block MUST have plain-English explanation
  (禁止未解释的代码：每个代码块必须有通俗英语解释)
- **NO Wall of Text**: Must use ASCII diagrams or tables for abstract concepts
  (禁止文字墙：抽象概念必须使用 ASCII 图或表格)

标准化工作流 (Workflow)

定义明确的执行步骤，让 AI 像运行程序一样按部就班：

1. Analyze & Scope (分析与定界): 扫描文件，识别语言、架构、关键算法。
2. Structure Outline (构建大纲): 强制使用模板（标题 -> 摘要 -> 图示 -> 对比 -> 代码 -> 排错 -> 总结）。
3. Content Generation (内容生成): 生成 ASCII 图 + 对比表格 + 代码解释块。
4. Self-Correction Review (自检修正): 自检四问（是否有老师腔？代码是否全解释？概念是否有图？结尾是否矫情？）。

2.4 L3：资源层 (References & Scripts)

• references/: 存放详细的风格指南 (style_guide.md) 或领域知识 (common_pitfalls.md)。仅在 AI 主动查阅时加载，节省主上下文。
• scripts/: 存放 Python/Bash 脚本。用于执行“脆弱操作”（如格式校验、Token 计数）。脚本是执行而不读入的，实现零 Token 成本的确定性保障。

---

3. 项目结构与文件说明

一个完整的 Skill 项目应包含以下结构，既方便 AI 执行，也方便人类维护。

tech-blog-generator/
├── SKILL.md                    # [核心] 5.7KB - AI 的执行指令与触发规则
├── README.md                   # [必读] 给人类看的介绍文档（开源必备）
├── LICENSE                     # [协议] MIT License
├── .gitignore                  # [忽略] 排除缓存和敏感文件
│
├── agents/                     # UI 展示层
│   └── openai.yaml             # 628B - 技能在界面上的名称、简介配置
│
├── references/                 # 知识库层 (按需加载)
│   ├── style_guide.md          # 1.2KB - 写作风格反模式清单
│   └── common_pitfalls.md      # 2.6KB - 常见技术坑点汇总
│
└── scripts/                    # 工具层 (确定性执行)
    ├── validate_yaml.py        # 1.6KB - 校验 frontmatter 格式
    └── count_tokens.py         # 1.4KB - 检查输出长度

关键文件作用表

文件/目录	角色	核心价值
SKILL.md	大脑	包含 Frontmatter 和 Body。AI 仅凭此文件即可工作。
agents/openai.yaml	名片	定义 UI 显示名称。通常由脚本生成，保证格式严格合规。
references/	外挂大脑	详细知识库。只在需要时加载，避免污染主上下文。
scripts/	机械臂	确定性工具。处理那些“不能出错”的任务，如格式校验。

---

4. 实战：将 Skill 发布到 GitHub

构建好 Skill 后，下一步是将其开源。以下是标准的发布流程。

4.1 准备工作

1. 本地整理：确保文件夹结构如上所示。
2. 创建 .gitignore：避免上传无用文件。

   __pycache__/
   *.pyc
   .env
   .DS_Store
   

3. 检查 README：确保根目录下有一个 README.md（注意大小写）。

4.2 创建 GitHub 仓库

1. 登录 GitHub.com。
2. 点击右上角 + -> New repository (新建仓库)。
3. Repository name (仓库名): tech-blog-generator (建议与技能名一致)。
4. Description (描述): “A universal AI skill for generating high-quality technical blogs from code.”
5. Visibility (可见性): 选择 Public (公开)。
6. ⚠️ 重要：不要勾选 “Initialize this repository with a README”。
   • 原因：本地已有 README，勾选会导致冲突。
7. 点击 Create repository (创建仓库)。

4.3 上传文件

方法 A：网页拖拽（推荐新手）

1. 在仓库页面点击 uploading an existing file (上传现有文件)。
2. 将本地 tech-blog-generator 文件夹内的所有文件拖拽到上传区。
3. Commit message (提交信息): Initial commit: Add full skill structure。
4. 点击 Commit changes (提交更改)。

方法 B：Git 命令行（推荐进阶）

cd tech-blog-generator
git init
git add .
git commit -m "Initial commit: Add TechBlogGenerator skill"
git remote add origin https://github.com/YOUR_USERNAME/tech-blog-generator.git
git branch -M main
git push -u origin main

---

5. ⚠️ 关键排查：为什么 README 不显示？

很多新手上传后发现仓库首页空空如也，或者 README.md 没有渲染。这通常是以下三个原因之一：

5.1 文件名大小写错误 (最常见！)

GitHub 只认 全大写的 README.md。

• ❌ 错误：readme.md, Readme.md, README.MD
• ✅ 正确：README.md (必须全部大写)

修复方法：
在 GitHub 网页上点击文件 -> 右上角铅笔图标 -> 修改文件名为 README.md -> Commit changes。
或者在本地执行：

git mv readme.md README.md
git commit -m "Fix: Rename to uppercase README.md"
git push

5.2 文件位置错误

README.md 必须位于仓库的 根目录 (Root Directory)。

• ❌ 错误：放在 docs/README.md 或子文件夹内。
• ✅ 正确：直接与 .git (隐藏) 同级。

5.3 扩展名错误

确保后缀是 .md，而不是 .txt 或 .markdown。

---

6. 效果验证与维护

6.1 触发测试

✅ 正面触发

User: “Here are main.go and config.yaml. Write a blog about concurrency.”
AI: (激活 Skill) 输出包含 ASCII 流程图、代码深度解析、无废话的技术博客。

❌ 负面触发

User: “What’s the weather today?”
AI: (不激活) 回复 “This skill is for code-to-blog generation. I can’t help with weather.” 或直接由其他通用逻辑处理。

6.2 迭代维护

Skill 不是一次性的。当你需要优化时：

1. 本地修改：编辑 SKILL.md 或补充 references/。
2. 脚本校验：运行 python scripts/validate_yaml.py . 确保格式无误。
3. 推送更新：

   git add .
   git commit -m "Update: Add Python async patterns to references"
   git push
   

---

7. 结语

构建高精度 Skill 的核心不在于 “Prompt 写得多长”，而在于：

1. 触发器精确化 — description 即决策逻辑。
2. 约束负向化 — “不要做 X” 比 “要做 Y” 更可靠。
3. 结构协议化 — 三层分离，按需加载。
4. 输出可验证 — 自检清单 + 脚本校验。

这套方法论不仅适用于博客生成器，任何需要稳定输出的 AI Agent 技能都应遵循同样的设计原则。

现在，去创建你的第一个高质量 Skill 仓库吧！

🔗 项目地址: github.com/YardonYan/tech-blog-generator

如果觉得本教程有帮助，欢迎 Star (加星收藏) ⭐️ 我的仓库！