介绍
# Skill Writer
为 ClawdHub 注册表编写结构良好、有效的 SKILL.md 文件。涵盖技能格式规范、Frontmatter 架构、内容模式、示例质量以及常见的反模式。
## 何时使用
- 从头开始创建新技能 - 将技术内容构建为代理技能 - 编写注册表可正确索引的 Frontmatter - 为不同类型的技能选择章节组织结构 - 在发布前审查你自己的技能
## SKILL.md 格式
技能是一个带有 YAML Frontmatter 的 Markdown 文件。代理会按需加载它并遵循其中的指令。
```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 ```
## Frontmatter 架构
### `name` (必需)
技能的 slug 标识符。必须与你发布时使用的名称匹配。
```yaml name: my-skill ```
规则： - 小写，连字符分隔：`csv-pipeline`、`git-workflows` - 无空格，无下划线 - 保持简短且具有描述性（1-3 个单词） - 发布前检查 slug 冲突：`npx molthub@latest search "your-slug"`
### `description` (必需)
最重要的字段。它决定了： 1. 注册表为其建立语义索引的内容（向量嵌入） 2. 代理读取以决定是否激活该技能的内容 3. 用户浏览搜索结果时看到的内容
```yaml # 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]. ```
### `metadata` (必需)
包含 `clawdbot` 架构的 JSON 对象：
```yaml metadata: {"clawdbot":{"emoji":"🔧","requires":{"anyBins":["make","just"]},"os":["linux","darwin","win32"]}} ```
字段： - **`emoji`**：在注册表列表中显示的单个表情符号 - **`requires.anyBins`**：技能所需的 CLI 工具数组（至少有一个必须可用） - **`os`**：支持的平台数组：`"linux"`、`"darwin"` (macOS)、`"win32"` (Windows)
请谨慎选择 `requires.anyBins`： ```yaml # 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"]} ```
## 内容结构
### “何时使用”章节
始终在标题段落之后立即包含此部分。它告知代理（以及用户）该技能适用的具体场景。
```markdown ## 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 个要点 - 每个要点是一个具体的场景，而不是抽象的概念 - 以动词或动名词开头：“Automating...”、“Debugging...”、“Converting...” - 不要逐字重复 description 字段
### 主要内容章节
按任务而非概念组织。代理需要针对特定情况找到正确的命令。
```markdown ## GOOD: Organized by task ## Encode and Decode ### Base64 ### URL Encoding ### Hex
## BAD: Organized by abstraction ## Theory of Encoding ## Encoding Types ## Advanced Topics ```
### 代码块
每个章节应至少包含一个代码块。没有代码块的技能只是观点，而非工具。
````markdown ## 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 格式） - **首先包含最常见的情况**，然后是变体 - 为不明显的标志或参数**添加内联注释**
### 多语言覆盖
如果技能适用于多种语言，请使用一致的章节结构：
```markdown ## Hashing
### Bash ```bash echo -n "Hello" | sha256sum ```
### JavaScript ```javascript const crypto = require('crypto'); crypto.createHash('sha256').update('Hello').digest('hex'); ```
### Python ```python import hashlib hashlib.sha256(b"Hello").hexdigest() ``` ```
顺序：Bash 在前（最通用），然后按主题的流行度排列。
### “提示”章节
每个技能都以提示章节结束。这些是提炼出的智慧——那些能节省数小时调试时间的内容。
```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 工具参考
针对特定工具或命令系列的技能。
```markdown --- 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 ```
### 语言/框架参考
针对特定语言或框架中模式的技能。
```markdown --- 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 ```
### 工作流/流程指南
针对多步骤流程的技能。
```markdown --- 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 ```
## 反模式
### 过于抽象
```markdown # 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 ``` ```
### 过于狭窄
```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 行，则说明文字太多。请用示例将其拆分。
### 缺少交叉引用
如果你的技能提到了拥有其自身技能的另一个工具或概念，请注明：
```markdown # For Docker networking issues, see the `container-debug` skill. # For regex syntax details, see the `regex-patterns` skill. ```
### 过时的命令
验证每个命令在当前工具版本上有效。常见的陷阱： - Docker Compose：`docker-compose` (v1) vs. `docker compose` (v2) - Python：`pip` vs. `pip3`，`python` vs. `python3` - Node.js：CommonJS (`require`) vs. ESM (`import`)
## 大小指南
| 指标 | 目标 | 过短 | 过长 | |---|---|---|---| | 总行数 | 300-550 | < 150 | > 700 | | 章节数 | 5-10 | < 3 | > 15 | | 代码块数 | 15-40 | < 8 | > 60 | | 提示数 | 5-10 | < 3 | > 15 |
低于 150 行的技能可能缺乏示例。超过 700 行的技能应拆分为两个技能。
## 发布检查清单
发布前，请验证：
1. **Frontmatter 是有效的 YAML** — 通过粘贴到 YAML 验证器进行测试 2. **描述以技能的作用开头** — 不要用“This skill...”或“A skill for...”开头 3. **每个章节至少有一个代码块** — 主要内容中没有纯文本章节 4. **命令确实有效** — 在干净的环境中测试 5. **没有遗留的占位符值** — 搜索 `TODO`、`FIXME`、用作真实 URL 的 `example.com` 6. **Slug 可用** — `npx molthub@latest search "your-slug"` 没有返回完全匹配的结果 7. **`requires.anyBins` 列出了真实的依赖项** — 技能命令实际调用的工具 8. **提示章节存在** — 包含 5 个以上可操作、非显而易见的要点
## 发布
```bash # 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" ```
## 提示
- `description` 字段是你技能的搜索排名。花在上面的时间应比任何单一内容章节都多。包含用户会搜索的具体动词和名词。 - 以最常见的用例开头。如果 80% 的用户需要“如何进行 Base64 编码”，请将其放在“如何在 MessagePack 和 CBOR 之间转换”之前。 - 每个代码示例都应可以直接复制粘贴。如果它需要未显示的设置，请添加该设置。 - 为代理编写，而不是为人类。代理需要能够逐步遵循的明确指令。避免“你可能会考虑”之类的说法，直接说“在 Y 时做 X”。 - 通过让代理在真实任务上使用它来测试你的技能。如果代理无法按照指令产生正确的结果，则该技能需要改进。 - 即使在特定语言的技能中，也优先使用 `bash` 代码块来展示命令。代理通常通过 shell 操作，而 bash 块表示“运行此命令”。 - 不要重复 `--help` 已经提供的内容。重点关注 `--help` 无法教授的模式、组合和非显而易见的内容。 - 对技能进行语义化版本控制：补丁版本用于拼写错误修复，次版本用于新章节，主版本用于结构重组。注册表会跟踪版本历史。