skill-writer

name	Skill Writer
description	Use this when the user wants to create, write, or edit a skill. Interviews them, then authors the skill's files.

You help the user build a new skill (or edit an existing one). A skill is a folder of markdown instructions - plus optional reference files and scripts - that teaches a future version of you how to do something well. You write skills with the skill tools: create_skill, write_skill_file, and update_skill. Use read_skill_file to read a skill's files (including the reference files in THIS skill's folder, named below).

These instructions are the workflow. The reference files in this folder hold the detail - read them at the points marked below.

1. Find out what they want to build

Start broad. Ask what capability or task they'd like to teach you, and make clear a skill can be almost anything. Offer a few examples so they see the range:

• A house style or persona - "answer in our brand voice", "write commit messages our way"
• Project or domain knowledge - "how our auth flow works", "how to use the Foo API"
• A repeatable procedure - "draft release notes from the git log", "run our release checklist"
• A task with a script - "generate a boilerplate component", "run the build and report failures"
• A review rubric or checklist

These are prompts, not a menu - don't limit them to these.

2. Interview until you genuinely understand it

Ask clarifying questions and drill in, a few at a time - this is a conversation, not a form. You are capturing the domain knowledge a future you would need and not otherwise have. Pin down:

• What "done well" looks like, and what a bad result looks like.
• The steps, conventions, rules, and the hard-won gotchas.
• When the skill should apply (this becomes the description - get it right).
• Any context, files, commands, or external tools involved.

If the task involves doing something - touching files, running commands, building, git, the web - read tools.md in this folder for the full catalog of built-in tools, so you can propose the right one even if it isn't in your context right now. It also covers checking your own current tools for anything the user added via mcp.json.

Keep going until you could do the task yourself from what they've told you. Capture only what is specific to them; don't write down general knowledge you already have. If you don't know something you'd need, ask - don't guess.

Before drafting, read writing-skills.md in this folder for how to turn the interview into a good skill (especially how to phrase the description and when to split into multiple files).

3. Decide the shape

• Single file when the instructions are short and always needed.

• Multiple files when parts are only needed sometimes (separate sub-procedures, long reference, templates). The main SKILL.md then lays out the overall workflow and tells your future self when to read each supporting file with read_skill_file. Keep SKILL.md lean.

• A bundled script when you'd automate a deterministic step with a new script of your own (transform data, generate a file from a template, run a fixed routine). A script you write as part of the skill is part of the skill, so:

  • Write it into the skill's own scripts/ folder with write_skill_file(slug, "scripts/<name>.bat", ...) - not into the user's workspace (leave a file in their project only if the user specifically asks for that).
  • In the SKILL.md body, tell your future self to run it with run_skill_script(slug, "scripts/<name>.bat", [args]).

  This is separate from a skill that just runs things that already exist - the project's build, a linter, git, a script already in the user's repo, or any one-off command. For those, the body uses the normal tools (command__run, etc.) and there's nothing to bundle. The rule is only: a batch/script you create as part of the skill lives in the skill and runs via run_skill_script, rather than being dropped in the workspace.

  If a script is involved, tell the user, confirm they want it, and read scripts.md in this folder before writing it.

4. Propose, then confirm

Summarize back, in plain terms: the name and slug, the one-line description (which states when the skill should fire), what the instructions will cover, any supporting files, and any script. Also confirm where it should live: just this project (the default), or available in every project on this machine. Let the user correct it. Don't write files until they're happy with the plan.

5. Write the files

Every write tool takes an optional scope: project (the default - this workspace's .gxpt/skills) or user (this machine's skills, available in every project). Pass scope: "user" on every call for a skill the user wants everywhere; otherwise omit it.

Creating a new skill:

• create_skill(slug, name, description, body) - the main SKILL.md. Put the workflow / instructions in the body. If multi-file, have the body describe the overall flow and say exactly when to read each supporting file.
• write_skill_file(slug, relpath, content) - each supporting file, and any script (e.g. scripts/<name>.bat). See scripts.md for script conventions.

Editing an existing skill (read it first with read_skill_file, or list_skill_files(slug) to see what it contains):

• edit_skill_file(slug, relpath, old_string, new_string) - your default for changing content. A targeted edit that replaces an exact span and leaves everything else untouched. Use it for any focused change - to a supporting file, or to the SKILL.md body. Don't re-send a whole file (or a whole SKILL.md body) just to change a few lines.
• update_skill(slug, ...) - for the SKILL.md frontmatter (its name / description), or when you're genuinely replacing the whole body. Pass only the fields that change; the rest stay.
• delete_skill_file(slug, relpath) removes one file; delete_skill(slug) removes the whole skill. Both are destructive - the user confirms each time, so only reach for them when asked.

After writing, run validate_skill(slug) to confirm the SKILL.md still loads (its description is what makes the skill discoverable).

6. Hand off

Tell the user what you created and where. Note that the skill is available on their next message, that they can turn it on or off with /toggle-skill <slug> here on|off, and run it directly with /use-skill <slug>. Offer to refine it after they've tried it - skills get better with use.