SkillHub 技能创作规范
面向 SkillHub 的中文 AI Agent 技能创作指南——从设计到 5 分发布的全流程。
AI-Native 设计原则
> 给 AI 写的技能，不是给人看的教材。
| 旧思维 | 新思维 |
|---|---|
| "支持丰富的功能" | 精确列出触发关键词 + 输入格式 + 输出格式 |
| 教程式："首先…然后…建议…" | 指令式：bash scripts/xxx.sh <input> <output> |
| 一个 Skill 做 5 件事 | 一个 Skill 专做一件事 |
| 解决"人想学什么" | 解决 "AI 自己做不了什么" |
| 依赖人去发现和使用 | AI 遇到关键词自动触发 |
description 硬性要求（评测关键）
description 末尾必须包含三个标签，缺失直接扣分：
description: >-
功能一句话。
TRIGGER: 触发词1、触发词2、触发词3
INPUT: 文件路径或场景描述
OUTPUT: 处理后的文件或分析报告
> 已验证：13 个 skill 的 v1.2.0 均补全了 TRIGGER/INPUT/OUTPUT。评测系统会检测这些关键词。
SkillHub 五维评测标准
1. adaptability — 适应性
boundary：必须声明 ✅能做什么 + ❌不能做什么 + 不适用的具体场景类型。模糊边界 = 扣分。
trigger：明确的触发关键词（中英双语）+ 不触发说明 + 同类型Skill区分指南。
2. convention — 规范性
antiPatternFaq：≥4 条反模式 + ≥5 条 FAQ。FAQ 必须覆盖"为什么用这个框架""与其他Skill区别""输出可靠性如何"。
docQuality：≥2 个不同场景的完整示例（输入→处理逻辑→输出）。只有一个示例 = 最高 4.5。
progressive：内容由浅入深——核心规则→角色/原则→示例→FAQ。勿一上来就堆大量信息。
structure：模块化拆分。推荐：SKILL.md + knowledge/（或 references/）目录。单一巨型文件 = 最高 4.0。
3. effectiveness — 有效性
accuracy：规则定义清晰无歧义。禁止"你可以考虑…"类模糊表述。
completeness：覆盖多维度场景。书单类 Skill 需覆盖多个领域示例。
creativity：独特的视角/框架（如用书中知识解决现实问题）。
usability：输入→输出链路清晰。模板固定、不偏离。
4. reliability — 可靠性
errorHandling：≥3 种降级场景（空输入/格式错误/超出能力范围），每种配具体提示文案。
func：输入验证逻辑 + 参数处理说明。
stability：纯规则型天然稳定；有脚本的确保幂等。
5. trust — 可信度
domestic：全中文 + 国内网络直连 + 零外部 API 依赖。
scan：通过平台安全扫描。
SKILL.md 必备结构
---
name: skill-name # 英文 slug
slug: skill-name
displayName: 中文显示名 # 必填！
description: >-
功能一句话。TRIGGER: 触发词。INPUT: 输入格式。OUTPUT: 输出格式。
version: 1.0.0
author: caizhongxian
---
必填章节：触发方式 → 能力边界 → 错误处理 → 使用方式 → FAQ → 反模式 → 文件结构。
书单类 Skill 知识库规范
目录结构：
skill-name/
├── SKILL.md
└── knowledge/
└── principles.md
knowledge 文件每条原则：编号 + 名称 + 原文引用 + 核心思想 + 现代应用场景 + 具体案例。100-300 字/条。
发布流程
# 验证
skillhub publish <path> --dry-run
# 发布（间隔 ≥15 秒防限流）
skillhub publish <path> --version x.x.x --changelog "描述"
反模式
- ❌ 给人写的教程式 Skill → AI 不会主动调用
- ❌ description 无触发关键词 → AI 不知道何时加载
- ❌ 一个大 Skill 想干所有事 → 拆成多个单一职责的
- ❌ 缺少"不能做什么"声明 → 评测扣分
- ❌ 连续发布无间隔 → 触发频率限制（HTTP 429/566）
- ❌ slug 与他人冲突 →
skillhub publish --dry-run能提前发现 - ❌ knowledge/ 或 references/ 目录缺失 → 文件结构分最高 4.0。每个 Skill 至少含一个 knowledge/ 子目录
- ❌ description 末尾缺 TRIGGER/INPUT/OUTPUT → 评测系统检测不到触发映射，直接降分
真实评测数据
devil's-advocate v1.0.0 各维度得分和修复对照详见 skillhub-publishing 的 evaluation-data.md。关键发现：
- 最大扣分项：antiPatternFaq(3.5)、errorHandling(3.5)、trigger(3.8)
- 最容易满分项：domestic(5.0)、scan(5.0)
- 各子项名称：boundary、trigger、antiPatternFaq、docQuality、progressive、structure、accuracy、completeness、creativity、usability、errorHandling、func、stability、domestic、scan
FAQ
Q: 为什么我的技能下载量低？
检查：description 里有没有触发关键词？Skill 做的是不是 AI 自己干不了的事？输入输出格式是不是足够明确？
Q: 评测多久出结果？
通常提交后 24-48 小时。
Q: 可以用英语吗？
本用户的永久指令：全部用简体中文。仅 name/slug/代码保留英文。
参考
已发布的 5 分参考 Skill：
- devils-advocate (144693) — 魔鬼代言人批判性评审
- sun-tzu-strategy (148272) — 孙子兵法策略引擎
- 更多见 SkillHub 搜索 @caizhongxian
