如何撰写一个高质量的 AI Skill：撰写指南

生成日期2026-08-10第 1 章引言——AI Skill 是什么为什么需要撰写规范1.1 AI Agent 的能力拼图AI Agent 的能力不是靠一个万能大模型独自完成的而是通过可插拔的能力包——Skill拼装起来的。Skill 是 AI Agent 的能力扩展包包含三个核心要素领域知识擅长什么、处理流程按什么步骤执行、引擎代码如何完成处理。与传统插件不同Skill 是包含完整上下文和执行协议的智能模块——它告诉 AI Agent 什么时候用我、怎么用我、出错了怎么办。1.2 标准化撰写的价值分析了多个不同领域代码质量、内容创作、金融、医疗、政务等的真实 Skill 后一个结论很清晰Skill 的质量80% 取决于撰写规范。撰写不规范会导致 Agent 误判、流程混乱、输出崩溃、维护噩梦。反之优秀 Skill 在目录结构、设计模式、SKILL.md 模板和健壮性规范四个维度上表现出惊人的一致性——这是实践验证后的收敛结果。1.3 本文结构维度内容目录结构标准 Skill 包必须包含的文件及职责设计模式八大模式的 Python 实现与架构角色SKILL.md 模板从 YAML frontmatter 到 Response Format 的逐段指南工程实践Windows 兼容、故障隔离、注入防护等健壮性规范常见踩坑8 个最容易犯的错及解决方案第 2 章标准化结构——目录树与设计模式分析多个高质量 Skill 后最突出的发现是它们在组织方式上的高度一致。2.1 标准目录树所有优秀 Skill 100% 遵循的结构skill-name/ ├── SKILL.md # 核心定义名片说明书契约 ├── architecture.md # 架构说明维护者的施工蓝图 ├── examples.md # 使用示例 ├── requirements.txt # 依赖声明 ├── scripts/run_xxx.py # CLI 入口 ├── demos/ # 演示数据sample.json sample.txt └── src/package/ # 引擎源码 ├── facade.py # 外观模式——唯一入口 ├── cli.py / loader.py / pipeline.py ├── model/ # enums.py schema.py ├── core_module/ # factory.py strategy.py ├── report/ # builder.py formatter.py md_escape.py └── rules/registry.py # 单例注册表关键文件职责SKILL.md是 Agent 判断加载的唯一依据缺失则无法触发demos/是评审者快速验证的通道缺失则无法通过评审src/package/与入口脚本分离支持python -m模块化运行。2.2 八大设计模式所有 Skill 采用对齐 GoF 的架构每个模式解决一个真实工程痛点模式文件解决的问题核心代码片段Facadefacade.py外部只需一个入口SkillFacade(mode).process(data)FactoryStrategyfactory.py按 mode 动态创建分析器新增只需注册一行AnalyzerFactory.register(Mode.X, XAnalyzer)Template Methodpipeline.py固定骨架加载→校验→分析→组装→格式化子类填充细节class Pipeline(ABC): run() → process()Chain of Responsibilitypipeline/chain.py多步骤串联单步失败不崩溃try: handler.handle(); except: errors.append()SingletonRegistryrules/registry.py规则库全局只加载一次__new___load_defaults()Builderreport/builder.py逐步组装复杂报告add_summary().add_details().add_stats()Adapteranalyzer/adapter.py封装外部库接口差异ASTAdapter.parse(source, lang)Formatter Strategyreport/formatter.py同一结果输出 Markdown/JSON/TextMarkdownFormatter/JsonFormatter关系链Facade 守门 → Template Method 定型 → Strategy 换脑 → Chain 串联 → Builder 组装 → Formatter 润色 → Registry 共享 → Adapter 对接。第 3 章SKILL.md 撰写模板全解析所有 Skill 的 SKILL.md 结构高度收敛本章逐段拆解标准模板。3.1 YAML Frontmatter--- name: code-intel-guardian # 全小写连字符 version: 1.2.1 # 严格 SemVer description: - # 英文在前 空行 中文必须双语 ...English description... ...中文说明 Use when 触发关键词... ---字段常见错误正确做法name空格、驼峰、中文全小写连字符version不写或1.01.0.0严格 SemVerdescription只写英文不带中文英文在前 空行 中文Use when:含中文关键词⚠️ description 只写英文 → 中文 Agent 永远匹配不到 → Skill 永不加载。3.2 各段撰写要点段落核心原则标题一句话定位不铺垫背景直接说清楚 Skill 做什么When to use包含自然语言触发词 CLI 命令两种触发方式Package Layout用 ASCII 树展示不用纯文本列表Architecture表格列出模式、组件、职责每组件对应真实文件Workflow- [ ]勾选格式每步动词开头5-9 步可选步骤标(Optional)RunCLI 命令从包根目录执行文件名用 demos 中的实际文件Response Format[TAG]ASCII 标记互斥且附示例禁用 emojiRobustness覆盖编码/标记/崩溃/注入四方面Extending具体到文件路径和函数名不能写在合适的地方添加代码3.3 SKILL.md 自检 Checklist10 条YAML 含name/version/ 双语descriptiondescription 中英文都有When to use 含用户表述 CLI 命令Package layout 与实际目录一致Architecture 表格每组件对应真实文件Workflow 每步有明确输入输出CLI 示例复制粘贴可运行Response Format 中[TAG]语义互斥Robustness 覆盖编码/标记/崩溃/注入Extending 有具体文件名和注册代码第 4 章工程实践——健壮性、踩坑与总结前几章分别从结构、模式、模板三个维度拆解了 Skill 的撰写方法论。本章聚焦最后的工程兜底——在生产环境中一个 Skill 能否稳定运行取决于它对边界情况的处理能力。4.1 五道健壮性防线防线一Windows cp936 编码。所有 Skill 统一在io_util.py中封装configure_stdio()UTF-8 配置safe_print()捕获 UnicodeEncodeError fallback 为 ASCIICLI 入口首行调用。防线二ASCII 标记禁 emoji。用[CRIT]/[WARN]/[OK]/[MISS]/[STAT]替代 ⚠️✅❌避免 cp936 乱码和跨平台渲染差异。防线三故障隔离。try/except包裹每个 handler异常写入errors[]不中断责任链。防线四Markdown 注入防护。用户输入中的|*经md_escape()转义阻止javascript:/data:协议 URL。防线五隐私保护行业增量。医疗/金融等涉及个人信息的 Skill 额外执行手机号/身份证/邮箱正则脱敏。4.2 常见踩坑 Top 8#踩坑解决方案1规则散落、不可测试集中在rules/ Registry 加载2不用 safe_print → Windows 崩溃io_util.py封装全项目统一3emoji 标记 → 控制台乱码统一[TAG]ASCII4单模块异常 → 全流程崩溃责任链 try/except errors[]5动态字段未转义 → 表格破坏/XSS经md_escape()后嵌入6description 只写英文英文 空行 中文7不提供 demos → 无法验证至少sample.jsonsample.txt8YAML 缺 version严格1.0.0SemVer4.3 开发流程与十二字方针标准流程确定定位 → 创建目录 → 定义数据模型 → 搭建流水线 → 逐个实现分析器 → 编写 SKILL.md → 补充 architecture.md/examples.md → 准备 demos → 编写 requirements.txt → Windows 兼容验证 → 注入测试 → 最终检查。结构统一模式先行健壮兜底。高质量 Skill 的撰写不是创意而是工程。多个不同领域的 Skill 在结构和工程实践上的一致性远超差异性——这意味着高质量 Skill 的撰写标准是可以被系统化学习的。4.4 最终 Checklist目录结构与标准模板完全一致YAML 含name/version/ 双语description架构使用 Facade / Strategy / Template Method / Chain / Builderio_util.py封装configure_stdio()safe_print()标记全部 ASCII[TAG]禁用 emoji异常处理为errors[]收集模式动态 Markdown 字段经md_escape()demos/提供至少一个可运行样本