Craftbot Skill Creator

CraftBot Skill Creator

Author a reusable skill from one completed task. The handler that spawned this task already gathered everything you need into a single markdown file — read it, generalise it, write the new skill, send the user a one-message summary, end the task. The handler has already posted "Creating skill <name>…" in chat for you, so do not duplicate that message. Your only chat message is the final presentation right before end_turn. Do not iterate with test cases. Do not run subagents.

What you receive

Your task instruction contains five lines (the two paths are absolute — pass them verbatim to read_file / write_file, do NOT prepend or modify any prefix):

Source file (read this — absolute path, use verbatim): <absolute path to SKILL_SOURCE_<id>.md>
Target file (write the new SKILL.md here — absolute path, use verbatim): <absolute path to skills/<name>/SKILL.md>
Mode: create
Skill name: <kebab-case-name>

⚠️ Do not invent your own path for the target file. The handler has already placed it at the correct location under the project's skills/ directory; using the literal value of Target file: puts the SKILL.md where the framework will discover it. A common mistake is generalising the source's agent_file_system/ prefix onto the target — that lands the new skill in the wrong directory and CraftBot will never see it.

SKILL_SOURCE_<task_id>.md has YAML frontmatter (mode, target_skill, source_task_id, generated_at) and these body sections, in order:

• ## Task name — the short task title shown in the action panel. Treat this as a one-line summary of what the user wanted, not a verbatim instruction (the original instruction is not retained on disk after the source task ends).
• ## Outcome — status, created/ended timestamps, the skills the source task had attached, and any internal workflow_id.
• ## Action trace — every action and reasoning item the source agent emitted, in order, with input, output, error, and duration. This is your primary evidence — it is the durable record of what actually happened, kept in actions.db.

create mode means there is no existing SKILL.md for the target name; you write a fresh one.

The Task name and the action trace together are enough to reconstruct the workflow. Treat the trace as the ground truth — the name is just a hint about user intent.

What you produce

Two artefacts, in order:

1. One file at the path given by Target file: in your task instruction (an absolute path under the project's skills/ directory). Pass that path verbatim to write_file (or create_file). The directory does not exist yet; write_file creates the parent directory in the same call.
2. One presentation message to the user via send_message, immediately after the file is written and immediately before end_turn. See Presentation message below for the format.

Do not write any other files. Do not send any chat message other than the single presentation one — the handler has already posted the "Creating skill …" acknowledgement.

Capture intent — from the source task

You will not interview the user. The source task IS the workflow you are codifying. Read SKILL_SOURCE_<task_id>.md once with read_file, then answer these four questions for yourself before drafting:

1. What should this skill enable CraftBot to do? Use the ## Task name as a hint, then walk the ## Action trace to see what the agent actually accomplished. Generalise: strip the specific subject ("PRs in repo X" → "summarise PRs in a repository"). The skill must be reusable across many invocations.
2. When should this skill trigger? What user phrases or contexts would lead someone to want this workflow next time? Be concrete in the description (see Description below).
3. What is the output format? Look at the final write/output actions in the trace. The skill should specify the same shape so future invocations produce comparable results.
4. What is the shortest happy path? The source agent may have re-queried, backtracked, or self-corrected. Walk the trace and identify the one sequence that gets to the outcome. Earlier dead-ends do not belong in the skill body — but a ## Common pitfalls section can mention them so future runs avoid them too.

If the source task has very thin evidence (one or two actions, no real workflow), still write a useful skill — but keep the body short and honest. Don't pad.

Anatomy of a CraftBot skill

skills/<skill-name>/
├── SKILL.md           (required)
│   ├── YAML frontmatter
│   └── Markdown body
├── scripts/           (optional — executable helpers)
├── references/        (optional — long docs the agent can read on demand)
└── assets/            (optional — templates, fixtures)

You will only write SKILL.md in this workflow. The optional directories exist for skills authored by hand; do not create them here even if the source task touched many helper scripts. (If you notice strong repeated work in the trace, mention it in ## Common pitfalls so a human author can come back and bundle it later.)

Frontmatter — the four fields

CraftBot extends Anthropic's standard frontmatter (name, description) with two local fields (user-invocable, action-sets) — both required.

---
name: <kebab-case-skill-name>
description: <one paragraph — see Description below>
user-invocable: true
action-sets:
  - <action-set-1>
  - <action-set-2>
---

Description — make it pushy

CraftBot tends to under-trigger skills it isn't sure about. A bare functional description like "Summarise GitHub PRs" loses to a skill with the same purpose but a more directive description. Aim for two parts: what + when. Use ~50–120 words.

Bad (too thin, won't trigger):

description: Summarise GitHub PRs.

Good (does the job):

description: Summarise the recent GitHub pull requests in a repository, grouped by author. Use this whenever the user asks for a PR digest, weekly engineering summary, "what shipped this week", or a code-review activity report — even if they don't say "PR" explicitly. Produces a markdown summary with one section per author and a one-line entry per PR.

The "Use this whenever…" clause is what fixes under-triggering. Include 2–4 phrasings the user might actually type, plus the output shape.

Body — sections to include

The body is markdown loaded into context whenever the skill triggers. Keep it under ~300 lines for a one-task-derived skill (Anthropic's general ceiling is 500). If the workflow seems to need more, that is a sign you are over-fitting to the source task.

Include these sections, in this order. Skip optional ones if they have nothing useful to say.

1. # <Title-Case Name> + one-paragraph overview. What the skill enables. What kind of input it expects. What it produces.
2. ## When to use (optional but recommended). Bullet list of trigger scenarios. The description already covers this; this section is for nuance — domains, adjacent cases, "use this instead of X when…".
3. ## Definition of Done. Numbered list of observable conditions that mark the task complete. Future agents will use this to decide whether to call end_turn.
4. ## General Steps. Numbered list. The shortest happy path, derived from the source action trace. One imperative sentence per step. No specific values. No code.
5. ## Output Format (if the skill produces structured output). The exact template the agent should write. Use a fenced code block.
6. ## Examples (0–2 examples). Realistic input → output pairs. Strip identifying details. Each example should be ~5–15 lines, not pages.
7. ## Common pitfalls (only if the source trace contained real evidence). Bullet list. Each bullet: the symptom you saw, then the avoidance. See Mistake-scanning below.
8. ## Allowed Actions. Comma-separated list of action names the skill expects to use, drawn from the source action trace.

Do not include sections for: testing, evaluation, packaging, description optimization. Those are the human author's job. The single SKILL.md is your only deliverable.