技能撰写器

为ClawdHub注册表编写结构良好、有效的SKILL.md文件。涵盖技能格式规范、前言模式、内容模式、示例质量和常见反模式。

使用时机

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

SKILL.md格式

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

---
name: my-skill-slug
description: One-sentence description of when to use this skill.
metadata: {"clawdbot":{"emoji":"🔧","requires":{"anyBins":["tool1","tool2"]},"os":["linux","darwin","win32"]}}
---

# Skill Title

One-paragraph summary of what this skill covers.

## When to Use

- Bullet list of trigger scenarios

## Main Content Sections

### Subsection with examples

Code blocks, commands, patterns...

## Tips

- Practical advice bullets

前言模式

名称（必填）

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

name: my-skill

规则：

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

描述（必填）

最重要的字段。这是用于：

1. 注册表进行语义搜索（向量嵌入）的索引依据
2. 智能体读取以决定是否激活此技能
3. 用户在浏览搜索结果时看到的内容

# GOOD: Specific triggers and scope
description: Write Makefiles for any project type. Use when setting up build automation, defining multi-target builds, managing dependencies between tasks, creating project task runners, or using Make for non-C projects (Go, Python, Docker, Node.js). Also covers Just and Task as modern alternatives.

# BAD: Vague, no triggers
description: A skill about Makefiles.

# BAD: Too long (gets truncated in search results)
description: This skill covers everything you need to know about Makefiles including variables, targets, prerequisites, pattern rules, automatic variables, phony targets, conditional logic, multi-directory builds, includes, silent execution, and also covers Just and Task as modern alternatives to Make for projects that use Go, Python, Docker, or Node.js...

有效描述的模式：

[What it does]. Use when [trigger 1], [trigger 2], [trigger 3]. Also covers [related topic].

元数据（必填）

符合以下架构的JSON对象：clawdbot架构：

metadata: {"clawdbot":{"emoji":"🔧","requires":{"anyBins":["make","just"]},"os":["linux","darwin","win32"]}}

字段：

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

请谨慎选择requires.anyBins：

# Good: lists the actual tools the skill's commands use
"requires": {"anyBins": ["docker", "docker-compose"]}

# Bad: lists generic tools every system has
"requires": {"anyBins": ["bash", "echo"]}

# Good for skills that work via multiple tools
"requires": {"anyBins": ["make", "just", "task"]}

内容结构

"何时使用" 章节

此章节必须紧接在标题段落之后。它向代理（及用户）说明本技能适用的具体场景。

## When to Use

- Automating build, test, lint, deploy commands
- Defining dependencies between tasks (build before test)
- Creating a project-level task runner
- Replacing long CLI commands with short targets

规则：

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

主要内容章节

按任务而非概念组织。代理需要为特定情况找到合适的命令。

## GOOD: Organized by task
## Encode and Decode
### Base64
### URL Encoding
### Hex

## BAD: Organized by abstraction
## Theory of Encoding
## Encoding Types
## Advanced Topics

代码块

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

## GOOD: Concrete, runnable example
```bash
# Encode a string to Base64
echo -n "Hello, World!" | base64
# SGVsbG8sIFdvcmxkIQ==
```

## BAD: Abstract description
Base64 encoding converts binary data to ASCII text using a 64-character alphabet...

代码块最佳实践：

• 始终指定编程语言（bash、python、javascript、yaml、sql等）
• 在命令下方以注释形式展示输出使用实际值
• ，而非foo/bar（应使用myapp、api-server、真实IP格式等）, real IP formats)
• 首先包含最常见的情况，然后是变体
• 为非显而易见的标志或参数添加内联注释

多语言覆盖

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

## Hashing

### 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()

Order: Bash first (most universal), then by popularity for the topic.

### The "Tips" Section

End every skill with a Tips section. These are the distilled wisdom — the things that save hours of debugging.

