如何写出稳定可靠、触发精准的AI Skill？这篇文章分享的，是从10万行代码实践中提炼出来的专业方法论。

核心内容：

1. Skill的准确定义与核心结构 2. 入门级与专业级Skill的对比分析 3. 从脚本到专业工作手册的进阶路径

你是否曾遇到过：为AI Agent编写了一个Skill，它能正常执行，但总是触发不够精准、运行不够稳定，每逢几天就会冒出bug？这好比做菜——你照着网上的菜谱来做，味道是有了，但总觉得与大厨的手艺之间还差了些火候。

那欠缺的，正是专业性。

我长期维护着一个10万行级别的Skill（WeWrite公众号全流程助手），从最初的一个简单脚本逐步迭代发展而来。在这段过程中，我踩过不少坑，也总结了一套系统性的方法论，今天将它们完整分享出来。

先搞清楚：Skill 究竟是什么

30秒速览版：Skill = 给AI Agent的操作手册。

它不是单纯的提示词（prompt），也不是一份API文档，它是一份结构化的行动指南，用来告诉Agent：

• 何时应该被触发（trigger）
• 如何一步步完成任务（workflow）
• 何种情况下会出错以及如何应对（pitfall）
• 任务完成后怎样验证结果（verification）

一个Skill的物理结构大致如下：

my-skill/
├── SKILL.md              # 核心指令（必需）
├── scripts/              # 可执行脚本
│   └── helper.py
├── references/           # 参考文档
│   ├── api.md
│   └── best-practices.md
└── templates/            # 模板文件
    └── output.md

SKILL.md是唯一必不可少的文件，其余都是辅助性的。但专业级Skill与入门级Skill的关键差异，恰恰体现在这些辅助文件的配置质量上。

能运行 vs 专业稳定：一个直观的对比

我们通过两个真实案例来剖析差距。

案例 A：入门级 Skill（aihot）

这是一个查询AI资讯的Skill，核心功能正确，结构也算清晰。它的frontmatter如下：

---
name: aihot
description: AI HOT 资讯查询 Skill。当用户想知道"今天 AI 圈有什么"时使用。
---

工作流部分只有一段核心命令：

since=$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)
curl -s "https://aihot.virxact.com/api/public/items?mode=selected&since=$since"

能用吗？完全没问题。 239行代码，11KB大小，功能完整。

案例 B：专业级 Skill（WeWrite）

同样是完成一个任务，WeWrite这个公众号写作Skill则配备了更多元素：

维度	入门级 (aihot)	专业级 (WeWrite)
Frontmatter	name + description	完整元数据 + tags + related_skills + version
触发条件	一句话描述	20+ 触发关键词 + 反向触发词（何时不应使用）
工作流	1 个主路径	8 步流水线，每步都包含输入输出定义
错误处理	无	每个步骤都设定了 fallback 方案 + 已知坑位手册
辅助文件	无	references/ (7个文档) + scripts/ (5个脚本) + personas/ (人格库)
验证方法	手动测试	自动化质量检查（禁用词扫描、human-ness 评分）
迭代机制	无	history.yaml 记录每篇文章的元数据，避免重复

文件大小：11KB 对比 103KB+。 这并非刻意写长，而是每个字节都在解决一个具体且实际的问题。

专业 Skill 的五个核心维度

1. Frontmatter：Agent决定是否加载你Skill的唯一依据

这是最重要，也最容易被忽视的环节。

Agent在加载Skill之前，只能看到frontmatter里的 name 和 description。 一旦这两个字段写得不够清晰，你的Skill就像一本没有封面的书籍——内容再好也无人问津。

入门级写法：

---
name: my-skill
description: 帮我做 X 事
---

问题在于：描述过于笼统。"帮我做X事"很可能匹配任何请求，最终导致过度触发（在不该用时被加载），或者触发不准（在该用时未被选中）。

专业级写法：

---
name: commit-message-generator
description: |
  Use when the user wants to generate conventional commit messages based on
  staged git changes. Covers feat/fix/docs/refactor/test/chore types.
  Triggers on: "commit message", "生成提交信息", "git commit", "提交说明".
  Do NOT use for: general text writing, PR descriptions, or changelogs.
version: 1.2.0
author: your-name
license: MIT
metadata:
  hermes:
    tags: [git, commit, conventional-commits, automation]
    related_skills: [github-pr-workflow, github-code-review]
---

关键改进之处：

• description ≤ 1024 字符（Hermes系统的硬性限制），但必须将触发条件交代清楚
• 明确反向触发词（Do NOT use for）：以此减少误触发几率
• 添加 metadata：tags用于分类检索，related_skills用于关联推荐
• 版本号：方便进行后续的迭代追踪

2. 结构化指令：让Agent能“按图施工”

入门级的指令往往采用段落式描述：

先拉数据，然后处理一下，最后输出

问题在于，Agent对“处理一下”的理解很可能与你截然不同。

专业级则采用分步骤 + 表格 + 代码块的组合方式。下面是一个工作流片段的写法示例——先定义参数表，再给出命令：

