Clawhub Skill Creator

Clawhub Skill Creator

Complete guide for creating skills compatible with clawhub registry and optimized for AI agent usage.

Language Rule

Skill description must be in English, unless context requires otherwise (examples, comments, etc. may use other languages when appropriate). description in frontmatter: English only SKILL.md body: English preferred Examples, code comments: Any language as needed References: Any language as appropriate for domain

Create New Skill

# Run initializer ./scripts/init-skill.sh my-skill # Or manually create structure mkdir -p my-skill/{references,scripts,assets} touch my-skill/SKILL.md my-skill/_meta.json my-skill/LICENSE.txt

Phase 1: Understand Requirements

Before writing any code, clarify: What problem does this skill solve? Concrete use cases (2-3 examples) Target queries that should trigger skill Who will use this skill? AI agents (primary audience for clawhub) Expected context (tools available, environment) What resources are needed? References for detailed docs? Assets for templates? Scripts for automation? Output: Clear understanding of skill scope and triggers.

Phase 2: Plan Structure

Choose pattern based on complexity: ComplexityStructureWhen to UseSimpleSKILL.md only<100 lines, single purposeMedium+ references/100-300 lines, some detailsComplex+ references/ + assets/>300 lines, multi-domain Decide on resources: Which references needed? (docs, examples, patterns) Which assets needed? (templates, configs) Which scripts needed? (validation, packaging) Output: Directory structure and resource list.

Phase 3: Initialize Structure

# Create directory mkdir -p my-skill/{references,scripts,assets} # Create required files touch my-skill/SKILL.md touch my-skill/_meta.json touch my-skill/LICENSE.txt Required files for clawhub: my-skill/ ├── SKILL.md # Instructions and metadata (required) ├── _meta.json # Registry metadata (required) ├── LICENSE.txt # License file (required) ├── references/ # Optional: detailed documentation ├── scripts/ # Optional: automation scripts └── assets/ # Optional: templates, resources

Phase 4: Write SKILL.md

Frontmatter (YAML) --- name: skill-name description: What it does. Use when: (1) trigger-1, (2) trigger-2, (3) trigger-3. --- Critical rules: name must match directory name description is ONLY trigger mechanism — include all "when to use" here description must be in English Only name and description are required in frontmatter Body Structure # Skill Title Brief purpose (1-2 sentences). ## Quick Start **Linux/Mac:** ```bash command --option Windows CMD: command --option PowerShell: command --option

When to Use

Situation 1: What to do Situation 2: What to do Situation 3: What to do

Workflow

Step one: Description Step two: Description Step three: Description

Resources

