Three skills. One install order. Work that survives.
These three Claude Code skills make a project remember what was done, survive interrupted sessions, and move to another machine with nothing lost. Each one installs itself, sets itself up in your repo, and updates itself when you run it again. Install them in the order below.
download https://www.siriusart.bg/handoff-toolkit/INSTALL_ACHIEVEMENTS_SYSTEM.md with curl, then run and install itasks: this project only, or every project?download https://www.siriusart.bg/handoff-toolkit/INSTALL_RESILIENT_AGENT_HANDOFF.md with curl, then run and install itinstalls globally, adds rules to CLAUDE.mddownload https://www.siriusart.bg/handoff-toolkit/INSTALL_SESSION_HANDOFF.md with curl, then run and install itinstalls globally, turns on the refresh hook, writes the first handoffEach skill closes one way work gets lost
A Claude Code session keeps its understanding in its own context, and that disappears when the session ends, hits a rate limit or runs out of room. Git keeps the code but not the reasoning. These skills write the missing parts into the repo, where they survive.
Commit messages say what changed, not how the problem was solved or what broke along the way. This skill keeps a permanent, append-only record of every real achievement, and every new session reads the newest records first.
Rate limits and crashes kill a turn mid-step, and parallel agents can overwrite each other’s work. This skill makes agents commit every verified step, write their state down before each step, claim files before touching them, and run long jobs outside the session.
A new computer, or a teammate, starts with none of the context. This skill writes a handoff bundle (state, next actions, tasks, Claude’s memories) into the repo, and a git hook refreshes it after every commit.
What each one adds to your repo
Everything below is created by the skill’s own auto-setup. You never make these files by hand, and re-running a skill only adds what is missing.
| Skill | Files and settings in the repo | Installed where |
|---|---|---|
| achievements-system | A rule section in the root CLAUDE.md (between <!-- achievements-system rule: begin v2 --> anchors), records in docs/handoff/achievements/, an index at .claude/ACHIEVEMENTS_INDEX.md, standalone achievement-establish.md / achievement-sync.md procedures |
You choose: this project only, or all projects |
| resilient-agent-handoff | A rules section in CLAUDE.md, the claim helper .claude/scripts/agent-claim.sh, a line in .gitattributes, and AGENT_CLAIMS.md kept local via .git/info/exclude |
Globally (all projects) |
| session-handoff | docs/handoff/SESSION_HANDOFF.md, TASKS.md, memories/, the hook .githooks/post-commit, a line in .gitattributes, and per-machine git config (core.hooksPath, handoff.*) |
Globally (all projects) |
Each skill also commits a copy of itself to docs/handoff/<name>-skill.md, so anyone who pulls the repo can reinstall it.
Install order, and why it matters
Every skill works on its own and can be re-run safely. The order still matters: it decides where shared files go, and how many extra commits setup produces.
New project, or first install on this machine
Nobody has set these up in the repo yet.
achievements-system first
- It creates the root
CLAUDE.mdand thedocs/handoff/folder the other two build on. - Its rule points at
docs/handoff/achievements/. If session-handoff ran first in a repo withoutdocs/, the bundle would go tohandoff/and the two locations would disagree. - History is recorded from the very first change.
- It creates the root
resilient-agent-handoff second
- Its rules go into the same
CLAUDE.md, and its „record achievements“ rule defers to the log that now exists. - The claim helper is in place before any parallel agent work starts.
- Its rules go into the same
session-handoff last
- Its first handoff snapshot captures the finished setup of the other two.
- Once its hook is on, every commit gets a follow-up
handoff: auto-refresh bundlecommit. Turning it on last keeps the setup history free of those follow-ups.
Existing project, new machine
The repo already has all three; you just cloned it.
session-handoff import first
- Say
import the session on this machine. The skill reads the handoff, installs the skills fromdocs/handoff/, and imports Claude’s memories. - It re-creates the per-machine hook settings, which git never copies.
- Say
achievements-system sync
- Say
sync achievements to this machine. It rebuilds the local index and reads the newest records into the session.
- Say
resilient-agent-handoff setup
- Say
run the resilient-agent-handoff auto-setup. The claim helper came with git, but the.git/info/excludeentry for the ledger is local to each clone.
- Say
Out of order is not broken. Running a skill again re-checks everything and fixes what is missing. The order above just avoids rework and extra commits.
Get the files
Everything is plain Markdown, served from https://www.siriusart.bg/handoff-toolkit/. The INSTALL files are what you normally need: each holds a user guide plus the complete skill. The skill files are the bare SKILL.md contents, for copying into ~/.claude/skills/<name>/SKILL.md by hand.
| Order | Installer + guide | Skill only | Version |
|---|---|---|---|
| 1 | INSTALL_ACHIEVEMENTS_SYSTEM.md | achievements-system-skill.md | v2 |
| 2 | INSTALL_RESILIENT_AGENT_HANDOFF.md | resilient-agent-handoff-skill.md | v3 |
| 3 | INSTALL_SESSION_HANDOFF.md | session-handoff-skill.md | v3 |
# or download all three installers from a terminal
curl -fsSLO https://www.siriusart.bg/handoff-toolkit/INSTALL_ACHIEVEMENTS_SYSTEM.md
curl -fsSLO https://www.siriusart.bg/handoff-toolkit/INSTALL_RESILIENT_AGENT_HANDOFF.md
curl -fsSLO https://www.siriusart.bg/handoff-toolkit/INSTALL_SESSION_HANDOFF.md
How to install
Each skill comes as one shareable file (INSTALL_*.md) holding a guide plus the complete skill. Pick whichever method fits; all of them give the same result.
A · One-line prompt
EasiestOpen Claude Code in your project and paste the prompt for the skill. It downloads the file straight from this site:
download https://www.siriusart.bg/handoff-toolkit/INSTALL_ACHIEVEMENTS_SYSTEM.md with curl, then run and install it
Already have the file in the project folder? Shorter:
run and install INSTALL_ACHIEVEMENTS_SYSTEM.md
Claude follows the install steps inside the file. It checks every existing copy (it never downgrades), writes the skill, commits a copy of it only if something changed, then sets the skill up in your repo. Claude Code may ask you to confirm, because the file installs instructions future sessions will follow.
The prompt says „with curl“ on purpose: curl saves the exact file, while a web-page reader can hand Claude a summary. Add install only, don't run AUTO-SETUP to install without touching the current repo.
B · Paste the install block
When Claude can’t see the fileIf you received the file by email or chat, open it, copy everything from ~~~PASTE START~~~ to ~~~PASTE END~~~ (section 9), and paste it into Claude Code.
C · Shell, no Claude
ManualFrom the folder with the file, in Git Bash, macOS or Linux. This copies the skill without a version check and does not set it up; the first time you invoke the skill, its auto-setup does that.
# example: achievements-system
n=achievements-system
home="${USERPROFILE:+$USERPROFILE/.claude}"; home="${home:-$HOME/.claude}"
mkdir -p "$home/skills/$n"
awk '/^--- BEGIN SKILL.md CONTENT/{f=1;next} /^--- END SKILL.md CONTENT/{exit} f' \
INSTALL_ACHIEVEMENTS_SYSTEM.md > "$home/skills/$n/SKILL.md"
| Requirement | Why |
|---|---|
| Claude Code (CLI, desktop, IDE or web) | Skills are loaded from ~/.claude/skills/ or a project’s .claude/skills/ |
| A git repository | Everything the skills write lives in, and travels with, the repo |
A POSIX sh: Git for Windows (Git Bash), or built in on macOS/Linux | Runs the hook, the claim helper and the setup scripts |
What happens every time a skill runs
Installing a skill and using it trigger the same opening routine, so a first install, a re-install and everyday use all end in the same place: latest version, fully set up.
Reads the <!-- skill-version: N --> line in every copy on the machine: global, project, docs/handoff/, root.
Overwrites only copies with a lower version. Never downgrades, never creates copies in new places.
Looks for what is missing: rule sections, hook, claim helper, handoff bundle, index.
Rewrites generated scripts and replaces versioned CLAUDE.md sections in place, then commits with explicit paths.
Your own edits: the rule sections sit between begin vN / end anchor comments. Edit outside the anchors. If an anchor is duplicated or missing, setup stops with an error instead of guessing.
What to say, and what happens
| Say to Claude | Skill | Result |
|---|---|---|
set up the achievements system | achievements | Checks the repo, then sets up, syncs, or reports ready |
| (just work) | achievements | After real progress, Claude writes YYYY-MM-DD_HHMMSS_slug.md: what, how, findings, problems, verification |
run several agents in parallel on this repo | resilient | Agents claim files, commit each verified step, keep PROGRESS_<task>.md |
resume after the rate limit | resilient | Reads git log, progress files and claims, confirms which processes are still running, then resumes without redoing committed work |
hand off the session | session-handoff | Fresh SESSION_HANDOFF.md + TASKS.md, committed |
translate the handoff to Bulgarian | session-handoff | SESSION_HANDOFF.bg.md, with code and commands unchanged |
What the hook looks like in git log
cd820c9 handoff: auto-refresh bundle b948645 Achievement record: self-updating skills 34c4210 handoff: auto-refresh bundle de48db4 Activate session-handoff in this repo
Each of your commits is followed by a small refresh commit that updates the handoff’s date and commit stamp. Skip it once with HANDOFF_SKIP=1 git commit …. It never fires during a rebase, merge or cherry-pick.
Claiming a file before editing it
sh .claude/scripts/agent-claim.sh claim src/app.js agent-a "refactor"
sh .claude/scripts/agent-claim.sh list
4m CLAIMED | 2026-09-13T14:18:54Z | src/app.js | agent-a | refactor | claim
sh .claude/scripts/agent-claim.sh release src/app.js agent-a
A second agent claiming the same file is refused. stale 90 lists claims older than 90 minutes. Check that the process behind a claim is really gone before releasing it.
Rolling out a new version
On one machine
Run run and install with the newer INSTALL file, or drop the newer SKILL.md into any of the copy locations and invoke the skill. The next run brings every other copy up to it.
Across machines and teammates
Commit the newer docs/handoff/<name>-skill.md. Every machine that pulls it upgrades the next time the skill runs there.
INSTALL files are snapshots. Auto-update refreshes installed copies and repo copies, but not the INSTALL_*.md files; regenerate those when a version number changes.
Check it worked
ls ~/.claude/skillsShowsachievements-system,resilient-agent-handoff,session-handoff(achievements-system may instead be in the project’s.claude/skills/if you chose „this project only“).git config --get core.hooksPathPrints.githooks. Make any commit, andgit log --oneline -2should show ahandoff: auto-refresh bundlecommit on top.grep -c "rule: begin\|rules: begin" CLAUDE.mdPrints2: one achievement rule and one resilience rules section.sh .claude/scripts/agent-claim.sh listRuns without error (empty output is fine when no claims are active).- Ask Claude:
set up the achievements systemReportsSTATE=READYonce everything is in place.
When something looks off
A skill is listed with a strange description like <!-- skill-version: 2 -->
Its YAML frontmatter failed to parse, usually because of a colon followed by a space inside the description. Replace ": " with " - " in that line. The skill still works, but it won’t be picked up from your wording until this is fixed.
The hook fails with $'\r': command not found
On Windows with core.autocrlf=true, git rewrote the script with CRLF line endings. Setup adds .githooks/* text eol=lf to .gitattributes. If yours predates that, run the session-handoff skill once, then rm .githooks/post-commit && git checkout -- .githooks/post-commit.
Claude Code asked for permission, or refused to install from the file
The INSTALL file writes instructions that future sessions will follow, so Claude Code’s safety check may pause on it. Confirm that you trust the file, or name the file explicitly in your prompt. Only install files from people you trust.
I don’t want the extra refresh commits
Skip one with HANDOFF_SKIP=1 git commit …, or turn the hook off for this clone with git config --unset core.hooksPath. The handoff then only updates when you ask Claude to hand off the session.
Setup stopped: „anchors found begin=2 end=1“
A rule section’s anchor comment was duplicated or deleted by hand. Open CLAUDE.md, keep exactly one begin and one end line per section, and run the skill again.