skillcraft

What this skill does

# 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