```markdown
## Tips

- The number one Makefile bug: using spaces instead of tabs for indentation.
- SHA-256 is the standard for integrity checks. MD5 is fine for dedup but broken for cryptographic use.
- Never schedule critical cron jobs between 1:00-3:00 AM if DST applies.

规则：

• 5-10个要点
• 每条提示都是一个独立的见解（不依赖于其他提示）
• 优先考虑陷阱和非显而易见的行为，而非基本建议
• 避免使用“始终遵循最佳实践”的陈词滥调

技能类型与模板

CLI工具参考

适用于关于特定工具或命令系列的技能。

---
name: tool-name
description: [What tool does]. Use when [scenario 1], [scenario 2].
metadata: {"clawdbot":{"emoji":"🔧","requires":{"anyBins":["tool-name"]}}}
---

# Tool Name

[One paragraph: what it does and why you'd use it.]

## When to Use
- [4-6 scenarios]

## Quick Reference
[Most common commands with examples]

## Common Operations
### [Operation 1]
### [Operation 2]

## Advanced Patterns
### [Pattern 1]

## Troubleshooting
### [Common error and fix]

## Tips

语言/框架参考

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

---
name: pattern-name
description: [Pattern] in [language/framework]. Use when [scenario 1], [scenario 2].
metadata: {"clawdbot":{"emoji":"📐","requires":{"anyBins":["runtime"]}}}
---

# Pattern Name

## When to Use

## Quick Reference
[Cheat sheet / syntax summary]

## Patterns
### [Pattern 1 — with full example]
### [Pattern 2 — with full example]

## Cross-Language Comparison (if applicable)

## Anti-Patterns
[What NOT to do, with explanation]

## Tips

工作流程/过程指南

适用于关于多步骤过程的技能。

---
name: workflow-name
description: [Workflow description]. Use when [scenario 1], [scenario 2].
metadata: {"clawdbot":{"emoji":"🔄","requires":{"anyBins":["tool1","tool2"]}}}
---

# Workflow Name

## When to Use

## Prerequisites
[What needs to be set up first]

## Step-by-Step
### Step 1: [Action]
### Step 2: [Action]
### Step 3: [Action]

## Variations
### [Variation for different context]

## Troubleshooting

## Tips

反模式

过于抽象

# BAD
## Error Handling
Error handling is important for robust applications. You should always
handle errors properly to prevent unexpected crashes...

# GOOD
## Error Handling
```bash
# Bash: exit on any error
set -euo pipefail

# Trap for cleanup on exit
trap 'rm -f "$TMPFILE"' EXIT

### Too narrow

```markdown
# BAD: Only useful for one specific case
---
name: react-useeffect-cleanup
description: How to clean up useEffect hooks in React
---

# GOOD: Broad enough to be a real reference
---
name: react-hooks
description: React hooks patterns. Use when working with useState, useEffect, useCallback, useMemo, custom hooks, or debugging hook-related issues.
---

大段文字缺少示例

如果任何章节超过10行没有代码块，就说明文字内容过多。请用示例来分解内容。

缺少交叉引用

如果你的技能提到了另一个有独立技能的工具或概念，请注明：

# For Docker networking issues, see the `container-debug` skill.
# For regex syntax details, see the `regex-patterns` skill.

过时的命令

验证每条命令在当前工具版本下是否有效。常见陷阱：

• Docker Compose：docker-compose（版本1）对比docker compose（版本2）
• Python：pip对比pip3、python对比python3
• Node.js：CommonJS（require）对比ESM（import尺寸指南

指标

发布清单

发布前，请验证：

前置元数据是有效的YAML

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

发布

# Publish a new skill
npx molthub@latest publish ./skills/my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --changelog "Initial release"

# Update an existing skill
npx molthub@latest publish ./skills/my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.1.0 \
  --changelog "Added new section on X"

# Verify it's published
npx molthub@latest search "my-skill"

技巧

• 描述字段是你的技能搜索排名的关键。花在它上面的时间应该超过任何一个单一的内容部分。要包含用户可能搜索的具体动词和名词。以最常见的用例开头。如果80%的用户需要"如何编码Base64"，就把这个放在"如何在MessagePack和CBOR之间转换"之前。
• 每个代码示例都应该是可以直接复制粘贴的。如果需要未显示的设置，请补充设置步骤。
• 为智能体编写，而不是为人类。智能体需要可以逐步遵循的明确指令。避免使用"你可能想要考虑"——直接说"当Y时，执行X。"
• 通过让智能体在实际任务中使用你的技能来测试它。如果智能体无法按照指令产生正确结果，那么该技能就需要改进。
• 优先使用
• bash代码块表示命令，即使在特定语言的技能中也是如此。智能体通常通过shell操作，bash代码块表示"运行这个"。不要重复
• --help--help已提供的。专注于模式、组合以及那些--help不会教的内容。
• 按语义版本管理你的技能：补丁版本用于修正拼写错误，次要版本用于新增章节，主要版本用于重构。注册表会追踪版本历史。