名称： skill-writer
描述： 为 ClawdHub/MoltHub 编写高质量的智能体技能（SKILL.md 文件）。适用于从零创建新技能、结构化技能内容、编写有效的元数据和描述、选择章节模式，或遵循面向智能体的技术文档最佳实践。
元数据： {"clawdbot":{"emoji":"✍️","requires":{"anyBins":["npx"]},"os":["linux","darwin","win32"]}}

技能编写器

为 ClawdHub 注册表编写结构良好、高效的 SKILL.md 文件。涵盖技能格式规范、元数据模式、内容模式、示例质量以及常见反面模式。

何时使用

• 从零开始创建新技能
• 将技术内容结构化为智能体技能
• 编写能被注册表正确索引的元数据
• 为不同类型的技能选择章节组织方式
• 在发布前审查自己的技能

SKILL.md 格式

一个技能是一个包含 YAML 元数据的单一 Markdown 文件。智能体按需加载并遵循其指令。

---
名称： my-skill-slug
**描述：** 一句话描述何时使用此技能。
**元数据：** {"clawdbot":{"emoji":"🔧","requires":{"anyBins":["tool1","tool2"]},"os":["linux","darwin","win32"]}}
---

# 技能标题

一段关于此技能涵盖内容的摘要。

## 何时使用

- 触发场景的要点列表

## 主要内容章节

### 包含示例的子章节

代码块、命令、模式...

## 技巧

- 实用建议要点

元数据模式

name (必需)

技能的标识符（slug）。必须与发布时使用的名称匹配。

名称： my-skill

规则：
- 小写，用连字符连接：csv-pipeline、git-workflows
- 无空格，无下划线
- 保持简短且描述性（1-3个词）
- 发布前检查 slug 是否冲突：npx molthub@latest search "your-slug"

description (必需)

最重要的字段。它用于：
1. 注册表进行语义搜索索引（向量嵌入）
2. 智能体决定是否激活该技能
3. 用户在浏览搜索结果时看到

# 良好：具体触发器和范围
**描述：** 为任何项目类型编写 Makefile。适用于设置构建自动化、定义多目标构建、管理任务间依赖、创建项目级任务运行器，或将 Make 用于非 C 项目（Go、Python、Docker、Node.js）。也涵盖 Just 和 Task 作为现代替代方案。

# 不佳：模糊，无触发器
**描述：** 关于 Makefile 的技能。

# 不佳：太长（在搜索结果中会被截断）
**描述：** 此技能涵盖关于 Makefile 的一切，包括变量、目标、先决条件、模式规则、自动变量、伪目标、条件逻辑、多目录构建、包含、静默执行，以及作为现代替代方案的 Just 和 Task，适用于使用 Go、Python、Docker 或 Node.js 的项目...

有效描述的模式：

[技能作用]。适用于 [触发器 1]、[触发器 2]、[触发器 3]。也涵盖 [相关主题]。

metadata (必需)

包含 clawdbot 模式的 JSON 对象：

**元数据：** {"clawdbot":{"emoji":"🔧","requires":{"anyBins":["make","just"]},"os":["linux","darwin","win32"]}}

字段：
- emoji：在注册表列表中显示的单个表情符号
- requires.anyBins：技能所需的 CLI 工具数组（至少有一个必须可用）
- os：支持的平台数组："linux"、"darwin" (macOS)、"win32" (Windows)

谨慎选择 requires.anyBins：

# 良好：列出技能命令实际使用的工具
"requires": {"anyBins": ["docker", "docker-compose"]}

# 不佳：列出每个系统都有的通用工具
"requires": {"anyBins": ["bash", "echo"]}

# 适用于通过多个工具工作的技能
"requires": {"anyBins": ["make", "just", "task"]}

内容结构

“何时使用”章节

始终在标题段落之后立即包含此章节。它告诉智能体（和用户）此技能适用的具体场景。

## 何时使用