• references/advanced.md - For complex cases
• references/examples.md - Usage examples
• assets/template.txt - Starting template
• **Writing guidelines:**
• Imperative voice ("Open file", not "You should open file")
• Concrete examples over abstract explanations
• Platform-aware commands
• Navigation to references
• English preferred for body text
• ### Phase 5: Create _meta.json
• ```json
• {
• "name": "skill-name",
• "version": "1.0.0",
• "description": "Short description for registry listing",
• "requires": {
• "env": ["ENV_VAR_1", "ENV_VAR_2"],
• "credentials": ["credential_name"]
• },
• "tags": ["tag1", "tag2", "latest"]
• }
• Fields explained:
• name: Must match directory and SKILL.md frontmatter
• version: Semver (X.Y.Z), check registry before setting
• description: For registry listing, must be in English
• requires.env: Environment variables needed
• requires.credentials: Credentials needed
• tags: Include "latest" for discoverability

Phase 6: Add LICENSE.txt

Choose license (MIT recommended): MIT License Copyright (c) 2025 [Author] Permission is hereby granted...

Phase 7: Write References (if needed)

Create files in references/: # Reference Title Detailed documentation here. ## Section Content... Guidelines: One topic per file <5K words per file Link from SKILL.md with clear context No deeply nested references Language: English preferred, domain-specific allowed

Phase 8: Validate Locally

# Check structure ./scripts/validate.sh my-skill # Or manual checks: # - SKILL.md exists and has frontmatter # - _meta.json is valid JSON # - LICENSE.txt exists # - No README.md, CHANGELOG.md # - Line count < 300 # - References linked correctly Validation checklist: Directory name matches name in frontmatter and _meta.json description in English, includes "Use when:" triggers SKILL.md < 300 lines _meta.json valid JSON No extraneous files (README, CHANGELOG) References exist and linked Token estimate < 10K

Phase 9: Test with Agent

Trigger test: Does skill activate for intended queries? Does description correctly trigger skill? Workflow test: Can agent follow steps without clarification? Are commands clear and executable? Resource test: Are references loaded at appropriate time? Is navigation clear? Edge case test: How does skill handle errors? Are platform differences handled?

Phase 10: Iterate (if needed)

If tests reveal issues: Identify problem Trigger not working? → Fix description Workflow unclear? → Rewrite steps Missing info? → Add reference Update files SKILL.md, _meta.json, or references Re-validate and re-test Go back to Phase 8 Repeat until satisfied Iterate cycle: Phase 8 → Phase 9 → Phase 10 (loop) → Phase 11

Phase 11: Check Version

Before publishing, verify current registry version: # Check current registry version clawhub inspect skill-name --json | grep version # Ensure new version follows semver: # 1.0.0 → 1.0.1 (patch: bug fixes) # 1.0.0 → 1.1.0 (minor: new features) # 1.0.0 → 2.0.0 (major: breaking changes) # Never downgrade! (1.1.0 → 1.0.2 is wrong) Update _meta.json with correct version: { "version": "1.0.1" }

Phase 12: Package

# Create .skill package for distribution ./scripts/package-skill.sh my-skill ./dist # Output: dist/my-skill.skill # Validates structure before packaging Package contains: All skill files Validated structure Ready for distribution

Phase 13: Publish

cd my-skill # Publish to clawhub clawhub publish . --version 1.0.1 --changelog "Description of changes" # Verify publication clawhub inspect skill-name After publish: Skill available in registry Others can install via clawhub install skill-name

SKILL.md

Instructions and metadata: YAML frontmatter (name, description in English) Markdown body (workflow, examples) Navigation to references

_meta.json

Registry metadata: { "name": "skill-name", "version": "1.0.0", "description": "Registry listing description in English", "requires": { "env": [], "credentials": [] }, "tags": ["latest"] }

LICENSE.txt

License file (MIT, Apache-2.0, etc.)

Resources

references/skill-structure.md - Directory structure patterns references/agent-first-design.md - Designing for AI vs humans references/token-optimization.md - Minimizing context usage references/cross-platform.md - Platform-aware scripts references/validation-checklist.md - Pre-publish checks references/versioning.md - Semver best practices

1. Agent-First Design

Skills used by AI agents, not humans: ❌ No interactive prompts ❌ No platform-specific scripts (use knowledge instead) ✅ Command templates for all platforms ✅ Clear navigation to references

2. Progressive Disclosure

Level 1: Metadata (name + description) → Always loaded Level 2: SKILL.md body → On trigger Level 3: Resources (references/, assets/) → On demand

3. Token Budget

ComponentTargetMaxMetadata50 words100 wordsSKILL.md200 lines300 linesReferences3K words5K wordsTotal5K tokens10K tokens

4. Cross-Platform Awareness

• Instead of script:
• ## Commands
• **Linux/Mac:**
• ```bash
• command --option
• Windows CMD:
• command --option
• PowerShell:
• command --option
• **Agent chooses** appropriate variant based on detected platform.
• ### 5. English Language for Descriptions
• **Required in English:**
• `description` in SKILL.md frontmatter
• `description` in _meta.json
• Main workflow instructions
• **May use other languages:**
• Code examples
• Comments
• Domain-specific references
• User-facing examples
• ## Scripts
• `scripts/init-skill.sh` - Initialize new skill structure
• `scripts/package-skill.sh` - Package skill for distribution
• `scripts/validate.sh` - Validate skill structure
• ## Anti-Patterns
• ❌ **Don't:**
• Put "When to use" only in body (must be in description)
• Use non-English description in frontmatter
• Duplicate info between SKILL.md and references
• Create README.md, CHANGELOG.md (clutter)
• Use platform-specific scripts (sh/bat)
• Write passive voice ("You should")
• Include generic background theory
• Skip validation before publish
• Forget to bump version
• Publish without testing
• ✅ **Do:**
• Write description in English
• Start with concrete examples
• Move details to references/
• Use imperative voice ("Do X")
• Challenge every sentence's value
• Test with real agent queries
• Validate before publish
• Follow semver strictly
• Iterate based on test results