skillcraft

Skillcraft - Clawdbot Skill Creator

An opinionated, AI-native design guide for Clawdbot skills. Focuses on clawdbot-specific integration patterns — message routing, cron scheduling, memory persistence, channel formatting — not generic programming advice.

Assumes: The agent knows how to write code, structure projects, and handle errors. This skill teaches clawdbot-specific concerns.

Prerequisites

Load the clawddocs (or equivalent) skill first. This skill relies on Clawdbot documentation for authoritative feature details. The clawddocs skill provides:

• Documentation category navigation (see categories below)
• Search scripts for finding specific docs
• Config snippets for common patterns

Documentation categories (via clawddocs):

Category	Path	Use for
Gateway & Config	/gateway/	Configuration, security, health
Tools	/tools/	Skills, browser, bash, subagents
Automation	/automation/	Cron jobs, webhooks, polling
Concepts	/concepts/	Sessions, models, queues, streaming
Providers	/providers/	Discord, Telegram, WhatsApp, etc.

When this skill says "consult documentation," use clawddocs to fetch the relevant doc.

Core Philosophy

Skills are how Clawdbot extends itself. They survive context limits, compose cleanly, and share via ClawdHub.

Most good skills start as scattered notes before anyone formalizes them. This skill is a protocol for that formalization — turning "remember to do X" into something that composes and shares.

---

The Design Sequence

Follow these stages in order. Each produces artifacts that feed the next.

Two entry modes:

• New skill: Start at Stage 1
• Extracting existing functionality: Start at Stage 0

---

Stage 0: Inventory (Extraction Only)

Skip this stage if building a new skill from scratch.

Use this when functionality already exists but isn't packaged as a skill. Common sources:

• Scripts in <workspace>/scripts/ that aren't part of any skill
• Instructions buried in TOOLS.md or AGENTS.md
• Patterns repeated across conversations
• "Remember to do X" notes that should be formalized

Gather the artifacts:

Ask:

• Where does it live? (scripts, TOOLS.md section, memory notes, conversation patterns)
• What does it do? (describe the capability)
• How is it currently triggered? (manual request, heartbeat check, ad-hoc)
• What Clawdbot features does it use? (exec, cron, message, memory, etc.)

Example inventory:

- scripts/mail/check.py — fetches and processes emails
- TOOLS.md ## Mail Rules — documents the mail command syntax  
- HEARTBEAT.md — includes "run mail heartbeat" instruction
- mail-rules.yaml — configuration file

Assess current state:

• What's working well? (keep it)
• What's fragile or unclear? (improve it)
• What's missing? (add it)
• What's over-engineered? (simplify it)

Output: Inventory of existing artifacts with assessment notes. Then proceed to Stage 1.

---

Stage 1: Problem Understanding

Goal: Concrete clarity on what the skill does and when it's needed.

Work through these questions with the user:

1. What does this skill do? (one sentence)

2. When should this skill be loaded?

   • What would a user say? (3-5 example phrases)
   • What mid-task needs might lead here? (e.g., "need weather data", "need to send a message")
   • Any scheduled/periodic triggers? (heartbeat, cron)

3. What does success look like? For each example, what's the outcome?

If extracting: Derive from actual usage, not just hypotheticals. It's ok to generalise the problem if that's what the user wants.

Output: Problem statement with trigger examples and success criteria.

---

Stage 2: Capability Discovery

Goal: Understand what the skill needs to work with.

Generalisability

Ask the user: Is this skill for your setup specifically, or should it work for any Clawdbot instance?

Choice	Implications
Universal	Generic paths (<workspace>/), no assumptions about installed tools, minimal references to user-specific config, suitable for ClawdHub
Particular	Can reference specific local paths, skills, tools, TOOLS.md entries; tailored to user's workflow

This affects many downstream decisions. Capture it early.

If extracting: Also decide what stays in workspace (user config, state) vs. what moves to skill (scripts, instructions, references).

Skill Synergy Search (Particular Only)

Skip this section if building a Universal skill.

When building for a particular setup, leverage existing workspace capabilities:

1. Scan available skills — review the skill descriptions in <available_skills> from your system prompt
2. Identify promising synergies — look for skills that:
   • Provide data sources this skill could consume (e.g., calendar, contacts, location)
   • Offer complementary capabilities (e.g., notification, storage, presentation)
   • Handle adjacent domains that might integrate naturally
