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

The SKILL.md Format

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

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

name: my-skill

Rules:

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

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

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

Fields:

Choose requires.anyBins carefully:

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

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

Main Content Sections

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

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

## GOOD: Concrete, runnable example

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

Code block best practices:

Multi-Language Coverage

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

## Hashing
Bash

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.

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

Skill Types and Templates

CLI Tool Reference

For skills about a specific tool or command family.

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

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

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

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

Bash: exit on any error

Trap for cleanup on exit

Too narrow

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

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

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

# 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

[What needs to be set up first]