参数	值	说明
端点	/api/public/items	主数据接口
mode	selected	精选模式（默认）
since	动态计算	最近 24 小时

# 计算时间窗口（兼容 macOS 和 Linux）
if [[ "$OSTYPE" == "darwin"* ]]; then
  since=$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)
else
  since=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)
fi

curl -sH "User-Agent: $UA" \
  "https://example.com/api/public/items?mode=selected&since=$since&take=50"

输出格式：JSON数组，每项包含 {id, title, category, url, published_at}。下一步则将输出传入Step 2进行过滤。

注意以下几个细节：

• 表格定义参数：Agent无需猜测
• 代码块可直接复制运行：不省略任何参数
• 明确输出格式：下一步流程清楚如何衔接
• 兼容性处理：分别考虑macOS和Linux的date命令差异

3. 错误处理：专业与业余的分水岭

入门级Skill假设一切顺利。专业级Skill则假设一定会出错。

下面是一段pitfalls章节的写法示例——每个坑都按“现象→原因→处理”三段式展开：

Pitfall 1：API返回空结果

items 数组为空，但HTTP状态码是200。原因：时间窗口内无数据，或 since 参数格式有误。

# 检查返回是否为空
response=$(curl -s "...")
count=$(echo "$response" | python3 -c "import sys,json; print(len(json.load(sys.stdin)))")
if [ "$count" -eq 0 ]; then
  echo "⚠️ 无数据，尝试扩大时间窗至 7 天"
  since=$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ)
  # 重试...
fi

Pitfall 2：User-Agent 被 403

直接curl返回403 Forbidden。原因：API端点设有UA黑名单。处理：所有curl命令必须携带浏览器UA。

Pitfall 3：编码问题

中文显示乱码。原因：远程终端locale不是UTF-8。处理：传递数据时使用纯ASCII JSON文件，不在命令行中硬编码中文。

专业Skill的pitfalls并非事后补充，而是在编写过程中同步记录的。 每次遇到问题就记下一条，慢慢积累下去就是竞争力。

4. 辅助文件体系：将 SKILL.md 控制在合理大小

SKILL.md有100,000字符的硬性限制（约36K tokens）。超过这个阈值，Agent在加载时就会发生截断。

当Skill复杂度提升时，解决方案不是一味地将SKILL.md写得更长，而是将其拆分到辅助文件中：

professional-skill/
├── SKILL.md                 # 核心（控制在 8-15K 字符）
├── references/
│   ├── api-reference.md     # API 完整文档
│   ├── error-codes.md       # 错误码对照表
│   └── best-practices.md    # 最佳实践
├── scripts/
│   ├── validate.sh          # 自动化验证脚本
│   └── deploy.sh            # 部署脚本
└── templates/
    └── output-template.md   # 输出模板

在SKILL.md里仅保留简短引用指向具体细节，比如API文档部分可如此编写：

详见 `references/api-reference.md`，覆盖以下端点：
- 数据采集（3 个端点）
- 内容发布（2 个端点）
- 媒体上传（1 个端点）

端点	用途	认证
/api/data	数据采集	无
/api/publish	发布内容	OAuth
/api/media	上传图片	OAuth

原则：SKILL.md放置决策逻辑和关键路径，references存放参考信息，scripts存放可执行逻辑。

5. 验证机制：能自动化检查就不要依赖人眼

专业Skill都具备自检能力。最基础的是验证清单，发布前逐项确认：

• [ ] Frontmatter 以 --- 开头，无前导空白行
• [ ] name ≤ 64 字符，仅小写字母 + 连字符
• [ ] description ≤ 1024 字符，包含触发词 + 反向触发词
• [ ] 所有代码块可直接复制运行（已实测）
• [ ] curl 命令都带了正确的 User-Agent
• [ ] 时间窗口计算兼容 macOS 和 Linux
• [ ] pitfalls 至少覆盖 3 个已知错误场景
• [ ] 总文件大小 ≤ 100,000 字符
• [ ] related_skills 引用的 Skill 确实存在

进阶做法是编写一个自动化验证脚本：

#!/usr/bin/env python3
"""Skill 质量检查工具"""
import yaml, re, pathlib

def validate_skill(skill_path: str) -> dict:
    path = pathlib.Path(skill_path)
    content = path.read_text()
    
    issues = []
    
    # 检查 1: frontmatter 格式
    if not content.startswith("---"):
        issues.append("❌ 必须以 --- 开头")
    
    # 检查 2: description 长度
    fm = yaml.safe_load(content.split("---")[1])
    desc_len = len(fm.get("description", ""))
    if desc_len > 1024:
        issues.append(f"❌ description {desc_len} 字符，超过 1024 限制")
    
    # 检查 3: 代码块数量（教程型 Skill 要求 ≥ 5）
    code_blocks = re.findall(r"```[\s\S]*?```", content)
    if len(code_blocks) < 5:
        issues.append(f"⚠️ 只有 {len(code_blocks)} 个代码块，建议 ≥ 5")
    
    # 检查 4: 是否有 pitfalls 章节
    if "## Common Pitfalls" not in content and "## pitfalls" not in content.lower():
        issues.append("⚠️ 缺少 pitfalls 章节")
    
    return {
        "skill": skill_path,
        "valid": len([i for i in issues if i.startswith("❌")]) == 0,
        "issues": issues,
        "stats": {
            "size_chars": len(content),
            "code_blocks": len(code_blocks),
            "has_pitfalls": "pitfalls" in content.lower(),
        }
    }

