摘要为什么同样是写技术博客有的 AI 能输出高质量内容有的却满屏 “In today’s digital landscape”在当今的数字景观中答案往往不在模型本身而在于Skill技能的设计质量。本文将以tech-blog-generator为例深度解析如何构建一个符合 OpenClaw/Codex 标准的高精度 AI Skill并手把手教你将其发布到 GitHub。标签OpenClawAI AgentSkill DevelopmentPrompt EngineeringGitHub文章目录1. 引言为什么你的 Skill 不够“智能”1.1 传统 Skill 的三大顽疾1.2 解决思路机器指令级设计2. 技术实现三级架构详解2.1 架构图解2.2 L1Frontmatter 触发器设计2.3 L2负向约束与工作流负向约束设计 (Anti-Patterns)标准化工作流 (Workflow)2.4 L3资源层 (References Scripts)3. 项目结构与文件说明关键文件作用表4. 实战将 Skill 发布到 GitHub4.1 准备工作4.2 创建 GitHub 仓库4.3 上传文件方法 A网页拖拽推荐新手方法 BGit 命令行推荐进阶5. ⚠️ 关键排查为什么 README 不显示5.1 文件名大小写错误 (最常见)5.2 文件位置错误5.3 扩展名错误6. 效果验证与维护6.1 触发测试6.2 迭代维护7. 结语1. 引言为什么你的 Skill 不够“智能”在AI Agent人工智能代理生态中Skill技能是赋予通用大模型特定领域能力的核心插件。然而许多开发者在编写 Skill 时往往陷入“写给人类看”的误区导致 AI 执行效果不稳定。1.1 传统 Skill 的三大顽疾顽疾典型表现后果触发模糊触发条件隐藏在大段正文中AI 无法在加载前判断是否激活导致误触发或静默失效指令冗余包含版本历史、作者介绍、安装指南浪费宝贵的Context Window (上下文窗口)稀释核心指令行为发散使用“要专业”、“要有帮助”等抽象指令AI 自由度失控输出风格不稳定充满“AI 味”传统模式的失败流程[用户输入] -- [AI 模型] -- [Skill: 请保持专业语气] ↓ 输出In todays digital landscape, let me help you unlock the power of... 在当今的数字景观中让我帮你解锁...的力量1.2 解决思路机器指令级设计要构建高精度 Skill必须转变思维你不是在写文档而是在写代码逻辑。核心三原则触发即决策触发条件必须前置FrontmatterAI 在加载正文前就能判断是否相关。负向约束优先告诉 AI“不要做什么”比“要做什么”更精确能有效收窄行为空间。结构即协议采用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 L1Frontmatter 触发器设计这是 Skill 的“门禁系统”。AI 每次对话都会扫描所有已安装技能的Frontmatter文件头元数据。---name:tech-blog-generatordescription:-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 lets learn, beginners, I hope this helps (禁止说教语气绝不用“让我们学习”、“初学者”、“希望这对你有帮助”) - **NO AI Fluff**: Never use In todays 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 像运行程序一样按部就班Analyze Scope (分析与定界): 扫描文件识别语言、架构、关键算法。Structure Outline (构建大纲): 强制使用模板标题 - 摘要 - 图示 - 对比 - 代码 - 排错 - 总结。Content Generation (内容生成): 生成 ASCII 图 对比表格 代码解释块。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 准备工作本地整理确保文件夹结构如上所示。创建.gitignore避免上传无用文件。__pycache__/ *.pyc .env .DS_Store检查 README确保根目录下有一个README.md注意大小写。4.2 创建 GitHub 仓库登录 GitHub.com。点击右上角-New repository (新建仓库)。Repository name (仓库名):tech-blog-generator(建议与技能名一致)。Description (描述): “A universal AI skill for generating high-quality technical blogs from code.”Visibility (可见性): 选择Public (公开)。⚠️ 重要不要勾选“Initialize this repository with a README”。原因本地已有 README勾选会导致冲突。点击Create repository (创建仓库)。4.3 上传文件方法 A网页拖拽推荐新手在仓库页面点击uploading an existing file (上传现有文件)。将本地tech-blog-generator文件夹内的所有文件拖拽到上传区。Commit message (提交信息):Initial commit: Add full skill structure。点击Commit changes (提交更改)。方法 BGit 命令行推荐进阶cdtech-blog-generatorgitinitgitadd.gitcommit-mInitial commit: Add TechBlogGenerator skillgitremoteaddorigin https://github.com/YOUR_USERNAME/tech-blog-generator.gitgitbranch-Mmaingitpush-uorigin main5. ⚠️ 关键排查为什么 README 不显示很多新手上传后发现仓库首页空空如也或者README.md没有渲染。这通常是以下三个原因之一5.1 文件名大小写错误 (最常见)GitHub只认全大写的README.md。❌错误readme.md,Readme.md,README.MD✅正确README.md(必须全部大写)修复方法在 GitHub 网页上点击文件 - 右上角铅笔图标 - 修改文件名为README.md- Commit changes。或者在本地执行gitmvreadme.md README.mdgitcommit-mFix: Rename to uppercase README.mdgitpush5.2 文件位置错误README.md必须位于仓库的根目录 (Root Directory)。❌错误放在docs/README.md或子文件夹内。✅正确直接与.git(隐藏) 同级。5.3 扩展名错误确保后缀是.md而不是.txt或.markdown。6. 效果验证与维护6.1 触发测试✅ 正面触发User: “Here aremain.goandconfig.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 不是一次性的。当你需要优化时本地修改编辑SKILL.md或补充references/。脚本校验运行python scripts/validate_yaml.py .确保格式无误。推送更新gitadd.gitcommit-mUpdate: Add Python async patterns to referencesgitpush7. 结语构建高精度 Skill 的核心不在于 “Prompt 写得多长”而在于触发器精确化—description即决策逻辑。约束负向化— “不要做 X” 比 “要做 Y” 更可靠。结构协议化— 三层分离按需加载。输出可验证— 自检清单 脚本校验。这套方法论不仅适用于博客生成器任何需要稳定输出的AI Agent技能都应遵循同样的设计原则。现在去创建你的第一个高质量 Skill 仓库吧 项目地址: github.com/YardonYan/tech-blog-generator如果觉得本教程有帮助欢迎Star (加星收藏)⭐️ 我的仓库