Building a skill is building a product. A well-written SKILL.md gets installs, reviews, and ClawHub verification. A poorly-written one gets ignored — or worse, flagged for security issues. This guide walks through the official structure, shows real examples, and documents the 12 mistakes that sink most first-time skill builders.
Every SKILL.md needs three things to be installable: a name, a description, and instructions. Here's the smallest valid skill: ``` --- name: hello-world description: A simple greeting skill version: 1.0.0 author: your-name --- # Hello World You are a friendly assistant. When the user says hello, respond with a warm, personalized greeting. ``` That's it. This skill loads, runs, and can be published to ClawHub. Of course, production skills need much more — tools, permissions, configuration, and thorough testing. But understanding the minimum helps you see the structure clearly.
Here's the recommended template for a production skill: Frontmatter (YAML): - `name` — Kebab-case, unique identifier - `description` — One sentence, under 120 characters - `version` — Semantic versioning (major.minor.patch) - `author` — Your ClawHub username - `category` — One of the 10 standard categories - `tags` — Up to 5 keywords for discoverability - `permissions.fileAccess` — `read`, `write`, or `none` + allowed paths - `permissions.networkAccess` — Allowed domains list - `permissions.systemCommands` — Allowed commands or `none` - `permissions.apiKeys` — Required API keys - `dependencies` — Other skills this skill requires System Prompt (Markdown body): - Role definition — Who/what the agent becomes - Capabilities — What the agent can do with this skill - Constraints — What the agent should NOT do - Output format — How to structure responses - Error handling — What to do when things fail Tool Declarations (code blocks with JSON Schema): - Tool name and description - Input parameters with types and validation - Output schema - Example usage
Bad description: 'A skill for doing code stuff' Better: 'Reviews pull requests for bugs, security issues, and style violations with line-level comments' Why: Descriptions are the first thing users and ClawHub search see. Vague descriptions get skipped. Specific descriptions get installs. Bad permissions: `fileAccess: write` (all paths) Better: `fileAccess: { write: ["./output", "./reports"] }` Why: Overly broad permissions trigger security warnings and fail our audit checklist. Scoped permissions build trust. Bad system prompt: 'You are a helpful assistant that can do many things.' Better: 'You are a code review expert specializing in TypeScript and Python. When reviewing code: 1) Check for bugs and logic errors first, 2) Flag security vulnerabilities with severity levels, 3) Suggest specific fixes with code examples, 4) Note style issues last. Never approve code with critical security issues.' Why: Generic prompts produce generic output. Specific, structured prompts produce consistent, high-quality results. See our complete skill architecture guide for deeper patterns.
1. Missing version number. ClawHub requires semantic versioning. Without it, your skill can't be published. 2. Overly broad permissions. Requesting all permissions 'just in case' triggers security flags. Only request what you need. 3. No error handling in the system prompt. If a tool call fails, what should the agent do? Without instructions, it hallucinates or crashes. 4. Hardcoded API keys. Never put credentials in the SKILL.md. Use the `apiKeys` permission field and let users provide their own. 5. No examples in tool declarations. The model performs better when tools include example inputs and outputs. 6. Conflicting instructions. If the system prompt says 'always use markdown' but a tool returns JSON, the agent gets confused. 7. Too many tools. Skills with 20+ tools overwhelm the model. Focus on 3-7 essential tools. 8. Missing category tag. Without a category, ClawHub can't index your skill and it won't appear in search. 9. No description or poor description. 'A useful skill' tells users nothing. Be specific about what the skill does and for whom. 10. Ignoring SKILL.md linting. Run `npx clawhub@latest validate ./SKILL.md` before publishing. It catches formatting errors, missing fields, and common issues. 11. Not testing with multiple models. A skill that works with GPT-5 may fail with Claude or Gemini. Test with at least two providers. 12. Forgetting the changelog. Users and reviewers want to know what changed between versions. Keep a changelog in the SKILL.md or as a separate file.
Once your SKILL.md is ready: 1. Validate: `npx clawhub@latest validate ./SKILL.md` Fixes formatting issues and checks required fields. 2. Test locally: `npx clawhub@latest install ./SKILL.md` Install from the local file and run several test prompts. 3. Publish: `npx clawhub@latest publish ./SKILL.md` Uploads to ClawHub. Your skill is immediately available but marked 'unreviewed.' 4. Request review: After publishing, request community review on the ClawHub listing page. Skills with 5+ positive reviews earn 'Community Verified' status. 5. Submit for ClawSkills review: If you want your skill featured in our directory, submit it via our contact form. We'll run our independent security audit and editorial review.
Can I write a SKILL.md in any language? SKILL.md files should be in English for ClawHub compatibility. The system prompt can instruct the agent to respond in other languages. How long should a SKILL.md be? Simple skills: 50-200 lines. Complex skills: 200-500 lines. Over 500 lines suggests the skill should be split into multiple skills. Can I use images or media in a SKILL.md? No. SKILL.md is plain text (markdown). Reference external URLs for images if needed. How do I update a published skill? Bump the version number in frontmatter, then publish again: `npx clawhub@latest publish ./SKILL.md`. ClawHub handles versioning automatically. Can I make a private skill? Yes. Don't publish to ClawHub. Install from local files: `npx clawhub@latest install ./path/to/SKILL.md`. For team distribution, use a private Git repo. What's the difference between a skill and an MCP server? A skill is configuration (behavior + tools). An MCP server is code (executable tool implementation). See our Skills vs Plugins vs MCP guide.