if __name__ == "__main__":
    import sys, json
    result = validate_skill(sys.argv[1] if len(sys.argv) > 1 else "SKILL.md")
    print(json.dumps(result, indent=2, ensure_ascii=False))

运行效果：

$ python3 validate_skill.py SKILL.md
{
  "skill": "SKILL.md",
  "valid": true,
  "issues": [],
  "stats": {
    "size_chars": 12458,
    "code_blocks": 7,
    "has_pitfalls": true
  }
}

实战：从零开始编写一个专业 Skill

理论部分讲完了，现在动手来写一个。场景：Git提交信息自动生成器。

第一步：创建目录结构

mkdir -p commit-gen/{scripts,references,templates}
touch commit-gen/SKILL.md

第二步：编写 Frontmatter

---
name: commit-message-generator
description: |
  Use when user wants to generate conventional commit messages from staged
  git changes. Supports feat/fix/docs/refactor/test/chore/style/ci/perf/revert
  types. Triggers on: "commit message", "提交信息", "git commit", "生成提交",
  "commit msg". Do NOT use for: PR descriptions, changelogs, release notes.
version: 1.0.0
author: your-name
license: MIT
metadata:
  hermes:
    tags: [git, commit, conventional-commits, automation]
    related_skills: [github-pr-workflow]
---

第三步：编写核心工作流

Skill的主体部分从获取diff开始。如果没有staged变化，先提示用户 git add：

git diff --cached --no-color

然后根据变更内容判断commit type：

变更特征	type	示例
新功能/新文件	feat	feat: add user login endpoint
Bug 修复	fix	fix: null pointer in auth middleware
文档变更	docs	docs: update API reference
重构（不改变行为）	refactor	refactor: extract validation logic
测试相关	test	test: add coverage for auth flow
构建/CI 相关	ci	ci: upgrade node version to 20
性能优化	perf	perf: reduce DB queries by 50%

生成的commit message遵循Conventional Commits规范：第一行 type(scope): subject（≤ 50字符），第二行为空行，正文可选（说明why而非what），页脚可选（Breaking Change / Closes #123）。示例输出：

feat(auth): add OAuth2 Google login

- Integrate with Google Identity Platform
- Support token refresh flow
- Add unit tests for token validation

Closes #42

最后用户确认后执行：

git commit -e -F /tmp/commit-msg.txt

第四步：补充 Pitfalls 和 Checklist

Pitfall 1：空diff — 用户忘记 git add 就触发了Skill。处理：检测staged变化数量，为0时给出提示而非直接报错。

Pitfall 2：subject过长 — Conventional Commits建议subject ≤ 50字符。处理：生成后自动检查长度，若超长则进行拆分。

Pitfall 3：scope歧义 — 同一个diff可能涉及多个模块。处理：取变化文件最多的目录作为scope，或省略scope。

Verification Checklist：

• [ ] 支持 9 种 commit type
• [ ] subject 长度检查（≤ 50 字符）
• [ ] 空 diff 优雅降级
• [ ] -e flag 允许用户编辑
• [ ] 兼容 Git 2.0+

运行验证：

python3 scripts/validate_skill.py commit-gen/SKILL.md

这就是一个完整而专业的Skill scaffold。 以此为起点，根据实际需求进行迭代即可。

从能运行到专业稳定的检查清单

最后，我为你准备了一份速查表。下次编写Skill时可以逐项打勾核对：

层次	检查项	入门	专业
Frontmatter	name/description 清晰	✅	✅
	包含触发词 + 反向触发词	❌	✅
	有 version/author/metadata	❌	✅
结构	分步骤工作流	✅	✅
	表格定义参数	❌	✅
	代码块可直接运行	⚠️	✅
	明确输入输出格式	❌	✅
鲁棒性	有 pitfalls 章节	❌	✅
	覆盖 ≥ 3 个错误场景	❌	✅
	兼容性处理（OS/版本）	❌	✅
工程化	拆分 references/	❌	✅
	有验证脚本	❌	✅
	有历史记录机制	❌	✅
总工作量		30 分钟	2-4 小时

结论：入门级Skill解决的是“能不能实现”的问题，而专业级Skill解决的是“能不能稳定运行100次”的问题。

如果某个Skill只需使用一次，入门级也就足够了。但若它将被反复调用、提供给他人使用，或承载关键业务流程，那么花时间将其打磨到专业级是值得的——回报是调试时间的数量级减少。

本文基于Hermes Agent Skill系统（hermes.nousresearch.com）和WeWrite公众号流水线的实战经验写成。文中所有代码片段均可直接复制运行。