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

Quick Start

Create New Skill

CODEBLOCK0

Skill Creation Workflow

Phase 1: Understand Requirements

Before writing any code, clarify:

1. 1. What problem does this skill solve?

1. 2. Who will use this skill?

1. 3. What resources are needed?

Output: Clear understanding of skill scope and triggers.

Phase 2: Plan Structure

Choose pattern based on complexity:

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

CODEBLOCK1

Required files for clawhub:
CODEBLOCK2

Phase 4: Write SKILL.md

Frontmatter (YAML)

CODEBLOCK3

Critical rules:

• - name must match directory name
• INLINECODE2 is ONLY trigger mechanism — include all "when to use" here
• INLINECODE3 must be in English
• Only name and description are required in frontmatter

Body Structure

CODEBLOCK4bash
command --option

**Windows CMD:**

**PowerShell:**

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

CODEBLOCK8

Fields explained:

• - name: Must match directory and SKILL.md frontmatter
• INLINECODE7: Semver (X.Y.Z), check registry before setting
• INLINECODE8: For registry listing, must be in English
• INLINECODE9: Environment variables needed
• INLINECODE10: Credentials needed
• INLINECODE11: Include "latest" for discoverability

Phase 6: Add LICENSE.txt

Choose license (MIT recommended):

CODEBLOCK9

Phase 7: Write References (if needed)

Create files in references/:

CODEBLOCK10

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

CODEBLOCK11

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:

1. 1. Identify problem

1. 2. Update files

1. 3. Re-validate and re-test

1. 4. Repeat until satisfied

Iterate cycle: Phase 8 → Phase 9 → Phase 10 (loop) → Phase 11

Phase 11: Check Version

Before publishing, verify current registry version:

CODEBLOCK12

Update _meta.json with correct version:

CODEBLOCK13

Phase 12: Package

CODEBLOCK14

Package contains:

• - All skill files
• Validated structure
• Ready for distribution

Phase 13: Publish

CODEBLOCK15

After publish:

• - Skill available in registry
• Others can install via INLINECODE15

Required Files for Clawhub

SKILL.md

Instructions and metadata:

• - YAML frontmatter (name, description in English)
• Markdown body (workflow, examples)
• Navigation to references

_meta.json

Registry metadata:
CODEBLOCK16

LICENSE.txt

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

Resources

• - references/skill-structure.md - Directory structure patterns
• INLINECODE17 - Designing for AI vs humans
• INLINECODE18 - Minimizing context usage
• INLINECODE19 - Platform-aware scripts
• INLINECODE20 - Pre-publish checks
• INLINECODE21 - Semver best practices

Key Principles

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

CODEBLOCK17

3. Token Budget

4. Cross-Platform Awareness

Instead of script:

## Commands

**Linux/Mac:**

**Windows CMD:**

**PowerShell:**

Agent chooses appropriate variant based on detected platform.

5. English Language for Descriptions

Required in English:

• - description in SKILL.md frontmatter
• INLINECODE23 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
• INLINECODE25 - Package skill for distribution
• INLINECODE26 - 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