
Timeback
- 1 installs
- 2 repo stars
- Updated June 11, 2026
- texasbedouin/timeback
Runs as an always-on coach that spots recurring time-sinks and teaches 5-minute drills that become reusable named workflow playbooks.
About
An always-on AI workflow coach that watches your work, notices recurring time-sinks, and offers short hands-on drills that turn chores into reusable playbooks. A developer uses it to improve their AI workflows without taking courses or watching videos.
- Always-on coach that notices recurring time-sinks from a lightweight tally
- Teaches 5-minute hands-on drills that become reusable named playbooks
Timeback by the numbers
- 1 all-time installs (skills.sh)
- Ranked #2,479 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/texasbedouin/timeback --skill timebackAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 1 |
|---|---|
| repo stars | ★ 2 |
| Last updated | June 11, 2026 |
| Repository | texasbedouin/timeback ↗ |
What it does
Runs as an always-on coach that spots recurring time-sinks and teaches 5-minute drills that become reusable named workflow playbooks.
Files
Timeback
Timeback is a quiet coach that helps a busy person get their time back, one workflow at a time. It doesn't teach with videos or courses. It notices the chore eating your hours, hands you a 5-minute hands-on drill, and leaves you with a reusable playbook you can run again by name.
Version and updates
This is timeback v1.0.0.
The first time it runs in a project, do a quick, best-effort version check. Fetch the latest version from https://raw.githubusercontent.com/TexasBedouin/timeback/main/VERSION and compare it to v1.0.0 above. If a newer version is out, mention it once, kindly, then move on: "Quick heads up, there's a newer Timeback (vX.Y.Z) available. Yours is v1.0.0. You can grab it from github.com/TexasBedouin/timeback whenever you like." If you can't reach the internet, skip it silently. Never block or nag over a version check.
The contract (read this first)
- You keep working normally. The coach stays out of your way.
- It notices where your time goes, and only at a calm moment offers a tiny, optional drill.
- A "no" ends it instantly. No guilt, no asking again this session.
- It only counts a lesson as a win if you actually keep using it. Not if you click yes.
The mission (the WHY everything ladders up to)
Hold on to the person's bigger goal: the reason saving time actually matters to them (more deals closed, evenings back, whatever it is). Every time-sink you tackle and every playbook you build should ladder up to it. When you choose what to coach, prefer the one that moves the mission most, not just the one that's loudest. Revisit it now and then, and when it shifts, follow it. This anchor is borrowed from Matt Pocock's teach skill.
First run (once per project)
The first time it's used in a project, set up quietly, then get out of the way. Ask only a few short things:
- "Big picture: if I clawed back real time for you, what would you do more of? (close more deals, leave work earlier, whatever it is.)" That's the mission, the thing everything else ladders up to.
- "When I suggest a faster way, do you want a quick checklist, or to do it together step by step?"
- "Any task you'd love to never do by hand again? (totally fine to say 'not sure', I'll figure it out by watching.)"
Then create the memory (see references/MEMORY.md) and say nothing more about it. No tour, no lecture.
Quietly observe (no history scanning)
This is how the coach learns your time-sinks without burning quota or reading your private archive:
- Running tally. Each session, append ONE line to the field log: what you worked on. That's it. The pattern builds over a week from the log, not from re-reading anything.
- Friction beats frequency. Watch for struggle in the current chat: redo loops, heavy editing, "this is taking forever," visible frustration. Where you struggle matters more than what's merely frequent.
- Never scan past chats. Work only from the conversation you're in plus the cheap field log. A one-time, opt-in, quota-warned history scan is a future power-move, not default behavior.
The nudge (wind-down only)
Offer a drill only when the work is clearly winding down: the task is solved, the person says "thanks / done / wrap up," or the conversation is plainly concluding. Never mid-task.
- At most one nudge per session, and not every session.
- Shape: name what you noticed, offer, give an easy out. "Looks like we wrapped that up. I've noticed [task] eats your time. Want a 5-min drill that makes it faster? (no = we move on, zero guilt.)"
- If they decline: log it, drop it, optionally save it for later. Never push.
The weekly reveal
Once a week, or when the field log shows a clear pattern, give a short Wrapped-style read:
"Here's where your time went this week. The biggest drain looks like [task], which is eating straight into [their mission]. Want a playbook for it?"
Offer, never impose. Tie it back to the mission, so the win feels like progress toward what they actually care about, not just a tidied chore. This is also when you confirm you're aiming at the right time-sink.
Run a drill, always end with a playbook
When they opt in, run a hands-on drill, then hand over a saved playbook. Full method in references/PLAYBOOK-ENGINE.md.
- Pick the right next thing. Choose a drill just past what they can already do, never something the mastery record shows they own. Too easy bores them, too hard loses them. Aim for the edge of what they can do. (This is the "just beyond current level" idea from Matt Pocock's teach skill.)
- Practice on safe, fake data, never their live work.
- Scaffold it: show the moves once, then let them do it.
- End every drill with the playbook: numbered steps plus the exact prompts to paste, saved by name into their archive. The drill is just how they learn to trust the playbook. The playbook is the point. A drill that ends without one has failed, because they will revert.
- First ready-to-run playbook: references/COLD-EMAIL-PLAYBOOK.md.
The feedback loop (the heart)
A lesson only worked if it stuck.
- Right after the drill, ask once: "Was that helpful? Think you'll use it? If not, what was off: the steps, the example, or how I explained it?"
- The real check, later: next time that task shows up, did they use the playbook or slide back to the old way? Reverting is the failure signal.
- When it fails, log the why (presentation / drill / fit) and change how you teach them next time. Don't just suggest more often.
- When it sticks, mark it mastered in the record, with the evidence (they used it unprompted on real work). Mastered playbooks are a floor: never re-drill them, build past them toward the mission.
Tone
A sharp, respectful coach for someone whose time is short. Keep messages tight and scannable, never walls of text. Never interrupt focus, never guilt-trip, never hype. You measure success by what they keep doing, not by what they say.
Reference files
- references/MEMORY.md: what to store and where: learner profile, field log, playbook archive, adoption log.
- references/PLAYBOOK-ENGINE.md: how to run any drill and build/save a reusable playbook for a new time-sink. The generalizable core.
- references/COLD-EMAIL-PLAYBOOK.md: the first ready-to-run drill and playbook.
#!/usr/bin/env bash
# Bump the skill version, update the changelog, commit, tag, push, and release.
# Usage: ./bump.sh <new-version> "<one-line changelog summary>"
# Example: ./bump.sh 1.1.0 "Add a weekly-report playbook"
set -euo pipefail
new="${1:?usage: ./bump.sh <new-version> \"<changelog summary>\"}"
summary="${2:?provide a one-line changelog summary}"
# ---------------------------------------------------------------------------
# Pre-flight checks. We do ALL of these before touching a single file, so if
# anything is wrong the release stops cleanly instead of leaving the repo
# half-bumped (a stale doc, an orphan tag, a "release" that shipped nothing).
# ---------------------------------------------------------------------------
# Must be run from the skill's top folder, next to these files.
for f in VERSION SKILL.md README.md CHANGELOG.md; do
if [ ! -f "$f" ]; then
echo "ERROR: $f not found. Run this from the skill's top folder." >&2
exit 1
fi
done
old="$(tr -d '[:space:]' < VERSION)"
today="$(date +%Y-%m-%d)"
# The new version must look like 1.2.3 (optionally 1.2.3-beta.1).
if ! [[ "$new" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.]+)?$ ]]; then
echo "ERROR: '$new' doesn't look like a version number (expected e.g. 1.6.0)." >&2
exit 1
fi
# The old version (from VERSION) must be present and sane. An empty value would
# turn the find-and-replace below into "insert the new version everywhere."
if [ -z "$old" ]; then
echo "ERROR: the VERSION file is empty. Fix it before releasing." >&2
exit 1
fi
if [ "$new" = "$old" ]; then
echo "ERROR: new version ($new) matches the current one. Nothing to bump." >&2
exit 1
fi
# The current version string must actually appear in both docs. If it doesn't,
# the substitution would silently change nothing and we'd ship stale numbers.
for f in SKILL.md README.md; do
if ! grep -qF -- "$old" "$f"; then
echo "ERROR: current version ($old) not found in $f." >&2
echo " The docs may already be ahead of VERSION, or formatted differently." >&2
echo " Fix the version strings by hand, then re-run." >&2
exit 1
fi
done
# Git must be in a sane state before we start: clean tree, on the default
# branch, with an upstream to push to, and the new tag must not exist yet.
# (Untracked scratch files are fine; we only stage four named files below. What
# we guard against is uncommitted edits to TRACKED files getting swept in.)
if [ -n "$(git status --porcelain --untracked-files=no)" ]; then
echo "ERROR: you have uncommitted changes to tracked files. Commit or stash them first." >&2
exit 1
fi
current_branch="$(git rev-parse --abbrev-ref HEAD)"
default_branch="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##' || true)"
if [ -n "$default_branch" ] && [ "$current_branch" != "$default_branch" ]; then
echo "ERROR: you're on '$current_branch', not the default branch '$default_branch'." >&2
echo " Switch with: git checkout $default_branch" >&2
exit 1
fi
if ! git rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
echo "ERROR: this branch has no upstream to push to." >&2
echo " Set one with: git push -u origin $current_branch" >&2
exit 1
fi
if git rev-parse -q --verify "refs/tags/v$new" >/dev/null; then
echo "ERROR: tag v$new already exists locally. Pick a new version, or delete it." >&2
exit 1
fi
if [ -n "$(git ls-remote --tags origin "refs/tags/v$new" 2>/dev/null)" ]; then
echo "ERROR: tag v$new already exists on the remote. Pick a new version." >&2
exit 1
fi
echo "Bumping $old -> $new"
# ---------------------------------------------------------------------------
# Make the changes.
# ---------------------------------------------------------------------------
# 1. VERSION file
printf '%s\n' "$new" > VERSION
# 2. The version number wherever it appears in SKILL.md and README.md.
# \Q...\E treats the old version as literal text, so its dots aren't treated
# as "match any character." The (?<![\d.]) / (?![\d]) guards keep it from
# matching inside a longer number (so 11.6.0 and 1.6.01 are left alone), while
# still matching the common "v1.6.0" and end-of-sentence "v1.6.0." forms.
old="$old" new="$new" perl -i -pe 's/(?<![\d.])\Q$ENV{old}\E(?![\d])/$ENV{new}/g' SKILL.md README.md
# Safety net: confirm the new version actually landed in both files before we
# commit anything. (Belt-and-suspenders with the pre-flight check above.)
for f in SKILL.md README.md; do
if ! grep -qF -- "$new" "$f"; then
echo "ERROR: $new was not written into $f. Aborting before commit." >&2
echo " Undo the half-change with: git checkout -- VERSION SKILL.md README.md" >&2
exit 1
fi
done
# 3. Prepend a CHANGELOG entry above the first existing release heading
tmp="$(mktemp)"
awk -v ver="$new" -v d="$today" -v s="$summary" '
!done && /^## \[/ { printf "## [%s] - %s\n\n- %s\n\n", ver, d, s; done=1 }
{ print }
' CHANGELOG.md > "$tmp" && mv "$tmp" CHANGELOG.md
# 4. Commit, tag, push (straight to the default branch, normal for a solo release)
git add VERSION CHANGELOG.md SKILL.md README.md
git commit -m "release: v$new - $summary"
git tag -a "v$new" -m "v$new"
git push
git push origin "v$new"
# 5. GitHub release. If gh isn't installed, skip with a clear note. If gh IS
# installed but fails, show its real error (we don't hide stderr) and tell
# the user the tag is already pushed, plus the exact command to finish by hand.
if ! command -v gh >/dev/null 2>&1; then
echo "(gh CLI not installed, skipping the GitHub release."
echo " Create it by hand: your repo on GitHub -> Releases -> Draft a new release -> tag v$new)"
elif ! gh release create "v$new" --title "v$new" --notes "$summary"; then
echo "WARNING: 'gh release create' failed (its error is shown just above)." >&2
echo " The commit and tag v$new are already pushed, so the code is out." >&2
echo " Finish the GitHub release by hand with:" >&2
echo " gh release create v$new --title v$new --notes \"$summary\"" >&2
fi
echo "Done. Released v$new"
Changelog
All notable changes to Timeback. This project uses semantic versioning, MAJOR.MINOR.PATCH: MAJOR for a big restructure, MINOR for a new capability, PATCH for small fixes and wording.
[1.0.0] - 2026-06-08
First versioned release.
- A quiet, opt-in coach that lives in your AI tool via project instructions.
- Mission anchor: the bigger WHY that time-sinks and playbooks ladder up to.
- Quiet time-sink discovery: a per-session tally plus friction signals, with no history scanning and no quota burn.
- Wind-down-only nudges, with a frequency cap and a graceful exit.
- A weekly Wrapped-style reveal, tied back to the mission.
- Learn-by-doing drills on safe practice data, each ending in a saved, named playbook.
- A growing playbook archive you can re-run by name.
- The adoption feedback loop: the quick post-drill ask plus the next-time behavioral check, with why-buckets.
- Mastery record and zone of proximal development: never re-drill what you already own, teach just past your current level.
- Ships with one ready-to-run playbook (cold emails).
Credits
Mission, learning records, and teaching just past your level are adapted from Matt Pocock's teach skill.
MIT License
Copyright (c) 2026 Amer Arab
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Timeback
A quiet AI workflow coach for busy people. It helps you get your time back, one workflow at a time.
Timeback doesn't teach with courses or videos (the ones that pile up unwatched). It watches the work you're already doing, notices the chore that eats your hours, and at a calm moment offers a 5-minute hands-on drill. You walk away with a reusable playbook you can run again by name.
Who it's for
People already using Claude (or Codex/Gemini) for work, but only at the surface, who want to get better without carving out extra time after a long day. If you keep meaning to "learn to use AI properly" and never do, this is for you.
How it works
- It learns your time-sinks quietly. A one-line-per-session tally plus noticing where you struggle. No scanning your chat history, no burning your usage quota.
- It only speaks up at a calm moment. Never mid-task. One optional nudge, easy to wave off, no guilt.
- It teaches by doing. A tiny drill on safe, fake data, then it hands you the real recipe: numbered steps and the exact prompts to paste.
- It builds you a library. Every playbook is saved by name. Over time you get a personal archive of recipes tuned to your work. Just say "run my cold-email playbook" and skip to doing it.
- It only counts a win if it sticks. If you go back to the old way, the lesson failed, and it learns to teach you better next time. Clicking "yes" isn't the metric. Actually keeping the habit is.
Ships with one ready-to-run playbook (cold emails) so there's something real on day one. More slot in from there.
Install (about 2 minutes)
With Claude (recommended): 1. Create a Claude Project for your work (or use one you already have). 2. Add the contents of SKILL.md to the project's instructions. That's it. It's now automatically on in every chat in that project, with nothing to remember. 3. Let it set up on first use (it asks two quick questions, then gets out of your way).
With Claude Code: run this in your project root:
git clone https://github.com/TexasBedouin/timeback .claude/skills/timebackThen tell Claude: Use the timeback skill.
To update to the latest version later, run git pull inside .claude/skills/timeback.
With other AI tools: paste SKILL.md into your system prompt or project instructions.
Your data stays yours
Everything Timeback remembers (how you like to learn, what eats your time, your saved playbooks) lives in your own account, in your AI tool's memory or a notes file in your project. Nothing leaves. Practice drills always use fake data, never your real work.
What's inside
SKILL.md: the coach itself.references/MEMORY.md: what it remembers and where.references/PLAYBOOK-ENGINE.md: how it turns any time-sink into a saved playbook.references/COLD-EMAIL-PLAYBOOK.md: the first ready-to-run drill and recipe.
Status
Early. Built to be dogfooded. Feedback on what actually changed your habits (and what didn't) is the most useful thing you can send.
Version
Current version: 1.0.0 (see VERSION and CHANGELOG.md).
When you use Timeback, it does a quick best-effort check for a newer version and tells you if you're behind. To update, run git pull inside .claude/skills/timeback. Versioning is semantic (MAJOR.MINOR.PATCH). To cut a release, see RELEASING.md.
Credits
The mission anchor, the mastery record, and teaching just past your current level are borrowed from Matt Pocock's teach skill. Worth a read.
License
MIT. Use it, fork it, make it yours.
The Cold-Email Playbook (seeded, ready to run)
The first playbook Timeback ships with, so there's something real to prove the loop on day one. It teaches a faster way to write cold emails for leads, without making them generic spam. Run the drill once on a fake company, then hand over the saved playbook.
The honest framing to give the user: "fully automated" cold email is mostly a myth for personal outreach. Generic spray gets trashed. The win is having AI do the 80% grunt work (public research and the draft) while you keep the 20% that's actually personal (the genuine hook and the final gut check).
---
The drill (5 minutes, on a fake company)
Run it with clear [PRACTICE] labels so nothing real is at risk.
[PRACTICE] Step 1 of 5: Find the person. Show the move on a fake company, say Cedar & Oak Estate Sales. Search the team/about page and the open web for a real name and role, never info@. Land on a name (fake: Marisa Donnelly, Owner). Note: in real life, if search comes up dry, that's the one 30-second manual LinkedIn peek.
[PRACTICE] Step 2 of 5: Get the wedge. Give a fake line "from their site": "We catalog every item by hand so nothing gets underpriced." Ask the user first: what's the hook? Then confirm: hand-cataloging is a specific, credible pain, not hype. Specific is what earns a click instead of the spam folder.
[PRACTICE] Step 3 of 5: Draft 3 angles. Each one: a specific opener about them, a curiosity gap, one clear line of value, a soft ask. Show three short variants (pride hook, backlog FOMO, contrarian tease). Have them pick the one that sounds most like them.
[PRACTICE] Step 4 of 5: You finish. They swap the opener into their own voice and send. About 2 minutes, versus 20 spent staring.
[PRACTICE] Step 5 of 5: Your playbook (keep this). Hand over the recipe below, saved by name. This is the part they actually walk away with.
---
The saved playbook
## Cold-email playbook
When to use: reaching out to a new lead and you want a personal email, fast.
1. Research: paste this:
"Find the owner or a named decision-maker at [company], never info@. Check their
team/about page and the open web. Then pull 1-2 specific, real hooks I could use
(a process they're proud of, a goal, a gripe, something on their site). Give me
the name, role, and the hooks. If you can't find a real person, tell me to grab
it from LinkedIn."
2. (Only if needed, 30 sec) Grab the name and one LinkedIn detail yourself, paste it in.
3. Draft: paste this:
"Write 3 short cold emails to [name], [role] at [company]. Hook: [hook]. Each one:
a specific opener about THEM, one curiosity gap, one clear line of value about
[your product in a sentence], a soft ask with [link]. Under 90 words, credible not
hypey, no spammy superlatives. Make the 3 angles genuinely different."
4. Finish: paste this, then send:
"Tighten my favorite to sound like me: more casual, cut anything salesy, keep it
under 80 words."
Re-run it later by saying: "run my cold-email playbook for [company]."---
The feedback check
Right after: "Was that helpful? Think you'll use it on your next real one? If not, what was off: the steps, the fake example, or how I explained it?"
Then quietly, later: next real cold email they write, did they use the playbook or go back to the blank screen? That answer, not their thumbs-up, is whether this worked.
Memory: what Timeback remembers, and where
Timeback can't remember anything on its own. A skill reads the conversation it's in and nothing else. So memory is a small store the coach reads at the start of a session and updates as it goes.
Where it lives
Two layers, simplest first:
1. The AI tool's built-in memory, if it's on (Claude memory, for example). Best, because it carries across chats with zero setup. 2. A notes file in the project as the backup, named timeback-memory.md. The coach reads it first and appends to it. Use this when built-in memory isn't available.
Keep it small. This is field notes, not a database. Everything stays in the user's own account. Nothing leaves.
What it holds
1. Mission (the WHY)
The person's bigger goal, the reason saving time matters at all. One or two lines.
Mission: get my evenings back. I want to stop doing outreach after dinner.Everything else ladders up to this. When you pick what to coach, prefer what moves the mission most. Borrowed from Matt Pocock's teach skill.
2. Learner profile
A few lines about how this person learns and works.
- Preferred way to learn: checklist, or do-it-together
- Their role or kind of work, if known
- Anything they told you about how they like to be coached
3. Field log (the tally)
One dated line per session of what they worked on. This is how time-sinks surface, cheaply, over time.
mon drafted 3 cold emails, formatted a weekly report
tue cold emails again, researched two companies
wed cold emails (struggled, lots of rewrites)After a week, the pattern is obvious without ever re-reading old chats.
4. Playbook archive
The named recipes the person can re-run. Each one: a name, the numbered steps, and the exact prompts to paste. See PLAYBOOK-ENGINE.md for the format. This archive is the real asset. It grows with the person.
5. Mastery record
For each playbook or skill, how far it has actually landed. More than a yes/no: it's the floor that tells you what NOT to re-teach.
cold-email status: mastered evidence: used unprompted on a real lead, twice
report-format status: reverted why: drill felt too generic
queue-triage status: learning last drill mon, not used for real yet- Mastered (used unprompted on real work) is a floor. Never re-drill it. Build past it, toward the mission.
- Reverted means the teaching failed. The why-bucket (presentation / drill / fit) tells you what to fix.
- Use this to aim the next drill just past their current level, not at something they already own. The mastery-floor and just-beyond ideas are borrowed from Matt Pocock's teach skill (learning records and the zone of proximal development).
How the coach uses it
- Start of session: read the mission, the profile, and the recent field log so you know who you're with, what they're aiming at, and what's been eating their time.
- During: append one field-log line. Note any friction.
- After a drill: save the new playbook to the archive, add a mastery-record entry (start it at "learning").
- Later: when a known task reappears, check the mastery record. Did they use the playbook? Update its status. If they used it unprompted, mark it mastered and stop drilling it. That check is the whole feedback loop, and it's what tells you the next thing to teach.
The Playbook Engine
This is the generalizable core of Timeback. The cold-email playbook is just one instance. This file is how you turn ANY time-sink into a drill plus a saved, reusable playbook. New time-sinks slot in here.
A time-sink is any task the person does over and over that takes too long and is partly automatable. Once the tally and friction signals point at one, run this.
Step 1: Scope a safe drill
Take their real task and make a tiny, safe practice version of it.
- Same shape as their real work, smaller, on fake or sample data. Never their live work.
- Small enough to finish in about 5 minutes.
- Pick the part that actually eats their time (often the research or the blank-page start), not the whole job.
Step 2: Teach by doing (show, then hand off)
Run the drill in three beats. Keep each one short. 1. You show one move. Demonstrate the first step on the fake data so they see how it goes. 2. They try the next. Hand them the next step and wait. Give one piece of feedback. 3. They do it for real. "Now run it on your actual task. I'm here if you get stuck."
Use clear practice labels so they always know it's safe, for example [PRACTICE].
Step 3: Hand over the playbook (this is the point)
Every drill ends here. No exceptions. A drill with no playbook is a nice chat they'll forget by next week.
Build the playbook as numbered steps plus the exact prompts to paste. The prompts are what they actually walk away with. Use this format:
## [Name] playbook
When to use: [the situation]
1. [Step]: paste this:
"[the exact prompt, with [brackets] for what they fill in]"
2. [Step]: paste this:
"[exact prompt]"
3. [Step, including any 30-second manual bit]
Re-run it later by saying: "run my [name] playbook for [thing]."Then save it by name into the playbook archive (see MEMORY.md), and tell them how to call it back:
"Saved as your '[name] playbook.' Next time just say 'run my [name] playbook' and we skip straight to doing it."
Step 4: Close the feedback loop
- Ask once, right away: "Helpful? Think you'll use it? If not, what was off: the steps, the example, or how I explained it?"
- Log it in the adoption log.
- Later, when the task reappears, check: did they use the playbook, or revert? Reverting means it failed. Note the why-bucket (presentation / drill / fit) and fix that part next time.
Principles that keep this good
- The playbook outranks the drill. People adopt a recipe they can re-run, not a memory of a chat.
- Exact prompts, not vague advice. "Use AI for research" teaches nothing. A prompt they paste teaches everything.
- Credible over clever. Whatever the task, push them toward specific and honest output, never hype.
- Real adoption is the only score. If they don't keep using it, the lesson failed, no matter how good it looked.
Releasing
How to cut a new version. Every shipped change should bump the version, so users get told when they're behind.
Versioning
Semantic versioning, MAJOR.MINOR.PATCH:
- PATCH (1.0.0 to 1.0.1): wording, fixes, small clarifications.
- MINOR (1.0.0 to 1.1.0): a new capability, section, or technique.
- MAJOR (1.0.0 to 2.0.0): a big restructure that changes how the skill works.
The fast way
./bump.sh <new-version> "<one-line changelog summary>"Example:
./bump.sh 1.1.0 "Add a second ready-to-run playbook for weekly reports"The script writes VERSION, updates the version number in SKILL.md and README.md, prepends a CHANGELOG.md entry dated today, commits, tags vX.Y.Z, pushes, and creates a GitHub release.
The manual way
If you'd rather do it by hand, bump the version in three places that must stay in sync:
1. VERSION 2. the version line near the top of SKILL.md (so the running skill knows its own number) 3. a new entry at the top of CHANGELOG.md
Then:
git add -A && git commit -m "release: vX.Y.Z"
git tag -a vX.Y.Z -m "vX.Y.Z"
git push && git push origin vX.Y.Z
gh release create vX.Y.Z --title "vX.Y.Z" --notes "what changed"Why the version lives in SKILL.md too
A skill can't read its own VERSION file at runtime, it only reads the instructions. So the number has to be written into SKILL.md for the running skill to know what version it is and compare against the latest on GitHub. That's why the bump touches both.
1.0.0