Using Claude to Write a Claude Skill, Start to Finish
The first time you try to get Claude to write a skill, you describe what you want, receive a file that looks completely correct, drop it into your skills folder, and discover two sessions later that it doesn't do what you thought it did. Not dramatically — nothing breaks. The output just quietly misses something you needed. You assumed the skill had encoded a constraint you mentioned in conversation. It hadn't. The skill file looked thorough. The trigger conditions were reasonable. The quality checks sounded right. None of it reflected the specific thing that matters in your workflow.
The gap is the missing step between describing what you want and actually specifying it. This post documents the workflow that closes it — how to go from raw idea to a tested, reliable skill file using Claude as the author, not just the executor.
Before You Open a Session: Writing Down What the Skill Actually Needs
The single most reliable way to get a useful first draft from Claude is to spend five minutes writing requirements before you prompt it. Not a formal spec — just a plain-text list that answers four questions: What does this skill need to produce? When should it fire and when shouldn't it? What does good output look like? What are the constraints or gotchas specific to this workflow?
The answers don't need to be polished. They need to exist. Without them, Claude infers your requirements from your description of the task, and it will produce plausible defaults — trigger conditions that are generically reasonable, quality checks that sound thorough, output instructions that seem complete. What it won't produce are the specific constraints that come from knowing your workflow: the output format required by the next step, the edge case you've already hit, the thing that looks optional but isn't. Those only exist in your head. Writing them down before the session is how they get into the skill.
A requirements note before building a skill for enriching content ideas might look like:
Output: enriched idea file in ./pipeline/ with all six enrichment fields populated
Trigger: when a raw idea file is in ./ideas/ and needs processing before writing
Quality: Pain field must describe a specific friction moment, not a topic summary
Quality: confidence signals (sourced/inferred/missing) must be honest — don't promote inferred to sourced
Constraint: never overwrite or edit original notes — append enrichment section only
Constraint: move processed files to ./pipeline/ — do not leave in ./ideas/
Gotcha: file cannot be deleted — edit in place or create new file, never removeThat's it. Nothing elaborate. The detail that matters is specificity: not "check the output quality" but "Pain field must describe a specific friction moment, not a topic summary." Claude can encode specific criteria. It cannot infer them.
The Opening Prompt: How to Frame the Skill Request
Once you have requirements written down, the opening prompt has a consistent structure. Name the skill, describe what it does in plain terms, paste your requirements directly, and specify the output format. The skill-creator skill in Claude Cowork is designed to receive this input and produce the SKILL.md — invoke it explicitly if you want it to handle the structural scaffolding.
A prompt that works:
I need a skill file for an idea enrichment workflow.
The skill should: read raw idea files from ./ideas/, enrich each one
with structured analysis (Pain, Decision Tension, Pattern, Technical Scope,
Reader Profile, Angle Candidates), and move completed files to ./pipeline/.
Requirements:
[paste your requirements list here]
Please produce a complete SKILL.md using the skill-creator skill.
The file should include: frontmatter with name and description, full
instructions, trigger conditions, quality checks, and a run checklist.
Make it lean enough to follow clearly but specific enough that the
quality checks are unambiguous.That last sentence — "lean enough to follow clearly but specific enough that the quality checks are unambiguous" — is worth including verbatim. It names the tradeoff you want Claude to navigate. Without it, Claude defaults toward thorough, which means verbose, which means the skill file accumulates language that sounds good but doesn't add constraint.
Ask Claude to save the file to ./skills/ or a staging path rather than directly to your active skills folder. You want to review it before it runs.
Reading the Draft: Where to Look Closely
When the draft comes back, the natural instinct is to read it top to bottom and check whether it sounds right. That's the wrong review method. A skill file that sounds right is not the same as one that will produce consistent outputs.
Read it in this order instead. Start with the trigger conditions. Ask whether they're specific enough to fire on what you want and narrow enough to not fire on what you don't. Generic triggers like "when working with documents" or "when the user asks about content" will activate the skill in situations that weren't intended. A good trigger names the specific context: "when a raw idea file is present in ./ideas/ and needs enrichment before entering the pipeline."
Then read the quality checks. For each one, ask: if Claude followed this check as written, would it catch the failure mode it's meant to catch? "Confirm output is complete" doesn't catch anything — Claude always confirms its output is complete. "Pain field describes a specific friction moment — not a topic summary" catches something. The difference is whether the check has a criterion Claude can actually evaluate against.
Finally, look for instructions that assume context you haven't provided. If a step refers to a path, format, or downstream requirement that isn't described anywhere in the skill file, Claude will improvise when it hits that step. Improvisation in a skill produces plausible outputs rather than correct ones. Any time you see "as appropriate" or "as needed" in the instructions, ask whether the skill file defines what appropriate or needed means in this context.
Iteration: Targeted Edits Without Losing Ground
The no-delete constraint means you're editing the file in place rather than starting fresh. This is actually the right approach — you're making targeted changes to a draft, not rebuilding from scratch. Use the Edit tool to make specific corrections rather than asking Claude to rewrite the whole skill, which will cause it to re-infer structure you've already validated.
When you find something to fix, be specific about what and why:
The trigger condition on line 12 is too broad — it will fire whenever
the user mentions ideas, not just when a file is ready for processing.
Change it to: "Trigger when a raw idea file is present in ./ideas/ and
the user wants to run enrichment or process the queue."
Also, the Pain quality check on line 34 says "confirm Pain is populated."
That's too weak — replace it with: "Pain describes a specific friction
moment — not a topic summary. If Pain reads as a category description,
it fails this check."Two changes, both specific, both with the exact replacement text. If you say "make the trigger conditions more specific" without stating what specific means here, Claude will produce something that's different from what you had but not necessarily better. Give it the criterion, not the judgment call.
Keep the original file intact if you're uncertain about a change. Create a v2 version alongside it rather than editing the only copy you have. The inability to delete means previous versions accumulate, but that's preferable to losing a working baseline while iterating toward something better.
Validation: The Traced Run and the Live Test
Before the skill runs in a real session, walk through it manually once. Take an input you know well, read through the skill instructions as if you were the model, and check whether following those instructions produces the output you'd expect. This doesn't require running anything — it requires reading your own skill file carefully and asking whether someone who didn't write it could follow it to the correct conclusion.
What you're looking for is ambiguity that only surfaces when you're actually following the instructions rather than reading them. "Process the file and populate all enrichment fields" reads fine in review. When you follow it with a specific input, you discover the skill doesn't define what to do when a field can't be populated from the notes alone — whether to leave it empty, flag it, or research externally. That decision needs to be in the skill file.
After the traced run, run it once in a live session against a real input. Evaluate the output against what you actually needed, not against what looks like a good output in the abstract. If the skill produces something that's structurally correct but misses the workflow-specific requirements you wrote down in step one, the gap is in the instructions. Go back to those requirements and find what didn't make it into the skill.
One live test on a representative input is enough to proceed for personal homelab use. The skill will surface additional gaps as it encounters variation — that's normal, and iterating on real outputs is a reasonable way to tighten a skill over time. If the skill is going to run unsupervised or be used by others, run it against two or three meaningfully different inputs before trusting it. A skill that performs well on the input it was designed for and inconsistently on everything else isn't finished.
Getting the File Into Your Skills Folder
Once the skill passes validation, move it to your active skills folder. In Claude Cowork, the skill-creator skill is designed to produce a .skill file that can be copied directly into your skills directory — look for the "Copy to your skills" option in the file card it presents when the skill is complete.
If the file was written to a staging path, copy it manually to ./skills/ and verify it appears in the available skills list in your next session. Rename the staging file with a reviewed- prefix rather than deleting it — it's the last known good state before the active version, and having it available if something goes wrong in the first few real runs is worth the storage.
Commands Reference
Requirements framing (before the session)
Output: [what the skill produces]
Trigger: [when it should fire / when it shouldn't]
Quality: [specific, testable criteria for good output]
Quality: [add as many as the workflow requires]
Constraint: [workflow-specific constraints]
Gotcha: [known failure modes or non-obvious requirements]Opening prompt structure
I need a skill file for [workflow name].
The skill should: [plain-language description of what it does]
Requirements:
[paste requirements list]
Please produce a complete SKILL.md using the skill-creator skill.
The file should include: frontmatter with name and description, full
instructions, trigger conditions, quality checks, and a run checklist.
Make it lean enough to follow clearly but specific enough that the
quality checks are unambiguous.Targeted edit prompt structure
[Identify the specific line or section]
[Name what's wrong with it]
[Provide the exact replacement text]
Example:
The trigger condition on line [N] is too broad — it will fire on
[unintended case]. Change it to: "[exact new trigger text]"Validation checklist (manual trace)
1. Take a representative input
2. Follow skill instructions as written, step by step
3. At each decision point: is the criterion explicit or inferred?
4. At each output step: is the format/path/naming defined?
5. At each quality check: does the criterion catch the failure mode it targets?
6. Note every step where you improvised — those need explicit instructionsPost-validation file management
# Stage skill file to active skills folder
cp ./staging/skill-name/SKILL.md ./.skills/skills/skill-name/SKILL.md
# Preserve staging version with reviewed prefix (no deletion)
# Rename staging file to: reviewed-YYYY-MM-DD-skill-name.md