3. Deep-read promising skills — for each skill with apparent synergy, read its SKILL.md to understand:
   • Exact capabilities and invocation patterns
   • Output formats that could be consumed
   • State or configuration that might be shared
   • Opportunities for composition or delegation

Prioritise skills which have their dependencies fulfilled and are in active use.

Example: Building a "daily briefing" skill? Scan for: calendar skills (event data), weather skills (forecast), mail skills (unread count), location skills (context-aware content). Read each to understand how to compose them.

Output from this step: List of synergistic skills with brief notes on how each might integrate.

External Dependencies

• Does it wrap a CLI tool? Which one? Is it installed? What's the basic usage pattern?
• Does it wrap a web API? What's the base URL? Auth mechanism? Rate limits?
• Does it process local files? What formats? What transformations?

Clawdbot Features

Clawdbot has powerful built-in features with deep semantics and rich configurability. They can be combined in unexpected ways to solve user problems.

Conduct a creatively-minded review of the documentation with the skill's needs in mind. Use clawddocs to explore — start with /concepts/ and /tools/ categories. Think like a meta-programmer: Clawdbot's features are primitives that compose. A skill might combine cron scheduling with canvas presentation and node camera access in ways no single feature anticipates. If a solution would require a configuration change, check /gateway/configuration and suggest it to the user.

Documentation categories to explore:

Need	Doc Category	Tools/Features
Send messages	/concepts/messages	message tool
Scheduled tasks	/automation/cron-jobs	cron tool
Persistent memory	/concepts/	Memory system, state files
Background work	/tools/subagents	sessions_spawn
Device interaction	/nodes/	nodes tool (camera, screen, location)
UI presentation	/tools/	canvas tool
Web browsing	/tools/browser	browser tool
Web research	/tools/	web_search, web_fetch
Image analysis	/tools/	image tool

Verify feature usage against documentation. Don't assume — features evolve and have nuances. Use clawddocs to check:

• Tool parameters and capabilities (fetch the relevant /tools/ doc)
• Channel-specific constraints (check /providers/ for the target channel)
• Configuration requirements and defaults (/gateway/configuration)
• Known gotchas or limitations

Output: Capability map listing external deps, Clawdbot features to use, and generalisability choice.

---

Stage 3: Architecture

Goal: Identify applicable design patterns and propose initial architecture.

Based on Stages 1-2, identify which patterns apply. Load relevant pattern references:

If the skill...	Load pattern
Wraps a CLI tool	patterns/cli-wrapper.md
Wraps a web API	patterns/api-wrapper.md
Monitors and notifies	patterns/monitor.md

Skills often combine multiple patterns. Load all that apply and synthesize.

Script vs. Agent Instructions

A critical design juncture: how should executable scripts be combined with agent instructions in SKILL.md?

Use scripts when:

• The operation is deterministic and repeatable
• Complex logic that's error-prone to re-derive each time
• Performance matters (script runs faster than AI reasoning)
• External tool interaction with specific syntax
• State management with precise file formats

Use agent instructions when:

