Writing SKILL.md Files With Claude: The Session Sequence That Produces a Working Skill

Skills written from scratch drift. The first run looks right, the third run produces something different, and you cannot tell whether Claude changed its interpretation or the inputs were subtly different. The fix — more explicit instruction — costs context. The fix for that — prune the instruction — reintroduces the variance. The iteration loop is manual and uncaptured, and every new skill starts the same process from zero.

Using Claude to write the skill via the skill-creator workflow makes that loop shorter and legible. The session produces a structured SKILL.md checked against the requirements you gave it, and the packaging step produces a .skill file with a copy-to-skills button. What follows is the session sequence that gets you there without manual cleanup afterward.

Jump to Commands Reference →

Write the Brief Before You Open Claude

The most common failure mode in skill-creator sessions is arriving without a clear picture of what success looks like. Claude will produce a skill either way — but without a brief, you have no basis for evaluating whether the draft is correct. You end up iterating on feel rather than on specifics, and the iteration takes longer than writing the brief would have.

The brief is not a prompt. It is a written document covering four things: what the skill does and when it should be invoked, what it reads as input and what it produces as output, what constraints the environment imposes (file locations, format requirements, things that cannot be deleted), and what the logging needs to capture. It should be specific enough that someone reading it without context would understand what a correct skill output looks like.

The leanness constraint belongs in the brief, not as an afterthought once the draft arrives. If you do not specify it, the skill-creator will default toward completeness over leanness, and the resulting file will spend words on procedure that Claude does not need. The constraint to state explicitly: prefer a brief over a procedure — describe the problem space, the quality bar, and the judgment calls, not the sequence of steps.

Two things that do not belong in the brief: the step-by-step sequence you want the skill to follow (that goes in the skill file, not in the requirements document), and tone or style guidance Claude can draw from the brand skill without being told.

Running the Skill-Creator Session

Invoke the skill-creator skill. When it asks for the task description, provide the brief — not a summary of the brief, the brief itself. Then add the leanness constraint as a separate line after the brief:

Make the skill lean enough to execute reliably without losing the judgment call context.
Prefer a brief over a procedure. The SKILL.md should describe the problem space, the
output requirements, and the decisions that matter — not the sequence of steps.

Then specify the output path in the same prompt. The file must be written to disk before the session ends — anything that exists only in context is gone when the session closes. Specify the destination up front:

Write the SKILL.md to: /path/to/skills/my-skill-name/SKILL.md

If you want session logs — a record of what the skill-creator reasoned through and why the draft is structured the way it is — request them in the initial prompt as well. Asking for a log after the draft is already produced means the reasoning is reconstructed, not captured. If you need it for debugging later, request it at the start:

Log the key decisions made during skill creation to: /path/to/skills/my-skill-name/session-log.md
Include: why each section was written the way it was, any tradeoffs made on leanness vs. specificity,
and what the quality gate is checking for.

Once the first draft arrives, review it against three questions before iterating. Does it describe what matters — judgment calls, quality bar, output format — or does it describe procedure? Is it shorter than a page? If it is longer, find what it is spending words on that Claude does not need and identify the specific section. Does the quality gate match what you actually need to validate, not what is generically safe to check?

If the draft misses on one of these: one targeted prompt to fix the specific issue. Not a rewrite request — a targeted correction. "The quality gate checks format only — add a check that confirms the output file was written to the correct path." is a useful prompt. "Make it better" is not. Targeted prompts produce targeted changes. Vague prompts produce rewrites that fix the thing you mentioned and break the things you did not.

Validating the Draft

Before packaging, run the skill once against a representative input. Not a constructed perfect case — an input that resembles what the skill will actually encounter in practice. The goal is to surface variance before it reaches production.

Review the output against the quality gate in the skill. Format first: does it match the specification exactly? Then judgment calls: did Claude make the decisions the skill was written to drive, or did it reason around them? Then logging: does the log contain what you specified, in a format you can actually read?

If the output drifts in one specific area, add specification at that point. If it drifts in multiple areas, the brief was underspecified — revise the brief, revise the skill against the revised brief, run again. A skill that required three broad revision passes to stabilize usually means the brief did not define success precisely enough. The skill is a symptom; the brief is the diagnosis.

One failure mode specific to this environment: the file-not-deletable constraint means there is no cleanup step. If the skill produces an output to the wrong path, the correct-path output and the wrong-path output both persist. Validate the output path in the quality gate. If the path is wrong on the first run and you correct it on the second run, you now have two output files and the downstream system may read either. Name the output path explicitly in the skill's quality gate checklist so Claude confirms it before declaring the run complete.

Packaging and Deploying

A plain SKILL.md file does not trigger the copy-to-skills button in Cowork. The .skill extension is what activates it — and that requires the file to be a zip archive containing the skill directory.

Package from the parent directory of the skill folder:

cd /path/to/skills
zip -r my-skill-name.skill my-skill-name/

The archive must contain the folder, not just the SKILL.md file directly. zip -r my-skill-name.skill SKILL.md will produce a .skill file that does not install correctly. The directory wrapper is required.

Once the .skill file exists, present it via the mcp__cowork__present_files tool. The Cowork interface will render it with a "Copy to your skills" button. The install copies the skill directory to the user's skills folder without requiring manual file management.

After installation, test the skill from a fresh session — not the session it was created in. The fresh session test catches load issues that do not appear when session context from the skill-creation run is still in memory. If the skill loads and executes correctly on the fresh session test, it is ready for production use.

Commands Reference

# Initial skill-creator prompt structure
# (Provide brief first, then append these lines)

Make the skill lean enough to execute reliably without losing the judgment call context.
Prefer a brief over a procedure. The SKILL.md should describe the problem space, the
output requirements, and the decisions that matter — not the sequence of steps.

Write the SKILL.md to: /path/to/skills/my-skill-name/SKILL.md

# Optional: request session log
Log the key decisions made during skill creation to: /path/to/skills/my-skill-name/session-log.md
Include: why each section was written the way it was, any tradeoffs made on leanness
vs. specificity, and what the quality gate is checking for.

# Targeted iteration prompt structure
# (Use for single-issue corrections — not rewrites)

"[Specific section] is [specific problem]. Fix: [specific requirement]."

# Examples:
# "The quality gate checks format only — add a check that the output file was written to the correct path."
# "The brief section describes procedure not judgment — rewrite it to describe what matters, not what to do."

# Create skill directory structure
mkdir -p /path/to/skills/my-skill-name

# Package as .skill archive (run from parent directory of skill folder)
cd /path/to/skills
zip -r my-skill-name.skill my-skill-name/

# Verify archive contents before presenting
unzip -l my-skill-name.skill