You fixed it. And now nothing works.
This is the Builder's most common disaster. You have a Skill that's been running fine for months. You decide to improve it — add a new fact, fix a typo, change how it greets people. Three other Skills depend on this one. The next day they all break, and you can't remember what you changed.
Editing in place
You open my-dog-buddy.skill.yaml and edit one fact.
The file name is the same. The version is the same. Nothing tracks what changed.
Two weeks later, something breaks. You have no idea why.
Bumping + changelog
You bump the version from v1.2.0 to v1.2.1.
You add one line to the changelog: "fixed a typo in Buddy's treat name."
Two weeks later, you know exactly what changed, when, and why.
Every Skill that you keep using for more than a month needs a version. Not because versioning is "professional" — because future-you is a different person who won't remember your decisions. A version is a note you leave for that stranger.
Every version has exactly three numbers.
Professional software has used this pattern for decades. It's called semantic versioning, and once you see it, you can't unsee it. Three numbers, separated by dots:
MAJOR
Changes when things break.
MINOR
Changes when you add something.
PATCH
Changes when you fix something.
The clever part: the position of the number tells you how worried other people should be about your change. A bump in the third number (patch) is safe. A bump in the first (major) means stop everything and read the changelog before you upgrade.
Every change you make is one of three kinds.
Before you bump a version, you have to know which number to bump. Here are the three kinds, from least scary to most scary.
Fix it quietly
You fixed a typo, corrected a wrong fact, or adjusted wording. Nothing new exists that wasn't there before. Nothing old is gone.
Add something new
You added a new fact, a new personality trait, a new voice profile. Everything that used to work still works. There's just more now.
Break something
You removed a fact, changed what when_to_use means, or renamed the file. Things that used to work might not.
Ask yourself: "If someone upgrades blindly without reading, will anything break?" If yes, it's MAJOR. If no, but there's something new: MINOR. If no and there's nothing new, just a fix: PATCH. That's the whole decision tree.
This is what a versioned Skill looks like.
Same Skill as Sprouts Module 01, but with two new fields and a changelog. Notice how readable the history is — you can scroll through it and understand exactly how the Skill evolved.
# A Skill about my dog Buddy # Current version: v1.2.1 — see changelog below name: "My Dog Buddy" version: "1.2.1" created: "2025-11-03" updated: "2026-03-28" description: "Everything Claude needs to know about my golden retriever" facts: - "Buddy is a 3-year-old golden retriever" - "He only answers to his name in a higher pitch" - "He loves peanut butter cookies from the farmers market" - "He has a small scar on his left ear" - "He only barks at one specific neighbor" personality: "Proud of his scar, suspicious of normal treats" when_to_use: "Any time the user asks about Buddy" # ============================================================ # CHANGELOG — most recent changes first # ============================================================ changelog: - version: "1.2.1" date: "2026-03-28" kind: patch summary: "Fixed the treat name — it's 'peanut butter cookies', not 'PB cookies'" why: "My mom corrected me. She's been buying them longer than I've been alive." - version: "1.2.0" date: "2026-02-15" kind: minor summary: "Added the ear-scar fact and the neighbor-barking fact" why: "I noticed these were both things a stranger would never guess. Makes the Skill feel more like Buddy." - version: "1.1.0" date: "2026-01-08" kind: minor summary: "Added the 'higher pitch' fact about how he responds to his name" why: "Grandma came over and couldn't get his attention until I showed her the pitch trick." - version: "1.0.0" date: "2025-11-03" kind: initial summary: "First version. Three facts."
Notice the why field.
It's optional — but without it, in six months you'll look at the changelog
and wonder why past-you made that change. The why is the most
valuable part.
Write a changelog entry for a real change.
Pick any Skill you've made. Think of something you'd change about it. Fill in the form — the YAML builds itself as you type.
# Fill in the form above and watch this update. changelog: - version: ... kind: ... summary: ...
The form shows just the new entry you'd add to your existing changelog. In practice you'd paste this at the top of the changelog list.
Breaking or not breaking?
Now the hardest part of versioning. For each change, decide which number to bump. The trick is asking: could this surprise someone who's already using my Skill?
Round 1. You add a new fact to your Buddy Skill: "Buddy is afraid of thunderstorms." What version bump?
Round 2. You rename your Skill from "my-dog-buddy" to "buddy-the-golden". What version bump?
MAJOR isn't about how big the change feels to you. It's about whether something else in the world will have to change to keep working. A tiny rename can be MAJOR. A huge pile of new facts can be MINOR. The only question is: will anything break?
You just learned versioning.
This is one of the oldest, quietest, most important patterns in all of software engineering. You now know something most adults don't.
The first big change to how you think about your own work.
What you just learned
- Editing a Skill in place without tracking the change is a time bomb.
- Every version has three numbers: MAJOR.MINOR.PATCH.
- PATCH = fix. MINOR = add. MAJOR = break.
- The simple test: "If someone upgrades blindly, will anything break?"
- The why field in a changelog is the most valuable part — future-you won't remember.
- A rename is always MAJOR, no matter how small it feels.
In Module 03, the theme gets darker — and more interesting. You'll learn how to teach a Skill what it should refuse to answer. Constraints, limits, and the quiet art of saying no.
★ Before you call it done
Three questions. Same three. Every time.
These are the same three questions for every module in Kindling. They are how you check whether AI did the part it should and you did the part only you could. Tap each one to mark it true.
★ ★ ★