- 自动化构建、测试、代码检查、部署命令
- 定义任务间的依赖关系（先构建后测试）
- 创建项目级任务运行器
- 用简短的目标替换冗长的 CLI 命令

规则：
- 4-8 个要点
- 每个要点是一个具体场景，而非抽象概念
- 以动词或动名词开头：“自动化...”、“调试...”、“转换...”
- 不要逐字重复描述字段的内容

主要内容章节

按任务组织，而非按概念。智能体需要为特定情况找到正确的命令。

## 良好：按任务组织
## 编码与解码
### Base64
### URL 编码
### 十六进制

## 不佳：按抽象概念组织
## 编码理论
## 编码类型
## 高级主题

代码块

每个章节应至少包含一个代码块。没有代码块的技能是观点，而非工具。

## 良好：具体、可运行的示例
```bash
# 将字符串编码为 Base64
echo -n "Hello, World!" | base64
# SGVsbG8sIFdvcmxkIQ==
```

## 不佳：抽象描述
Base64 编码使用 64 个字符的字母表将二进制数据转换为 ASCII 文本...

代码块最佳实践：
- 始终指定语言 (bash、python、javascript、yaml、sql 等)
- 在命令下方的注释中显示输出
- 使用实际值，而非 foo/bar（使用 myapp、api-server、真实的 IP 格式）
- 将最常见的情况放在前面，然后是变体
- 为非显而易见的标志或参数添加行内注释

多语言覆盖

如果技能适用于多种语言，使用一致的章节结构：

## 哈希

### Bash
```bash
echo -n "Hello" | sha256sum

JavaScript

const crypto = require('crypto');
crypto.createHash('sha256').update('Hello').digest('hex');

Python

import hashlib
hashlib.sha256(b"Hello").hexdigest()

顺序：Bash 优先（最通用），然后按主题的流行度排序。

### “技巧”章节

每个技能都以技巧章节结尾。这些是提炼出的智慧——能节省数小时调试时间的东西。

```markdown
## 技巧

- Makefile 的头号错误：使用空格而非制表符进行缩进。
- SHA-256 是完整性检查的标准。MD5 可用于去重，但已不适用于加密用途。
- 如果适用夏令时，切勿在凌晨 1:00-3:00 安排关键的 cron 任务。

规则：
- 5-10 个要点
- 每个技巧是独立的见解（不依赖其他技巧）
- 优先考虑陷阱和非显而易见的行为，而非基本建议
- 避免“始终使用最佳实践”之类的陈词滥调

技能类型与模板

CLI 工具参考

适用于特定工具或命令族的技能。

---
名称： tool-name
**描述：** [工具作用]。适用于 [场景 1]、[场景 2]。
**元数据：** {"clawdbot":{"emoji":"🔧","requires":{"anyBins":["tool-name"]}}}
---

# 工具名称

[一段话：它的作用以及你为何使用它。]

## 何时使用
- [4-6 个场景]

## 快速参考
[最常见命令及示例]

## 常见操作
### [操作 1]
### [操作 2]

## 高级模式
### [模式 1]

## 故障排除
### [常见错误及修复]

## 技巧

语言/框架参考

适用于特定语言或框架中模式的技能。

---
名称： pattern-name
**描述：** [语言/框架] 中的 [模式]。适用于 [场景 1]、[场景 2]。
**元数据：** {"clawdbot":{"emoji":"📐","requires":{"anyBins":["runtime"]}}}
---

# 模式名称

## 何时使用

## 快速参考
[速查表 / 语法摘要]

## 模式
### [模式 1 — 包含完整示例]
### [模式 2 — 包含完整示例]

## 跨语言比较（如适用）

## 反面模式
[不应做什么，并解释原因]

## 技巧

工作流/流程指南

适用于多步骤流程的技能。

---
名称： workflow-name
**描述：** [工作流描述]。适用于 [场景 1]、[场景 2]。
**元数据：** {"clawdbot":{"emoji":"🔄","requires":{"anyBins":["tool1","tool2"]}}}
---

