ClawHub Best Practices

+15 Mana ✨
ClawHub Publishing Best Practices(DOCUMENTATION)Semantic Versioning Specification(DOCUMENTATION)

Introduction

Whether you are consuming skills from ClawHub or publishing your own, following established best practices ensures a smooth experience. This lesson covers naming conventions, documentation standards, versioning strategies, and how to handle skill deprecation gracefully.

Key Concepts

  • Naming Conventions: Rules for choosing clear, discoverable skill names
  • Documentation Standards: What a well-documented skill includes beyond the basic SKILL.md
  • Versioning Strategy: When to bump major, minor, and patch versions
  • Deprecation Handling: How to retire a skill gracefully without breaking existing users
  • Community Engagement: Responding to feedback and maintaining published skills

Real World Context

A developer publishes a popular skill called deploy. It gains 5,000 installations. Later, they realize the name is too generic and conflicts with other deployment skills. They also need to make a breaking change to the instruction format. Without a versioning strategy and deprecation plan, this update would break thousands of installations silently. Following best practices, they handle the transition smoothly.

Deep Dive

Naming Conventions

Choose skill names that are specific, descriptive, and unlikely to collide with other skills:

markdown
Naming Guidelines:
- Use lowercase with hyphens: git-commit, code-review, docker-deploy
- Be specific: "k8s-helm-deploy" not just "deploy"
- Include the tool or domain: "eslint-fixer" not just "fixer"
- Avoid generic single words: "helper", "utils", "tool"
- Check for conflicts: run `clawhub search <name>` before publishing

A good name tells users what the skill does at a glance. "prisma-migration-review" is immediately clear. "reviewer" is not.

Documentation Standards

A well-documented skill's SKILL.md should include these sections:

markdown
---
name: prisma-migration-review
description: Reviews Prisma migration files for common issues
user-invocable: true
requires:
  bins: ["npx"]
---

# Prisma Migration Review

## What This Skill Does
Reviews Prisma migration SQL files for common issues including
missing indexes, destructive operations, and data loss risks.

## Usage
Invoke with `/prisma-migration-review` when you have pending
migrations to review.

## Output
Produces a categorized report with:
- Critical issues (must fix before applying)
- Warnings (should investigate)
- Suggestions (optional improvements)

## Instructions
(step-by-step agent instructions here)

This structure gives users everything they need: what it does, how to use it, and what to expect. The instructions section at the bottom is what the agent actually follows.

Versioning Strategy

Follow semantic versioning with clear rules for when to bump each component:

markdown
Version Bumping Rules:
- Major (2.0.0): Breaking changes to skill behavior or output format
  Example: Changing from markdown to JSON output format

- Minor (1.1.0): New features that do not break existing behavior
  Example: Adding a new analysis category to a review skill

- Patch (1.0.1): Bug fixes and minor improvements
  Example: Fixing a typo in instructions or improving wording

Users who pin versions rely on these conventions to understand the impact of updates.

Deprecation Handling

When retiring a skill, follow a graceful deprecation process:

bash
# Step 1: Add deprecation notice to SKILL.md
# Add to frontmatter: deprecated: true
# Add to body: "This skill is deprecated. Use prisma-review-v2 instead."

# Step 2: Publish the deprecation notice
clawhub publish

# Step 3: Keep the skill available for at least 90 days
# Users relying on pinned versions continue to work

# Step 4: After 90 days, optionally unlist
clawhub unlist prisma-migration-review

The deprecated: true frontmatter flag causes ClawHub to show a deprecation warning during installation. The skill remains functional but users are encouraged to switch to the replacement. Unlisting removes it from search results but does not delete it — pinned installations continue to work.

Common Pitfalls

  • Choosing names that are too generic: Generic names like "helper" or "tool" collide frequently and do not help users understand what the skill does.
  • Making breaking changes in minor versions: Users expect minor version bumps to be backwards-compatible. Breaking this convention erodes trust.
  • Abandoning published skills: Skills with no updates and unaddressed issues lose community trust. If you cannot maintain a skill, mark it as deprecated and suggest alternatives.

Best Practices

  • Search before naming: Always check clawhub search <name> for conflicts before publishing.
  • Include usage examples: Show users exactly how to invoke the skill and what output to expect.
  • Maintain a changelog: Document what changed in each version so users can make informed update decisions.

Summary

  • Use specific, hyphenated, lowercase names that describe what the skill does
  • Document skills with clear sections: what it does, usage, output, and instructions
  • Follow semantic versioning: major for breaking changes, minor for features, patch for fixes
  • Deprecate gracefully: add the deprecated flag, publish the notice, and maintain availability for at least 90 days
  • Engage with the community by responding to feedback and keeping skills maintained
✓ Completed