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)** ```markdown ## 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** ```bash scripts/gather.py --type company --name "Acme Corp" --context meeting ``` ```python # 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)** ```markdown ## 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](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:** ```yaml --- 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):** ```yaml 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):** ```yaml 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: ```json { "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