Publish Your First Skill to ClawHub: A Step-by-Step Guide

Every skill in the ClawHub marketplace started as someone solving a problem for themselves. The commit message formatter, the browser automation agent, the code review skill — they all began as private tools that someone decided to share.

If you've built a prompt, workflow, or Claude Code command that saves you time, publishing it takes about 20 minutes. This guide covers everything: the SKILL.md format, required metadata, validation, and the CLI commands to push it live.

What You're Publishing

A ClawHub skill is a directory containing:

my-skill/
├── SKILL.md          # Main skill definition (required)
├── README.md         # Human-readable documentation (required)
├── examples/         # Usage examples (recommended)
│   ├── basic.md
│   └── advanced.md
└── tests/            # Validation tests (recommended)
    └── test.md

The SKILL.md file is the heart of your skill. Everything else supports it.

The SKILL.md Format

SKILL.md is a structured markdown file with two parts: YAML frontmatter for metadata, and markdown for the skill's instructions.

Complete SKILL.md Template

---
name: "my-skill-name"
version: "1.0.0"
title: "Human-Readable Skill Title"
description: "One or two sentences. What does this skill do? What problem does it solve?"
author: "your-github-username"
type: "command"
category: "development"
tags:
  - "tag-one"
  - "tag-two"
  - "tag-three"
invocation: "/my-command"
difficulty: "beginner"
claude_version: ">=1.2.0"
permissions:
  read:
    - "project files"
    - "git history"
  write:
    - "project files"
  network: "none"
examples:
  - input: "/my-command fix the auth bug"
    output: "Analyzes auth code, identifies issue, proposes fix"
  - input: "/my-command refactor for performance"
    output: "Reviews hot paths, rewrites with optimizations"
---

# My Skill Title

[The skill instructions go here. This is what gets injected into Claude's context when the skill activates.]

## When to Use This Skill

[Describe the scenarios where this skill is most effective]

## Instructions

[The actual prompt/instructions for the skill]

## Output Format

[Describe what the skill produces]

Metadata Field Reference

Required fields:

Recommended fields:

Skill Types

• command — A single slash command with a specific purpose (/commit, /review, /document)
• plugin — A multi-command bundle that adds a capability domain (git-workflow, testing-suite)
• agent — An autonomous workflow that takes high-level goals and executes multi-step tasks

Categories

development   — Code writing, refactoring, debugging
testing       — Test generation, coverage, QA
devops        — CI/CD, deployment, infrastructure
productivity  — Workflow, documentation, communication
research      — Web search, data gathering, analysis
agents        — Autonomous workflows and AI orchestration

Writing Effective Skill Instructions

The instructions section of your SKILL.md is what actually runs inside Claude. Write it like a senior developer briefing a colleague:

Be specific about the task:

## Instructions

When activated, analyze the staged git diff and generate a commit message that:
1. Follows the Conventional Commits specification (feat/fix/chore/docs/refactor/test/perf)
2. Uses the imperative mood ("add" not "adds" or "added")
3. Keeps the subject line under 72 characters
4. Adds a body if the change is non-trivial, explaining WHY not WHAT

Define the output format:

## Output Format

Output the commit message directly with no preamble. If you're unsure of the type, ask one clarifying question before generating the message.

Example output:
feat(auth): add OAuth2 flow with Google provider

Replaces the custom JWT implementation with Google OAuth2.
Removes 340 lines of auth boilerplate and improves security
posture by delegating token management to Google.

Include edge case handling:

## Edge Cases

- If the diff is empty: remind the user to stage changes first
- If the diff includes generated files (package-lock.json, .min.js): ignore those files in the analysis
- If the change spans multiple concerns: suggest splitting into multiple commits

Setting Up Your Publisher Account

Before you can publish, set up a publisher profile:

clawhub auth login
clawhub publisher init

The publisher init command prompts for:

• Display name
• Bio (shown on your publisher page)
• GitHub profile (for verification)
• Website URL (optional)

Request verification to get the verified publisher badge (required for featuring):

clawhub publisher verify

Verification checks that your GitHub account is real and active. The review takes 1-2 business days.

Validate Before Publishing

Run the validator before pushing to catch common issues:

clawhub validate ./my-skill

The validator checks:

Validating my-skill...

  ✓ SKILL.md found
  ✓ Required metadata present
  ✓ name: "my-skill-name" — valid format
  ✓ version: "1.0.0" — valid semver
  ✓ type: "command" — valid
  ✓ category: "development" — valid
  ✓ invocation: "/my-command" — valid
  ✓ README.md found
  ✓ Examples provided (2)
  ✗ No tests found — strongly recommended
  ⚠ description is 47 characters — consider expanding to 100+

Validation score: 88/100

Fix any errors before publishing. Warnings won't block publishing but will affect your skill's quality score in search results.

Writing Tests

Tests live in tests/test.md and define expected behavior as example conversations:

# Tests for my-skill

## Test 1: Basic usage
Input: /my-command analyze the login function
Expected behavior:
  - Identifies the specific function in scope
  - Returns analysis within 30 seconds
  - Output includes at least one concrete recommendation

## Test 2: Empty input handling
Input: /my-command
Expected behavior:
  - Asks for clarification rather than guessing
  - Suggests example inputs

## Test 3: Edge case
Input: /my-command (run on a project with no code files)
Expected behavior:
  - Gracefully handles empty project
  - Returns helpful error message

Run tests before publishing:

clawhub test ./my-skill

Publish

Once validation passes:

clawhub publish ./my-skill

Output:

Publishing my-skill v1.0.0...

  ✓ Validating manifest
  ✓ Signing package
  ✓ Uploading to registry
  ✓ Updating search index
  ✓ Building marketplace listing

Published! Your skill is live at:
https://aiskill.market/skills/my-skill-name

Share it:
  clawhub install my-skill-name

Your skill is immediately available to all ClawHub users.

Publishing Updates

When you improve the skill, bump the version and republish:

1. Update version in SKILL.md (follow semver: patch for fixes, minor for new features, major for breaking changes)
2. Run validation again
3. Publish

# After editing SKILL.md version to "1.1.0"
clawhub validate ./my-skill
clawhub publish ./my-skill

Existing users with auto-update enabled will get the new version automatically. Users with manual updates will see it in clawhub outdated.

What Makes a Skill Get Featured

The ClawHub team features skills that meet these criteria:

• Quality score 4.5+ — High ratings from real users
• Install count 100+ — Proven demand
• Verified publisher — Confirmed identity
• Complete documentation — README, examples, tests
• Specific, focused purpose — Does one thing well
• Active maintenance — Updated within last 90 days

Focus on solving a real problem clearly. The install count follows from usefulness.

Next Steps

• Browse existing skills for inspiration
• Read the ClawHub CLI reference for full command details
• Join the community forum to get feedback on your skill before publishing