Draft, Publish, Version: Best Practices for Building Agent Skills That Last

Key Facts

• A draft skill already works in Claude. You don't have to publish to try it — connect your library, and the draft runs in real conversations while you refine it.
• Publishing is the "I'm satisfied" step, not a switch that turns the skill on. It freezes the current version into an immutable, stable one and makes it the shared version your team and agents rely on.
• Because published versions are frozen, editing a published skill opens a new draft automatically — you can't break the live version by experimenting.
• Drafts are unlimited on every plan; only distinct published skills count toward plan limits.
• Every publish adds to version history, so you can compare any two versions and restore an earlier one without overwriting anything.

Most people build a skill the hard way: write the whole SKILL.md, publish it, discover it doesn't trigger the way they expected, edit, publish again, repeat. There's a better loop, and it starts from one fact many builders miss — a draft skill is already usable in Claude. That changes the whole workflow. You don't perfect a skill and then publish it; you draft it, use it live, refine it against real conversations, and publish only when it's genuinely good. This guide is that workflow, plus the habits that keep skills durable as they evolve.

Table of Contents

1. The three states, and why they matter
2. Draft: your live workshop
3. Publish: freeze the version you trust
4. Version: evolve without fear
5. Best practices for each stage
6. Related entities
7. Frequently asked questions
8. Key takeaways

The Three States, and Why They Matter

A skill moves through a simple lifecycle: Draft → Published → (later) new Draft → Published again, each publish landing in version history. The status badge in the editor always shows where you are.

The mental model that trips people up is thinking "published = on." It isn't. The right model:

• Draft = the working copy. Editable, and — this is the key — runnable in Claude right now.
• Published = a frozen snapshot you've blessed as the stable, shareable version. Immutable, so it's trustworthy.

Once you internalize that a draft is already live to you, the workflow inverts in your favor: you test before you commit, not after.

Draft: Your Live Workshop

Every skill starts as a draft, and every edit happens in one. Drafts are unlimited on every plan, so there's no cost to experimenting — write as many skills and as many revisions as you like.

The best practice here is to use the draft in Claude while you build it. Once your library is connected to Claude, your draft skill loads into real conversations. So the loop looks like:

1. Write a first pass of the SKILL.md — rough is fine.
2. Go to Claude and try the actual task the skill is for. Does the skill trigger? Does it do the right thing?
3. Watch where it falls short — wrong trigger, missing step, too verbose — and edit the draft.
4. Try again. Repeat until it behaves.

This is the single highest-leverage habit in skill building. A skill's quality is almost entirely about how it behaves in a live conversation, and you can only see that by running it. Drafting in a vacuum and publishing hopefully is how you end up with the "why won't my skill trigger?" problem — you're debugging after committing instead of before.

Publish: Freeze the Version You Trust

When the draft consistently does what you want, publish it. Publishing does two things at once:

• Freezes the version. A published version is immutable — it can never be silently edited. That's what makes version history trustworthy: every published version is exactly what ran.
• Makes it the version your team relies on. Publishing marks the stable, blessed version — the one you'd want teammates and agents standing on, rather than a half-finished edit.

Publishing is a decision, and treating it that way is the point. It's you saying "this one is good; make it the reference." Because the version freezes, you get an honest record of what you actually shipped, not a mutable blob that drifted.

Two things worth knowing:

• Editing a published skill opens a new draft automatically. The published version keeps running untouched while you work in the new draft — you literally cannot break the live version by experimenting. Publish again when the new draft is ready.
• Published does not mean public. Publishing changes which version is the stable one, never who can see the skill. Your published skills are exactly as private as your drafts — visibility is a separate, deliberate sharing decision.

Version: Evolve Without Fear

Skills are living assets — they get better as you learn what works. Every time you publish, that version lands in version history: a day-grouped timeline with real author names, per-version notes, and a side-by-side diff of what changed.

Two habits make versioning pay off:

• Diff before you publish. Compare your working draft against the current live version so you know exactly what you're about to change. No surprises for the teammates who depend on it.
• Annotate as you go. Add a note to a version while it's still a draft explaining why you changed it — publishing freezes the note in with the version, so the reasoning travels with the record permanently. Six months later, "who changed the screening threshold, and why?" has an answer.

And if a change turns out wrong, restore brings an earlier version's content back into a fresh draft — nothing is overwritten. Your team keeps using the current published version until you review the restored content and publish it deliberately. The safety net means you can evolve aggressively.

Best Practices for Each Stage

While drafting

• Use the draft in Claude from the very first pass — test behavior, don't imagine it.
• Keep the SKILL.md focused: one skill, one job. Reliable triggering comes from a clear, specific description of what the skill does and when to use it.
• Push detail into reference files rather than bloating the main instructions — load the specifics on demand.

Before publishing

• Diff the draft against the live version so you know precisely what's changing.
• Confirm the skill triggers on the words people actually say, not just the phrasing you had in mind.
• Write the version note now — while it's still a draft — so the "why" is captured.

After publishing

• Decide visibility separately: keep it private, share it with the workspace, or share it use-only if it's IP you want run but not read.
• Let updates flow — edit in the auto-created draft, test in Claude, publish again. The live version never wobbles in between.

Related Entities

This workflow lives in Agentman's Agent Skills platform: the open SKILL.md format popularized as Claude Skills, and the lifecycle around it — drafts (unlimited, runnable in Claude), publishing (freeze + bless a stable version), and version history (compare, annotate, restore). It connects to the practical guides for creating your first skill, connecting your library to Claude, and the publish/deprecate/archive lifecycle.

Frequently Asked Questions

Can I use a skill in Claude before I publish it?

Yes. A draft skill is already usable in Claude once your library is connected — that's the whole point of the draft-first workflow. You test the skill in real conversations, refine it, and publish only when you're satisfied. Publishing isn't what makes a skill work; it's what freezes a version as the stable, shareable one.

What does publishing actually do, then?

Two things: it freezes the current version so it's immutable (which is what makes version history trustworthy), and it marks that version as the stable one your teammates and agents should rely on. It does not change who can see the skill — visibility is a separate sharing decision.

Will I run out of published-skill slots while experimenting?

No. Drafts are unlimited on every plan, and re-publishing a new version of an already-published skill doesn't use another slot — only distinct published skills count. Experiment freely.

What happens if I edit a skill that's already published?

Editing a published skill automatically opens a new draft, and the published version keeps running untouched until you publish again. You can't break the live version by experimenting — and you can diff the new draft against the live one before you commit.

Key Takeaways

• A draft skill already works in Claude — build with it live, testing behavior in real conversations instead of imagining it.
• Publish when you're satisfied. Publishing freezes an immutable, stable version and blesses it as the one your team relies on — it isn't an on/off switch.
• Editing a published skill opens a new draft automatically, so the live version never breaks while you iterate.
• Version deliberately: diff before publishing, annotate the "why" while it's still a draft, and restore fearlessly — nothing is ever overwritten.
• Drafts are unlimited; only distinct published skills count toward plan limits — so there's no cost to a workshop-heavy workflow.

Build your next skill draft-first. Create a skill, connect your library to Claude, and try it live before you publish. When it's good, publish it — and you'll have a version history to prove exactly how it got there.