Craftbot Skill Improve

CraftBot Skill Improver

Refine one existing skill using evidence from one task that used it. The handler that spawned this task already gathered everything you need into a single markdown file — read it, diff it against the live skill, apply small surgical edits, send the user a one-message summary of the changes, end the task. The handler has already posted "Improving 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 / stream_edit, do NOT prepend or modify any prefix):

Source file (read this — absolute path, use verbatim): <absolute path to SKILL_SOURCE_<id>.md>
Target file (edit this — absolute path, use verbatim): <absolute path to skills/<existing-name>/SKILL.md>
Mode: improve
Skill name: <existing-skill-name>

⚠️ Do not invent your own path for the target file. Using the literal value of Target file: ensures stream_edit modifies the actual installed SKILL.md.

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

• ## Task name — the short task title shown in the action panel. A one-line summary of intent, not a verbatim instruction.
• ## Outcome — status, created/ended timestamps, the skills the source task had attached, and any internal workflow_id.
• ## Action trace — every action and reasoning item, in order, with input, output, error, and duration. This is your primary evidence — it is the durable record of what actually happened.
• ## Existing SKILL.md — the verbatim contents of skills/<target>/SKILL.md as captured at the moment the workflow started.

The target skill exists. Your job is to edit it in place. The action trace is the evidence; the existing SKILL.md is what you are diffing against.

What you produce

Two artefacts, in order:

1. Targeted edits to exactly one file: the path given by Target file: in your task instruction (an absolute path under the project's skills/ directory). Pass that path verbatim to stream_edit. Do not do a whole-file rewrite of it — that clobbers the rest of the file. Do not write any other files. Do not change the directory layout. Do not delete bundled resources in scripts/, references/, or assets/.
2. One presentation message to the user via send_message, immediately after the edits and immediately before end_turn. See Presentation message below for the format.

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

Improvement constraints — what makes this different from creation

These four rules are the heart of improve mode. Read them before drafting.

1. Do not redesign the skill. The existing skill encodes a tested workflow. Your job is refinement, not rewriting. Drastic restructuring regresses use cases that this single source task never exercised. Why: one task is a sample size of one. The skill has likely been used many times before; you are seeing one slice.

2. Optimise for accuracy AND token efficiency. A change is justified if and only if it does one of:

   • Prevents a class of mistake the source task hit (and that the existing skill did not warn about), OR
   • Shortens the skill without removing meaning (kill filler, redundant restatements, dead bullets). Why: both quality and prompt-cost matter. Skills are loaded into context every time they trigger.

3. Prefer surgical edits over wholesale rewrites. One stream_edit per change. Each edit replaces or inserts a small contiguous range. If you are about to replace half the file, stop — that is redesign, not refinement. Why: small diffs are reviewable and reversible by humans afterwards.

4. Do not invent pitfalls. If the source task ran cleanly, do not add speculative warnings. If the trace shows the existing pitfall warnings are wrong, fix or remove them. Why: unfounded warnings dilute real ones; agents start ignoring the section.

How to think about improvements

These come straight from Anthropic's skill-improver guidance and apply here verbatim.

• Generalise from the feedback. The skill will be invoked many more times than just this one task. If a fix only works for the source task's specific scenario, it's overfitting. Prefer changes that handle a class of cases, not the literal symptoms you saw.
• Keep the prompt lean. Read the action trace, not just the final outputs. If the existing skill told the agent to do something that the trace shows was wasted effort, removing that instruction is a valid improvement.
• Explain the why. When you add a rule, add a *Why:* … line right after it. When you sharpen an existing rule, preserve any existing *Why:* line — those are gold.
• Look for repeated work. If the action trace shows the agent independently wrote the same helper logic the existing skill could have bundled, mention it in the skill body so a human author knows to bundle it later. Do not attempt to create scripts/ files yourself — that's outside this workflow's scope.

CraftBot frontmatter — what you can and cannot change

CraftBot skills have four frontmatter fields:

Anatomy reminder

skills/<skill-name>/
├── SKILL.md           ← edit this only
├── scripts/           ← do not modify in this workflow
├── references/        ← do not modify in this workflow
└── assets/            ← do not modify in this workflow

Bundled resources may exist for the target skill. Leave them alone. If the source trace suggests one of them is outdated, mention it in ## Common pitfalls so a human can revisit.

Workflow

Use update_todos at the start to track these. Mark each completed before moving on.

1. Read the SOURCE. read_file on the path from your task instruction. Note the action trace, errors, summary, and the verbatim existing SKILL.md.
2. Re-read the live target. read_file on skills/<target-skill>/SKILL.md. The SOURCE may be milliseconds stale; the live file is authoritative for line offsets when you stream_edit.
3. Diff in your head. Two questions:
   • What did the source task do that the existing skill does not document (and should)?
   • What did the source task do that the existing skill says to do but evidence shows is wrong / extra?
4. Plan a small edit list. Each entry is one of: add a pitfall, trim a redundant step, sharpen wording for accuracy, shrink wording for tokens. Aim for 1–4 edits. If you find yourself listing 10, you are redesigning — pick the highest-leverage few and stop.
5. Apply edits. One stream_edit per item in the list. Re-read the file between edits if line offsets have shifted significantly.
6. Send the presentation message via send_message. See Presentation message below.
7. end_turn with a one-line summary of what changed.