make-skill

Make Skill

Create one new workspace Skill from the current conversation through planning, user approval, draft authoring, validation, and publication.

Resolve <workspace> from the runtime directory context: use the current agent's absolute workspace path (also the working directory when no separate project is configured). Pass that same value throughout the lifecycle, independently of the task's project directory and the script cwd. Lifecycle artifacts belong under <workspace>/.qwenpaw/make-skill/; published Skills belong under <workspace>/skills/.

Script interface

Run python scripts/<script> through execute_shell_command, setting cwd to this Skill's <dir> from the available-skills entry. Each script reads one JSON object from stdin (or --input <file>) and returns one JSON object. Every input includes workspace; the table lists the other top-level fields.

| Operation | Script | Other input fields | Successful result |

|---|---|---|---|

| Create a plan | create_plan.py | plan | plan_id, normalized plan |

| Revise that plan | create_plan.py | plan_id, complete new plan | Same plan_id, normalized plan |

| Initialize after approval | init_draft.py | plan_id | draft_id, skill_dir |

| Validate a draft | validate_skill.py | draft_id | digest |

| Publish a validated draft | publish_skill.py | draft_id, expected_digest from validation | Publication result |

plan_id identifies one editable plan; keep it across revisions, including renames. draft_id identifies the initialized draft for validation, testing, and publication; skill_dir is where its package files belong. Use the returned values unchanged, not IDs inferred from names or paths.

Plan

The focus in /make-skill <focus> is required. For a natural-language request, infer it from the request and current conversation. Later user corrections replace conflicting earlier rules. Preserve stable guidance, contracts, templates, and workflows that should change future behavior; exclude one-off data, temporary paths, secrets, and retry chatter.

Read [primary type and package](references/type-and-package.md), then choose one primary type and only the files it needs. When the proposed test mode is not off, read [behavior testing](references/behavior-testing.md) before defining its target.

Batch workflows

A stored batch is a parameterized run_tool_batch program bundled with a workflow Skill. Use batch: true when a reusable region's actions, branches, and success condition can be stated before execution and one stored entrypoint saves meaningful agent-tool round trips. The region may be the whole workflow, one substantial helper, or one semantic tool-native action; action count is not the criterion. Runtime data, observations, and a final agent review do not prevent batching when the rule for handling them is already known.

Use batch: false only when execution must invent the next action or success condition at runtime, or a shared entrypoint has no practical reuse value. If the user explicitly requests Batch, apply that choice to the plan without reopening eligibility.

Only after selecting batch: true, read [run batch](references/run-batch.md) before finalizing the workflow and file tree. When batch: false, do not read it.

Save and review the plan

Planning is read-only except for saving the plan through create_plan.py: use conversation evidence and existing artifacts, but do not execute or probe the proposed workflow, create package files, or initialize a draft. For first creation, omit plan_id and pass a complete candidate:

{
  "workspace": "<workspace>",
  "plan": {
    "revision": 1,
    "focus": "One-sentence extraction scope",
    "name": "lowercase-hyphen-name",
    "goal": "Outcome for a future agent",
    "type": "workflow",
    "batch": true,
    "steps": ["A user-reviewable workflow step"],
    "package": ["SKILL.md", "scripts/run.batch.json"],
    "execution": "foreground",
    "test": {"mode": "off", "target": ""},
    "warnings": []
  }
}

To revise, add the returned plan_id to the top-level input above and replace plan with the complete revised candidate, not a partial patch. This updates the existing plan without creating a copy. If an update reports missing-plan, return to planning and approval instead of building. A saved plan is not evidence of user approval.

Render the normalized plan in English and show the selected value together with every available choice so the user can revise it without knowing the schema. The user-visible plan must contain this compact options table; do not replace it with prose or an approval hint. Omit the Batch row for a non-workflow:

| Option | Selected | Available |

|---|---|---|

| Type | current English label | instruction / template / workflow |

| Batch (workflow only) | enabled or disabled | enabled / disabled |

| Execution | foreground or background | foreground / background |

| Behavior test | current English label | off / smoke / eval (full behavioral evaluation) |

Also show the name, goal, workflow, complete file tree, test target when applicable, and warnings. Pass the internal values instruction/template/workflow, true/false, foreground/background, and off/smoke/eval to the script. Do not invent a full enum or any choice outside the script schema. Do not show a Batch closing reason, schema, revision, or internal enum. Ask the user to approve, modify, or cancel, then end the response without further tool calls.

Only a new user message explicitly approving the latest displayed create_plan.py result permits Build. Invoking /make-skill starts planning; earlier task discussion or a hand-written outline does not replace this plan and approval step.

• After a modification, merge the feedback, increment revision, and update the same plan. Revise serially within the current conversation, then show the complete returned plan for approval; earlier approval does not carry over.
• Stop on cancellation, retaining the plan without creating a draft. Distinguish acknowledgment from approval; if the user's intent is unclear, ask one brief confirmation and wait.
• Do not ask separately about execution or testing.

This version creates new Skills only. Resolve a name conflict through a newly approved revision; never overwrite an existing Skill.

Build

After approval, run init_draft.py with the saved plan_id. Initialization snapshots the current plan into a new draft; later plan edits do not update that draft. It does not accept an inline replacement. If the plan is missing or invalid, return to planning instead of proceeding to Build.

execution selects whether the current agent or a background subagent completes Skill creation. After initialization, for background, use spawn_subagent with background: true and give the generic subagent the complete approved plan, latest corrections, workspace, draft_id, and skill_dir to author the files, validate, run the approved behavior test, and publish without requesting approval again. Report the creation result when finished; running the generated Skill outside the approved behavior test requires a separate user request.

Create only approved files under the returned skill_dir. Start the generated SKILL.md with valid frontmatter:

---
name: lowercase-hyphen-name
description: Briefly state the capability and when to use it.
---

Keep the body to essential procedure and constraints without repeating the description. Type metadata is unnecessary.

Before validation, read the package from the perspective of a future agent that cannot see the source conversation. Remove references to source task directories, prior outputs, temporary IDs, current-case examples, or make-skill draft/publish language unless that resource is deliberately packaged and reusable. When adapting an existing helper, generalize its paths, docstrings, and reporting, and check that its implementation still matches the final reusable rules. Keep this as one authoring pass; do not add case-specific lifecycle checks.

Validate, test, and publish

Before executing any draft script or batch, run validate_skill.py for the initialized draft.

Fix reported static or security errors in the draft and validate again. Testing is independent of Batch: run exactly the approved behavior test according to [behavior testing](references/behavior-testing.md), and let off perform no draft execution. When a test or Batch run fails, retain the draft, report the concrete error, revise the Skill if the correction is clear, then validate again; do not hide the failure behind a fallback.

Publish the unchanged validated draft with publish_skill.py, using the validation result's digest as expected_digest.

On success, report the package tree, validation summary, test result when one ran, and invocation /<name>. On conflict or failure, retain the draft and report the error. Publishing a Skill is already persistent; do not also write it to MEMORY.md or daily memory unless the user separately asks.