{"skill":{"slug":"clawhub-skill-creator","displayName":"Clawhub Skill Creator","summary":"Create and update skills for clawhub registry; optimize structure, validate metadata, and ensure compatibility for AI agent usage.","description":"---\nname: clawhub-skill-creator\ndescription: Create effective skills for clawhub registry. Use when: (1) Creating new skill for publication, (2) Updating existing skill metadata, (3) Optimizing skill structure for AI agents, (4) Validating skill before publish, (5) Understanding clawhub-specific requirements.\n---\n\n# Clawhub Skill Creator\n\nComplete guide for creating skills compatible with clawhub registry and optimized for AI agent usage.\n\n## Language Rule\n\n**Skill description must be in English**, unless context requires otherwise (examples, comments, etc. may use other languages when appropriate).\n\n- `description` in frontmatter: English only\n- SKILL.md body: English preferred\n- Examples, code comments: Any language as needed\n- References: Any language as appropriate for domain\n\n## Quick Start\n\n### Create New Skill\n\n```bash\n# Run initializer\n./scripts/init-skill.sh my-skill\n\n# Or manually create structure\nmkdir -p my-skill/{references,scripts,assets}\ntouch my-skill/SKILL.md my-skill/_meta.json my-skill/LICENSE.txt\n```\n\n## Skill Creation Workflow\n\n### Phase 1: Understand Requirements\n\n**Before writing any code, clarify:**\n\n1. **What problem does this skill solve?**\n   - Concrete use cases (2-3 examples)\n   - Target queries that should trigger skill\n\n2. **Who will use this skill?**\n   - AI agents (primary audience for clawhub)\n   - Expected context (tools available, environment)\n\n3. **What resources are needed?**\n   - References for detailed docs?\n   - Assets for templates?\n   - Scripts for automation?\n\n**Output:** Clear understanding of skill scope and triggers.\n\n### Phase 2: Plan Structure\n\n**Choose pattern based on complexity:**\n\n| Complexity | Structure | When to Use |\n|------------|-----------|-------------|\n| Simple | SKILL.md only | <100 lines, single purpose |\n| Medium | + references/ | 100-300 lines, some details |\n| Complex | + references/ + assets/ | >300 lines, multi-domain |\n\n**Decide on resources:**\n- Which references needed? (docs, examples, patterns)\n- Which assets needed? (templates, configs)\n- Which scripts needed? (validation, packaging)\n\n**Output:** Directory structure and resource list.\n\n### Phase 3: Initialize Structure\n\n```bash\n# Create directory\nmkdir -p my-skill/{references,scripts,assets}\n\n# Create required files\ntouch my-skill/SKILL.md\ntouch my-skill/_meta.json\ntouch my-skill/LICENSE.txt\n```\n\n**Required files for clawhub:**\n```\nmy-skill/\n├── SKILL.md              # Instructions and metadata (required)\n├── _meta.json            # Registry metadata (required)\n├── LICENSE.txt           # License file (required)\n├── references/           # Optional: detailed documentation\n├── scripts/              # Optional: automation scripts\n└── assets/               # Optional: templates, resources\n```\n\n### Phase 4: Write SKILL.md\n\n#### Frontmatter (YAML)\n\n```yaml\n---\nname: skill-name\ndescription: What it does. Use when: (1) trigger-1, (2) trigger-2, (3) trigger-3.\n---\n```\n\n**Critical rules:**\n- `name` must match directory name\n- `description` is ONLY trigger mechanism — include all \"when to use\" here\n- `description` must be in **English**\n- Only `name` and `description` are required in frontmatter\n\n#### Body Structure\n\n```markdown\n# Skill Title\n\nBrief purpose (1-2 sentences).\n\n## Quick Start\n\n**Linux/Mac:**\n```bash\ncommand --option\n```\n\n**Windows CMD:**\n```cmd\ncommand --option\n```\n\n**PowerShell:**\n```powershell\ncommand --option\n```\n\n## When to Use\n\n- Situation 1: What to do\n- Situation 2: What to do\n- Situation 3: What to do\n\n## Workflow\n\n1. **Step one**: Description\n2. **Step two**: Description\n3. **Step three**: Description\n\n## Resources\n\n- `references/advanced.md` - For complex cases\n- `references/examples.md` - Usage examples\n- `assets/template.txt` - Starting template\n```\n\n**Writing guidelines:**\n- Imperative voice (\"Open file\", not \"You should open file\")\n- Concrete examples over abstract explanations\n- Platform-aware commands\n- Navigation to references\n- English preferred for body text\n\n### Phase 5: Create _meta.json\n\n```json\n{\n  \"name\": \"skill-name\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Short description for registry listing\",\n  \"requires\": {\n    \"env\": [\"ENV_VAR_1\", \"ENV_VAR_2\"],\n    \"credentials\": [\"credential_name\"]\n  },\n  \"tags\": [\"tag1\", \"tag2\", \"latest\"]\n}\n```\n\n**Fields explained:**\n- `name`: Must match directory and SKILL.md frontmatter\n- `version`: Semver (X.Y.Z), check registry before setting\n- `description`: For registry listing, must be in **English**\n- `requires.env`: Environment variables needed\n- `requires.credentials`: Credentials needed\n- `tags`: Include \"latest\" for discoverability\n\n### Phase 6: Add LICENSE.txt\n\nChoose license (MIT recommended):\n\n```\nMIT License\n\nCopyright (c) 2025 [Author]\n\nPermission is hereby granted...\n```\n\n### Phase 7: Write References (if needed)\n\nCreate files in `references/`:\n\n```markdown\n# Reference Title\n\nDetailed documentation here.\n\n## Section\n\nContent...\n```\n\n**Guidelines:**\n- One topic per file\n- <5K words per file\n- Link from SKILL.md with clear context\n- No deeply nested references\n- Language: English preferred, domain-specific allowed\n\n### Phase 8: Validate Locally\n\n```bash\n# Check structure\n./scripts/validate.sh my-skill\n\n# Or manual checks:\n# - SKILL.md exists and has frontmatter\n# - _meta.json is valid JSON\n# - LICENSE.txt exists\n# - No README.md, CHANGELOG.md\n# - Line count < 300\n# - References linked correctly\n```\n\n**Validation checklist:**\n- [ ] Directory name matches `name` in frontmatter and _meta.json\n- [ ] `description` in English, includes \"Use when:\" triggers\n- [ ] SKILL.md < 300 lines\n- [ ] _meta.json valid JSON\n- [ ] No extraneous files (README, CHANGELOG)\n- [ ] References exist and linked\n- [ ] Token estimate < 10K\n\n### Phase 9: Test with Agent\n\n**Trigger test:**\n- Does skill activate for intended queries?\n- Does description correctly trigger skill?\n\n**Workflow test:**\n- Can agent follow steps without clarification?\n- Are commands clear and executable?\n\n**Resource test:**\n- Are references loaded at appropriate time?\n- Is navigation clear?\n\n**Edge case test:**\n- How does skill handle errors?\n- Are platform differences handled?\n\n### Phase 10: Iterate (if needed)\n\nIf tests reveal issues:\n\n1. **Identify problem**\n   - Trigger not working? → Fix description\n   - Workflow unclear? → Rewrite steps\n   - Missing info? → Add reference\n\n2. **Update files**\n   - SKILL.md, _meta.json, or references\n\n3. **Re-validate and re-test**\n   - Go back to Phase 8\n\n4. **Repeat until satisfied**\n\n**Iterate cycle:** Phase 8 → Phase 9 → Phase 10 (loop) → Phase 11\n\n### Phase 11: Check Version\n\n**Before publishing, verify current registry version:**\n\n```bash\n# Check current registry version\nclawhub inspect skill-name --json | grep version\n\n# Ensure new version follows semver:\n# 1.0.0 → 1.0.1 (patch: bug fixes)\n# 1.0.0 → 1.1.0 (minor: new features)\n# 1.0.0 → 2.0.0 (major: breaking changes)\n\n# Never downgrade! (1.1.0 → 1.0.2 is wrong)\n```\n\n**Update _meta.json with correct version:**\n\n```json\n{\n  \"version\": \"1.0.1\"\n}\n```\n\n### Phase 12: Package\n\n```bash\n# Create .skill package for distribution\n./scripts/package-skill.sh my-skill ./dist\n\n# Output: dist/my-skill.skill\n# Validates structure before packaging\n```\n\n**Package contains:**\n- All skill files\n- Validated structure\n- Ready for distribution\n\n### Phase 13: Publish\n\n```bash\ncd my-skill\n\n# Publish to clawhub\nclawhub publish . --version 1.0.1 --changelog \"Description of changes\"\n\n# Verify publication\nclawhub inspect skill-name\n```\n\n**After publish:**\n- Skill available in registry\n- Others can install via `clawhub install skill-name`\n\n## Required Files for Clawhub\n\n### SKILL.md\n\nInstructions and metadata:\n- YAML frontmatter (name, description in English)\n- Markdown body (workflow, examples)\n- Navigation to references\n\n### _meta.json\n\nRegistry metadata:\n```json\n{\n  \"name\": \"skill-name\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Registry listing description in English\",\n  \"requires\": {\n    \"env\": [],\n    \"credentials\": []\n  },\n  \"tags\": [\"latest\"]\n}\n```\n\n### LICENSE.txt\n\nLicense file (MIT, Apache-2.0, etc.)\n\n## Resources\n\n- `references/skill-structure.md` - Directory structure patterns\n- `references/agent-first-design.md` - Designing for AI vs humans\n- `references/token-optimization.md` - Minimizing context usage\n- `references/cross-platform.md` - Platform-aware scripts\n- `references/validation-checklist.md` - Pre-publish checks\n- `references/versioning.md` - Semver best practices\n\n## Key Principles\n\n### 1. Agent-First Design\n\nSkills used by AI agents, not humans:\n- ❌ No interactive prompts\n- ❌ No platform-specific scripts (use knowledge instead)\n- ✅ Command templates for all platforms\n- ✅ Clear navigation to references\n\n### 2. Progressive Disclosure\n\n```\nLevel 1: Metadata (name + description)     → Always loaded\nLevel 2: SKILL.md body                      → On trigger\nLevel 3: Resources (references/, assets/)   → On demand\n```\n\n### 3. Token Budget\n\n| Component | Target | Max |\n|-----------|--------|-----|\n| Metadata | 50 words | 100 words |\n| SKILL.md | 200 lines | 300 lines |\n| References | 3K words | 5K words |\n| Total | 5K tokens | 10K tokens |\n\n### 4. Cross-Platform Awareness\n\n**Instead of script:**\n```markdown\n## Commands\n\n**Linux/Mac:**\n```bash\ncommand --option\n```\n\n**Windows CMD:**\n```cmd\ncommand --option\n```\n\n**PowerShell:**\n```powershell\ncommand --option\n```\n```\n\n**Agent chooses** appropriate variant based on detected platform.\n\n### 5. English Language for Descriptions\n\n**Required in English:**\n- `description` in SKILL.md frontmatter\n- `description` in _meta.json\n- Main workflow instructions\n\n**May use other languages:**\n- Code examples\n- Comments\n- Domain-specific references\n- User-facing examples\n\n## Scripts\n\n- `scripts/init-skill.sh` - Initialize new skill structure\n- `scripts/package-skill.sh` - Package skill for distribution\n- `scripts/validate.sh` - Validate skill structure\n\n## Anti-Patterns\n\n❌ **Don't:**\n- Put \"When to use\" only in body (must be in description)\n- Use non-English description in frontmatter\n- Duplicate info between SKILL.md and references\n- Create README.md, CHANGELOG.md (clutter)\n- Use platform-specific scripts (sh/bat)\n- Write passive voice (\"You should\")\n- Include generic background theory\n- Skip validation before publish\n- Forget to bump version\n- Publish without testing\n\n✅ **Do:**\n- Write description in English\n- Start with concrete examples\n- Move details to references/\n- Use imperative voice (\"Do X\")\n- Challenge every sentence's value\n- Test with real agent queries\n- Validate before publish\n- Follow semver strictly\n- Iterate based on test results","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":950,"installsAllTime":36,"installsCurrent":5,"stars":2,"versions":1},"createdAt":1771779323761,"updatedAt":1778491608600},"latestVersion":{"version":"1.0.0","createdAt":1771779323761,"changelog":"Complete guide for creating clawhub-compatible skills with 13-phase workflow","license":null},"metadata":null,"owner":{"handle":"erview","userId":"s175h0jdx5g1z9bpzgdxrfjban83t7pq","displayName":"erview","image":"https://avatars.githubusercontent.com/u/1901695?v=4"},"moderation":null}