skill-writer

# Skill Writer

Write well-structured, effective SKILL.md files for the ClawdHub registry. Covers the skill format specification, frontmatter schema, content patterns, example quality, and common anti-patterns.

## When to Use

- Creating a new skill from scratch
- Structuring technical content as an agent skill
- Writing frontmatter that the registry indexes correctly
- Choosing section organization for different skill types
- Reviewing your own skill before publishing

## The SKILL.md Format

A skill is a single Markdown file with YAML frontmatter. The agent loads it on demand and follows its instructions.

```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 Schema

### `name` (required)

The skill's slug identifier. Must match what you publish with.

```yaml
name: my-skill
```

Rules:
- Lowercase, hyphenated: `csv-pipeline`, `git-workflows`
- No spaces, no underscores
- Keep it short and descriptive (1-3 words)
- Check for slug collisions before publishing: `npx molthub@latest search "your-slug"`

### `description` (required)

The single most important field. This is what:
1. The registry indexes for semantic search (vector embeddings)
2. The agent reads to decide whether to activate the skill
3. Users see when browsing search results

```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...
```

Pattern for effective descriptions:
```
[What it does]. Use when [trigger 1], [trigger 2], [trigger 3]. Also covers [related topic].
```

### `metadata` (required)

JSON object with the `clawdbot` schema:

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

Fields:
- **`emoji`**: Single emoji displayed in registry listings
- **`requires.anyBins`**: Array of CLI tools the skill needs (at least one must be available)
- **`os`**: Array of supported platforms: `"linux"`, `"darwin"` (macOS), `"win32"` (Windows)

Choose `requires.anyBins` carefully:
```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"]}
```

## Content Structure

### The "When to Use" Section

Always include this immediately after the title paragraph. It tells the agent (and the user) the specific scenarios where this skill applies.

```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
```

Rules:
- 4-8 bullet points
- Each bullet is a concrete scenario, not an abstract concept
- Start with a verb or gerund: "Automating...", "Debugging...", "Converting..."
- Don't repeat the description field verbatim

### Main Content Sections

Organize by task, not by concept. The agent needs to find the right command for a specific situation.

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

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

### Code Blocks

Every section should have at least one code block. Skills without code blocks are opinions, not tools.

````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...
````

Code block best practices:
- **Always specify the language** (`bash`, `python`, `javascript`, `yaml`, `sql`, etc.)
- **Show the output** in a comment below the command
- **Use realistic values**, not `foo`/`bar` (use `myapp`, `api-server`, real IP formats)
- **Include the most common case first**, then variations
- **Add inline comments** for non-obvious flags or arguments

### Multi-Language Coverage

If a skill applies across languages, use consistent section structure:

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

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.
```

Rules:
- 5-10 bullets
- Each tip is a standalone insight (no dependencies on other tips)
- Prioritize gotchas and non-obvious behavior over basic advice
- No "always use best practices" platitudes

## Skill Types and Templates

### CLI Tool Reference

For skills about a specific tool or command family.

```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
```

### Language/Framework Reference

For skills about patterns in a specific language or framework.

```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
```

### Workflow/Process Guide

For skills about multi-step processes.

```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
```

## Anti-Patterns

### Too abstract

```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
```
```

### 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.
---
```

### Wall of text without examples

If any section goes more than 10 lines without a code block, it's too text-heavy. Break it up with examples.

### Missing cross-references

If your skill mentions another tool or concept that has its own skill, note it:

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

### Outdated commands

Verify every command works on current tool versions. Common traps:
- Docker Compose: `docker-compose` (v1) vs. `docker compose` (v2)
- Python: `pip` vs. `pip3`, `python` vs. `python3`
- Node.js: CommonJS (`require`) vs. ESM (`import`)

## Size Guidelines

| Metric | Target | Too Short | Too Long |
|---|---|---|---|
| Total lines | 300-550 | < 150 | > 700 |
| Sections | 5-10 | < 3 | > 15 |
| Code blocks | 15-40 | < 8 | > 60 |
| Tips | 5-10 | < 3 | > 15 |

A skill under 150 lines probably lacks examples. A skill over 700 lines should be split into two skills.

## Publishing Checklist

Before publishing, verify:

1. **Frontmatter is valid YAML** — test by pasting into a YAML validator
2. **Description starts with what the skill does** — not "This skill..." or "A skill for..."
3. **Every section has at least one code block** — no text-only sections in the main content
4. **Commands actually work** — test in a clean environment
5. **No placeholder values left** — search for `TODO`, `FIXME`, `example.com` used as real URLs
6. **Slug is available** — `npx molthub@latest search "your-slug"` returns no exact match
7. **`requires.anyBins` lists real dependencies** — tools the skill's commands actually invoke
8. **Tips section exists** — with 5+ actionable, non-obvious bullets

## Publishing

```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"
```

## Tips

- The `description` field is your skill's search ranking. Spend more time on it than any single content section. Include the specific verbs and nouns users would search for.
- Lead with the most common use case. If 80% of users need "how to encode Base64", put that before "how to convert between MessagePack and CBOR."
- Every code example should be copy-pasteable. If it needs setup that isn't shown, add the setup.
- Write for the agent, not the human. The agent needs unambiguous instructions it can follow step by step. Avoid "you might want to consider" — say "do X when Y."
- Test your skill by asking an agent to use it on a real task. If the agent can't follow the instructions to produce a correct result, the skill needs work.
- Prefer `bash` code blocks for commands, even in language-specific skills. The agent often operates via shell, and bash blocks signal "run this."
- Don't duplicate what `--help` already provides. Focus on patterns, combinations, and the non-obvious things that `--help` doesn't teach.
- Version your skills semantically: patch for typo fixes, minor for new sections, major for restructures. The registry tracks version history.