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.

CODEBLOCK0

Frontmatter Schema

name (required)

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

CODEBLOCK1

Rules:

• - Lowercase, hyphenated: csv-pipeline, INLINECODE2
• No spaces, no underscores
• Keep it short and descriptive (1-3 words)
• Check for slug collisions before publishing: INLINECODE3

description (required)

The single most important field. This is what:

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

CODEBLOCK2

Pattern for effective descriptions:
CODEBLOCK3

metadata (required)

JSON object with the clawdbot schema:

CODEBLOCK4

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:
CODEBLOCK5

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.

CODEBLOCK6

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.

CODEBLOCK7

Code Blocks

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

INLINECODE14

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:

CODEBLOCK10bash
echo -n "Hello" | sha256sum

### JavaScript

### Python

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.

CODEBLOCK14

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.

CODEBLOCK15

Language/Framework Reference

For skills about patterns in a specific language or framework.

CODEBLOCK16

Workflow/Process Guide

For skills about multi-step processes.

CODEBLOCK17

Anti-Patterns

Too abstract

CODEBLOCK18bash

Bash: exit on any error

Trap for cleanup on exit

Too narrow

CODEBLOCK20

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:

CODEBLOCK21

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. INLINECODE29
• Node.js: CommonJS (require) vs. ESM (import)

Size Guidelines

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

CODEBLOCK22

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.