# 工作流名称

## 何时使用

## 先决条件
[首先需要设置什么]

## 逐步指南
### 步骤 1: [操作]
### 步骤 2: [操作]
### 步骤 3: [操作]

## 变体
### [针对不同上下文的变体]

## 故障排除

## 技巧

反面模式

过于抽象

# 不佳
## 错误处理
错误处理对于健壮的应用程序很重要。你应该始终妥善处理错误，以防止意外崩溃...

# 良好
## 错误处理
```bash
# Bash：在任何错误时退出
set -euo pipefail

# 退出时清理的陷阱
trap 'rm -f "$TMPFILE"' EXIT

### 过于狭窄

```markdown
# 不佳：仅对一种特定情况有用
---
名称： react-useeffect-cleanup
**描述：** 如何在 React 中清理 useEffect 钩子
---

# 良好：足够广泛，成为真正的参考
---
名称： react-hooks
**描述：** React 钩子模式。适用于处理 useState、useEffect、useCallback、useMemo、自定义钩子或调试钩子相关问题。
---

无示例的长篇大论

如果任何章节超过 10 行没有代码块，说明文本过多。用示例将其分解。

缺少交叉引用

如果你的技能提到另一个拥有自己技能的工具或概念，请注明：

# 对于 Docker 网络问题，请参阅 `container-debug` 技能。
# 对于正则表达式语法细节，请参阅 `regex-patterns` 技能。

过时的命令

验证每个命令在当前工具版本下是否有效。常见陷阱：
- Docker Compose: docker-compose (v1) 与 docker compose (v2)
- Python: pip 与 pip3，python 与 python3
- Node.js: CommonJS (require) 与 ESM (import)

篇幅指南

少于 150 行的技能可能缺乏示例。超过 700 行的技能应拆分为两个技能。

发布前检查清单

发布前，请验证：

1. 元数据是有效的 YAML — 通过粘贴到 YAML 验证器中进行测试
2. 描述以技能作用开头 — 而非“此技能...”或“用于...的技能”
3. 每个章节至少有一个代码块 — 主要内容中没有纯文本章节
4. 命令实际有效 — 在干净环境中测试
5. 没有遗留占位符值 — 搜索 TODO、FIXME、用作真实 URL 的 example.com
6. Slug 可用 — npx molthub@latest search "your-slug" 返回无精确匹配
7. requires.anyBins 列出真实依赖 — 技能命令实际调用的工具
8. 存在技巧章节 — 包含 5 个以上可操作、非显而易见的要点

发布

# 发布新技能
npx molthub@latest publish ./skills/my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --changelog "初始版本"

# 更新现有技能
npx molthub@latest publish ./skills/my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.1.0 \
  --changelog "新增关于 X 的章节"

# 验证已发布
npx molthub@latest search "my-skill"

技巧

• description 字段决定了技能的搜索排名。花在它上面的时间应超过任何单个内容章节。包含用户会搜索的特定动词和名词。
• 以最常见的用例开头。如果 80% 的用户需要“如何编码 Base64”，就把它放在“如何在 MessagePack 和 CBOR 之间转换”之前。
• 每个代码示例都应该是可复制粘贴的。如果需要未显示的设置，请添加设置步骤。
• 为智能体而写，而非为人。智能体需要清晰明确的指令，以便逐步遵循。避免“你可能想要考虑...”——应该说“当 Y 时，执行 X。”
• 通过让智能体在真实任务中使用你的技能来测试它。如果智能体无法遵循指令产生正确结果，说明技能需要改进。
• 优先使用 bash 代码块表示命令，即使在特定语言技能中也是如此。智能体通常通过 shell 操作，bash 块表示“运行此命令”。
• 不要重复 --help 已经提供的内容。专注于模式、组合以及 --help 没有教授的非显而易见的内容。
• 对技能进行语义化版本控制：补丁版本用于修复拼写错误，次版本用于新增章节，主版本用于重构。注册表会跟踪版本历史。