• Judgment is required (interpreting results, choosing approaches)
• The task varies based on context
• Natural language interaction is primary
• Flexibility matters more than consistency
• The "how" depends on "what" (can't be predetermined)

The split: scripts handle the mechanics, instructions handle the judgment.

Example: Context Briefing Skill

A skill that prepares briefings before meetings. This illustrates the full agent→script→agent flow.

User message:

"Brief me on Acme Corp before my 2pm call"

Phase 1: Agent parses and routes (SKILL.md instructions)

## Handling Briefing Requests

When user requests a briefing:
1. Extract the **subject** (company, person, project, topic)
2. Extract **context** if provided (meeting, call, presentation, general)
3. Check calendar for related upcoming events
4. Run the appropriate gather script based on subject type:
   - Company/org → `scripts/gather.py --type company --name "..."`
   - Person → `scripts/gather.py --type person --name "..."`
   - Project → `scripts/gather.py --type project --name "..."`
5. Analyze results and compose briefing (see Phase 3)

The agent interprets "Acme Corp" as a company, "2pm call" as meeting context. It checks calendar, finds "Call with Acme Corp re: Q2 partnership" at 2pm.

Phase 2: Script fetches external data

scripts/gather.py --type company --name "Acme Corp" --context meeting

# scripts/gather.py - deterministic data gathering
def gather_company(name: str, context: str) -> dict:
    return {
        "emails": search_emails(f"from:{domain} OR to:{domain}", days=30),
        "calendar": get_related_events(name, days=14),
        "web": search_web(f"{name} news", recent=True),
        "contacts": find_contacts(name),
        "history": load_prior_briefings(name)  # from state
    }
    # Output: structured JSON with all gathered data

Phase 3: Agent synthesizes and acts (SKILL.md instructions)

## Composing the Briefing

With gathered data, synthesize: key context, recent activity, news, relationship history, suggested talking points, and warnings.

If meeting is <1 hour away, send immediately. If >1 hour, offer to set a reminder.

After delivery: log to `<workspace>/memory/`, update `<skill>/state.json`.

The agent composes a briefing from the structured data, using judgment to prioritize and frame.

If user confirms reminder → dynamically select the appropriate reminder system. The skill doesn't hardcode "use Apple Reminders" — it checks what's available (Apple Reminders skill? Google Calendar? cron-based?) and routes accordingly. This is agent judgment, not script logic.

---

Composable Pattern Examples

Skills often combine multiple Clawdbot primitives in non-obvious ways. See patterns/composable-examples.md for 7 detailed examples:

1. Visual Monitoring Pipeline (nodes + image + canvas + message)
2. Parallel Research Aggregator (sessions_spawn + web_search + browser)
3. Location-Aware Context Switcher (nodes + cron + memory)
4. Cross-Channel Thread Tracker (message + memory_search + sessions_send)
5. Scheduled Report Generator (cron + exec + browser + canvas)
6. Interactive Approval Workflow (message + cron + memory + gateway)
7. Adaptive Learning Loop (image + memory + cron)

Output: Selection of Clawdbot system features with rationale (if any), initial architecture sketch.

Stage 4: Design Specification

Goal: User-reviewed specification ready for implementation.

State Requirements

• Stateless: Pure function of inputs, no memory needed
• Session-stateful: Remembers within a conversation (use context)
• Persistent-stateful: Survives restarts (needs file-based state)

If persistent state is needed, where should it live?

• <workspace>/memory/ — for context that's part of the user's memory
• <skill>/state.json — for skill-internal state (lives with the skill)
• <workspace>/state/<skill>.json — for skill-internal state (common workspace area)
• <workspace>/TOOLS.md — for user-specific configuration notes

By default, skills shouldn't write state outside the workspace. ~/.clawdbot/ and other system-level config directories are not suitable for state storage.

User Preferences & Environment

Ask about the user's existing setup:

• Scripting language preference? (Python, Bash, etc.)
• Coding style preferences? (types, functional idioms, etc.)
• Existing shared environment? (venv, uv, conda that scripts should use)

Check USER.md and TOOLS.md for documented coding preferences.

Secret Handling

If the skill needs API keys or credentials:

1. Ask how the user handles secrets — they may have existing patterns
2. Default to environment variables — SERVICENAME_API_KEY
3. Document the requirement — in SKILL.md setup section
4. Never hard-code secrets — not in scripts, not in skill files

Common patterns:

• Environment variables (most portable)
• macOS Keychain via security command
• Config file in ~/.config/skillname/ (gitignored)
• 1Password CLI (op read)

Proposed Architecture

Present the proposed architecture:

1. Skill structure — files and directories
2. SKILL.md outline — sections and key content
3. Software — high level requirements for each software component (script, module, wrapper)
4. State management — where and how state is persisted
5. Clawdbot integration points — which features, how they interact

If extracting: Include migration notes — what moves where, what workspace files need updating.

The specification is a review checkpoint. Its purpose is letting the user verify:

• Assumptions about Clawdbot integration are correct
• The design fits their existing workflow
• No conflicts with existing workspace files or tools
• Generalisability matches their intent

Validate against requirements:

• Does it handle all the examples from Stage 1?
• Are Clawdbot features used correctly? (verify via clawddocs)
• Is the state approach appropriate for the access pattern?
• Are there edge cases or failure modes to handle?
• Has the proposed architecture revealed any contradictions in the Stage 1 requirements?

Iterate until the user is satisfied. This is where design problems surface cheaply.

Output: Design specification including state approach, user preferences, secret handling, and skill structure.

---

Stage 5: Implementation

Goal: Working skill with all components.

Strong default: Same-session implementation. Work through the spec with user review at each step. This keeps the user in the loop for integration decisions.

Coding-agent handoff is optional and should be reserved for complex software subcomponents only — not entire skills. The SKILL.md and integration logic should stay in the main session where the user can review.

Implementation Steps

Work through in order, with user review at each checkpoint:

1. Create skill directory
2. SKILL.md skeleton — frontmatter + section headers → Review: is the structure right?
3. Scripts (if any) — get executable pieces working → Review: test each script
4. SKILL.md body — complete instructions
5. Test against Stage 1 examples → Review: does it handle all examples?

If extracting: 6. Update workspace files (remove migrated content, add skill references) 7. Clean up old locations 8. Verify skill works standalone

Crafting the Skill Frontmatter

The SKILL.md frontmatter determines discoverability and provides structured metadata. The description field is critical — when the agent scans available skills, this determines whether the skill gets loaded.

See https://docs.clawd.bot/tools/skills for Clawdbot-specific metadata documentation.

Frontmatter format:

---
name: my-skill
description: [description optimized for discovery]
homepage: https://github.com/user/repo  # optional
metadata: {"clawdbot": {"emoji": "🔧", "requires": {"bins": ["tool"], "env": ["API_KEY"]}, "install": [...]}}
---

Description field — write for keyword matching and context recognition:

• What it does — the core capability
• Keywords — terms users might say that should trigger this skill
• Contexts — situations where this skill applies
• Trigger phrases — natural language patterns that indicate relevance

Example (good):

description: Download videos/audio from YouTube and other sites with interactive quality selection, learned preferences, and recent directory tracking. Use when user shares a video URL or asks to download video/audio.

Example (too sparse):

description: YouTube downloader.

Metadata field (optional but recommended for publishable skills)

Refer to the format specification at https://docs.clawd.bot/tools/skills.

Simple example:

{
  "clawdbot": {
    "emoji": "📍",
    "requires": {
      "bins": ["goplaces"],
      "env": ["GOOGLE_PLACES_API_KEY"]
    },
    "primaryEnv": "GOOGLE_PLACES_API_KEY",
    "install": [
      {
        "id": "brew",
        "kind": "brew",
        "formula": "steipete/tap/goplaces",
        "bins": ["goplaces"],
        "label": "Install goplaces (brew)"
      }
    ]
  }
}

Test the description: Would the agent select this skill if the user said each of your Stage 1 example phrases? If not, add the missing keywords.

Output: Complete skill directory ready for use.

---

Path Conventions

Skills must handle paths carefully, especially for portability and multi-agent contexts.

Notation

Prefix	Meaning	Example
<workspace>/	Agent's workspace root	<workspace>/TOOLS.md
<skill>/	This skill's directory	<skill>/scripts/check.py
(no prefix)	Skill-relative path	scripts/helper.sh

Rules:

• Workspace files: Always use <workspace>/ prefix
• Skill components: Relative paths OK (refers to skill directory)
• Never hardcode ~/clawd or similar — workspaces are portable
• State files: Use <workspace>/ paths, not ~/.clawdbot/ (skills don't own user home)

Sub-Agent Considerations

Sub-agents via sessions_spawn may run in sandboxed containers with different mount points. Use clawddocs to check /tools/subagents for current sandbox configuration and path translation requirements. When spawning sub-agents that need workspace files, include path context in the task description.

Workspace Awareness

Skills may interact with workspace structure:

File	Purpose	When to reference
<workspace>/TOOLS.md	Local tool notes	CLI wrappers storing user-specific config
<workspace>/MEMORY.md	Long-term memory	Skills that contribute to memory
<workspace>/memory/	Daily logs	Skills that log activity
<workspace>/HEARTBEAT.md	Periodic checks	Heartbeat-driven skills
<workspace>/USER.md	User context	Skills needing user info

Principle: Skills document what workspace files they touch and why.

---

References

Pattern references for common skill types:

• patterns/cli-wrapper.md — wrapping CLI tools
• patterns/api-wrapper.md — wrapping web APIs
• patterns/monitor.md — watching conditions and notifying