中文 Skill 创作规范
面向 AI Agent 的中文 Skill 设计、实现与发布的完整规范。适用于 SkillHub、ClawdHub、GitHub Marketplace 等多平台发布。
核心原则（三条红线）
1. 全部中文
- ✅ 正文、触发词、FAQ、反模式、错误提示 → 全部简体中文
- ✅ 仅
name、slug、代码块、命令保留英文 - ❌ 禁止中英混杂 description（AI 无法准确匹配触发词）
2. AI-Native 设计
根本问题：AI 不会调用"给人看"的 Skill。必须遵循：
- 解决 AI 做不了的事：格式转换、并发 HTTP、批量处理、编码修复——这些都是 AI 原生工具链的盲区
- 一个 Skill 只做一件事：多用途 Skill 触发条件模糊，AI 不敢调用
- 脚本驱动：
bash scripts/do.sh <输入> <输出>— AI 看到这行就知道可以 fire-and-forget - 明确 I/O 契约：输入是什么（文件路径？URL？目录？）、输出是什么（新文件？报告文本？）
详见 references/ai-native-patterns.md。
3. SkillHub 5 分全覆盖
SkillHub 评测 5 个维度，每个维度必须达到关键要求：
| 维度 | 5分关键 |
|---|---|
| 适应性 | 能力边界（✅能做什么 + ❌不能做什么）+ 触发关键词 + 不触发说明 |
| 规范性 | FAQ（5条）+ 反模式（3条）+ 多示例 + 模块化文件结构 |
| 有效性 | 输入验证 + 错误处理 + 可用脚本 + 具体示例 |
| 可靠性 | 空/坏输入降级 + 依赖缺失提示 + 功能完整 |
| 可信度 | 全中文 + 安全扫描 + 零外部API |
详见 references/skillhub-scoring.md。
SKILL.md 标准模板
---
name: <英文slug>
slug: <英文slug>
displayName: <中文名称>
description: >-
<做什么>。<为什么AI需要它>。触发词：<关键词列表>。输入：<格式>。输出：<格式>。
version: 1.0.0
author: caizhongxian
---
# <中文标题>
一句话说明核心价值。
## 触发方式
**关键词触发**：<列举触发词和组合>
**不触发的情况**：<列举不应触发的场景>
## 能力边界
### ✅ 可以做的
### ❌ 不能做的
## 错误处理
<至少3种异常场景的处理方式>
## 使用脚本
```bash
bash scripts/<脚本名>.sh <参数说明>
FAQ（至少5条）
Q: <常见问题>
<答案>
反模式（至少3条）
- ❌ <错误用法> → <正确做法>
文件结构
```
触发词设计规则
好的 description 决定 AI 是否会调用你的 Skill：
- ✅
触发词：转换、转格式、convert、export as + 文件路径 + 目标格式 - ✅
TRIGGER: user says "抓取"/"scrape"/"提取内容" + URL - ❌
一个强大的文件处理工具（AI 不知道什么时候该用） - ❌
支持多种场景和灵活配置（太模糊，AI 不会匹配）
常见错误
- description 写教程 → 应该写成触发规则
- 一个 Skill 干五件事 → 拆成 5 个独立 Skill
- 没有能力边界 → 必须写清楚不能做什么
- 没有错误处理 → 输入异常时 AI 会卡住
- 中英混杂 → 触发词匹配失败
参考文件
references/ai-native-patterns.md— AI-Native Skill 设计模式详解references/skillhub-scoring.md— SkillHub 5分评测标准完整版references/devils-advocate-case-study.md— 魔鬼代言人评测修复案例
