Skills are not static artifacts. They draft, promote, rename, merge, and die. Treating them as living things — with an expected lifespan and lifecycle — means you actively maintain a portfolio rather than letting it rot in place.
This lesson maps the lifecycle stages, shows you seven real evolution traces from a production skill portfolio, and gives you the decision framework to know when a skill should move to the next stage.
The Lifecycle Stages
Draft In-progress
A skill that exists but hasn't proven itself. Maybe it's half-written, maybe it works but hasn't been invoked enough to validate its shape. Drafts are experimental — they have permission to be messy.
Promote Earning its place
The skill has been used in real work, its scope is clear, and its name fits. Promotion means it's graduated from experiment to tool — worthy of maintenance investment and the context/cognitive load it imposes.
Rename / Reframe The name stopped fitting
The skill's concept solidified but its name didn't keep up. Or the framing shifted — what started as a verb ("review") became a discipline ("code-review"). Renaming is a signal of maturity, not instability.
Merge Consolidation
Multiple skills that overlap get folded into fewer, stronger ones. The merged skill covers more surface with less maintenance cost and less cognitive/context load. Three weak skills become two strong ones.
Deprecate / Remove Deliberate death
The skill didn't earn its place, or its purpose was absorbed by another skill, or the workflow it served no longer exists. Removal is active maintenance, not neglect.
Seven Real Lifecycle Traces
These are real evolutions from a production skill portfolio. Each trace shows a skill moving through one or more lifecycle stages:
1. decision-mapping → wayfinding → wayfinder
Draft → Rename → Rename → Promote
Three names, two bucket moves, full reframe. Started as "decision-mapping" (too narrow — it wasn't just about decisions). Renamed to "wayfinding" (better metaphor, broader scope). Then to "wayfinder" (noun form, consistent with agent naming convention). Each rename reflected a deepening understanding of what the skill actually did.
2. review → code-review
Draft → Rename → Promote
Straightforward promotion. "review" was too generic — could mean document review, PR review, design review. "code-review" scoped it precisely. The skill's content didn't change much; the name caught up with reality.
3. diagnose → diagnosing-bugs
Draft → Rename → Promote
Same-bucket rename for clarity. "diagnose" was ambiguous (diagnose what?). "diagnosing-bugs" made the trigger obvious. Later simplified back to "diagnose" once its description made the scope clear — proving that names can simplify once the description does the heavy lifting.
Three overlapping skills consolidated into two. "to-prd" and "to-plan" had blurry boundaries — both produced planning documents. Merged into "to-spec" (one output format). "to-issues" became "to-tickets" (clearer name). Net: less maintenance, less confusion about which to invoke.
5. write-a-skill → writing-great-skills
Draft → Promote → Reframe
Thin how-to became a full reference glossary. "write-a-skill" was a simple scaffolding helper. Over time it accumulated vocabulary definitions, quality criteria, and anti-patterns until it outgrew the how-to format. Reframed as "writing-great-skills" — now a reference dependency that other skills point to, not just a one-off generator.
6. teach
Draft → Move → Move → Promote
Bounced between buckets twice before settling. Started in "productivity", moved to "meta", moved to "learning", finally settled back in its own category. The wandering reflected genuine uncertainty about what kind of skill it was — a productivity tool? A meta-skill? It was neither; it was a pedagogical mode.
7. caveman & zoom-out
Draft → Kill
Tried and deliberately cut. "caveman" was an experiment in ultra-simplified communication. "zoom-out" provided broader context on unfamiliar code. Both were used a few times, never became habitual, and their value didn't justify the cognitive/context load. Killed — not because they were bad ideas, but because they didn't earn their place.
Pattern recognition
Notice that most skills rename at least once. This is normal and healthy — it means you're learning what the skill actually does through use, not through upfront design. Resist the urge to get the name "right" on the first try.
The Decision Framework
Promotion Criteria
A skill earns promotion when all three hold:
Proven in use — you've invoked it in real work at least 3-5 times and it produced the expected result
Clear scope — you can state what it does in one sentence without hedging ("it kind of...")
Named well — someone seeing the name in a list can guess what it does without reading the description
Rename Signals
A skill needs renaming when:
You find yourself explaining what it actually does because the name misleads
The name violates a convention you've since adopted (verb-first, noun-form, etc.)
A better metaphor emerged through usage ("decision-mapping" → "wayfinder")
The scope shifted but the name stayed — the name describes the old version
Merge Triggers
Multiple skills should merge when:
You hesitate about which one to invoke — the boundary between them is unclear
They share 50%+ of their workflow steps
One is a strict subset of the other
Maintaining both costs more than maintaining one that covers both
Kill Signals
A skill should die when:
You haven't invoked it in 60+ days and don't miss it
Its purpose was absorbed by another skill or by the base model improving
It never graduated from draft — after a month of existence, it's still not invoked
The workflow it served no longer exists in your daily practice
The Courage to Kill
Removing a skill feels like losing capability. It's not. It's reclaiming attention. Every skill in your portfolio imposes cost — either context load (model-invoked) or cognitive load (user-invoked). A skill that exists but never fires is paying rent for an empty room.
The deletion reframe
Before: "I might need this someday."
After: "If I need this again, I can recreate it in 10 minutes.
Meanwhile, it's costing me attention every day it exists."
Skills are cheap to recreate and expensive to maintain. The bias should be toward killing, not keeping. A lean portfolio of 20 sharp skills outperforms a bloated portfolio of 40 where half are stale.
Check Your Understanding
You have a skill called "plan" that you always have to explain: "No, not project planning — it generates implementation plans from specs." What lifecycle action does this need?
Kill — delete it and fold into another skill
Merge — combine with the spec-writing skill
Rename — the name misleads; it needs a more specific name
Promote — just improve the description
Correct. If you're explaining what a skill "actually" does because the name misleads, that's a rename signal. "plan" is too generic. Something like "impl-plan" or "spec-to-plan" would eliminate the confusion.
This is a rename signal. The skill works fine — you just have to explain it every time because "plan" is too ambiguous. The cure is a more specific name, not deletion or merging.
You have three skills: "to-prd", "to-plan", and "to-spec". When deciding which to invoke, you frequently hesitate between to-prd and to-plan because both produce planning documents. What's the right lifecycle action?
Rename all three to be more distinct
Kill to-plan since it's the newest
Merge to-prd and to-plan into one skill with a clear name
Keep all three but improve their descriptions
Correct. Hesitation about which to invoke is the primary merge trigger. If the boundary between two skills is unclear to you (the author), it's invisible to the model. Merge them. Better descriptions can't fix a fundamentally blurry scope boundary.
When you hesitate about which skill to use, the boundary between them is too blurry. Better descriptions won't fix this — the skills genuinely overlap. Merge them into one that covers both use cases. That's what happened with to-prd + to-plan → to-spec.
A skill has existed for 45 days. You've invoked it once (it worked), but you haven't reached for it since. What does the lifecycle framework say?
Promote it — it worked when invoked
It's approaching the kill threshold — if it doesn't get invoked in the next 15 days, it hasn't earned its place
Rename it — maybe the name isn't triggering you to use it
Keep it as a draft indefinitely — one invocation means it has value
Correct. The kill signal is 60+ days without invocation. At 45 days with only one use, it's approaching the threshold. One successful invocation doesn't prove ongoing value — it proves the skill can work, but not that it earns its ongoing maintenance and attention costs.
The kill threshold is 60+ days without meaningful use. At 45 days with a single invocation, this skill is on notice. Working once doesn't mean it earns its ongoing costs. If you don't miss it, it's not pulling weight. Skills that "might be useful someday" are paying rent on an empty room.
Your Exercise
List 5 of your skills (pick a mix of frequently-used and rarely-used).
For each, identify its current lifecycle stage: Draft, Promoted, needs Rename, merge candidate, or kill candidate.
For any in Draft: do they meet all three promotion criteria? If not, what's missing?
For any rarely-used: when did you last invoke them? Are they approaching the 60-day kill threshold?
Identify one merge opportunity and one kill candidate. Act on at least one of them.
📖 Primary Source
trail-map.html — Skill Lifecycles view — The full evolution history of a production skill portfolio showing every rename, merge, and removal with dates and rationale.
Questions? Show me your skill list and I'll help you identify which are due for promotion, renaming, merging, or removal. Lifecycle decisions are easier with a second opinion.