Skillcraft

Guide for creating and improving MoltBot/Clawdbot skills that follow the AgentSkills specification.

When to Use

• User asks to create a new skill
• User wants to improve or audit an existing skill
• User asks about skill structure, frontmatter, or best practices
• You need to package functionality as a reusable skill

Skill Directory Structure

skills/skill-name/
  SKILL.md          # Required: YAML frontmatter + instructions
  scripts/          # Optional: executable code
  references/       # Optional: supplementary docs (loaded on demand)
  assets/           # Optional: templates, data files

A copy-paste template is available at {baseDir}/assets/SKILL_TEMPLATE.md.

YAML Frontmatter (Required)

Every SKILL.md must start with YAML frontmatter:

---
name: skill-name
description: What this skill does. Activation triggers. When to use it.
---

Naming Rules

• 1-64 characters, lowercase alphanumeric + hyphens only
• No consecutive hyphens, no leading hyphens
• Must match the directory name exactly

Optional Frontmatter Fields

Metadata Gates

Control when a skill loads via metadata:

metadata: {"moltbot":{"os":["darwin","linux"],"requires":{"bins":["python3"],"env":["API_KEY"]}}}

• requires.bins — all listed binaries must exist on PATH
• requires.anyBins — at least one must exist
• requires.env — environment variables must be set (or in config)
• requires.config — config keys must be truthy
• os — restrict to specific platforms

Writing the Description

The description field is the most important field — agents use it to decide whether to activate the skill.

Rules:

1. Write in third person (not "I" or "you")
2. Include capabilities AND activation triggers
3. Use domain-specific terminology the user would actually say
4. Stay under 1,024 characters

Good: "Manage tasks in a SQLite database. Add, list, complete, prioritize, and search tasks. Use when the user mentions tasks, to-dos, or tracking work items."

Bad: "Helps with tasks" (too vague), "I manage your to-do list" (wrong perspective)

Body Content Guidelines

Token Budget

• SKILL.md body: under 500 lines (loaded when skill activates)
• Move detailed reference material to references/ (loaded only when explicitly read)
• Use {baseDir} to reference files in the skill directory

Recommended Sections

1. When to Use — specific trigger conditions and scenarios
2. Quick Start — minimal example to get going
3. Step-by-Step Process — numbered instructions for the main workflow
4. Examples — concrete input/output pairs
5. Error Handling — common issues and solutions

Conciseness Standards

• Assume the agent has baseline technical knowledge
• Challenge each paragraph: does it earn its token cost?
• One concept per section, no redundancy
• Prefer tables and lists over prose

Authoring Principles

1. Be specific and decisive. Don't list every option — recommend one approach. "Use pdfplumber for text extraction" beats "You could use pdfplumber, PyMuPDF, or tabula."

2. Consistent terminology. Pick one term per concept. Don't alternate between "task," "item," "entry," and "record."

3. Appropriate constraint levels:

   • High freedom (text guidance) — multiple valid approaches exist
   • Medium freedom (pseudocode/templates) — preferred patterns exist
   • Low freedom (exact scripts) — consistency is critical

4. No time-sensitive instructions. State the current method. Don't write "if before version X, do Y."

5. Use {baseDir} for paths. Never hardcode absolute paths in instructions.

Anti-Patterns

Skill Creation Checklist

Before considering a skill complete, verify:

• SKILL.md has valid YAML frontmatter with name and description
• name matches directory name (lowercase, hyphens, 1-64 chars)
• description is third-person, includes capabilities + triggers, <1,024 chars
• Body has "When to Use" section with specific trigger conditions
• Body includes at least one concrete example
• All file paths use {baseDir}, no hardcoded absolute paths
• Total SKILL.md is under 500 lines
• Verbose reference material is in references/, not inline
• Required binaries/env declared in metadata if applicable
• No time-sensitive or version-gated instructions

Detailed Reference

For full research including token cost calculations, security best practices, metadata gate examples, common patterns, and the complete AgentSkills specification details, read {baseDir}/references/best-practices.md.