01 Overview

Claude Code lets you author "skills" — Markdown files with a little YAML frontmatter that an agent loads and follows as a procedure. I wrote two, to make the parts of my own workflow I most wanted to be repeatable into something an agent runs the same way every time. They are prose, not code: no services, no ports, nothing to deploy. The point was building a capability for an AI agent rather than only using one.

handoff

save-state

A semantic checkpoint. The agent reads repo state — diff, branches, commits — then writes and syncs a fixed documentation suite so a fresh session can resume with minimal context loss.

reverse-engineering

debug-research

A six-phase forensic protocol for the D3Guard Blender port: read the old source line by line, map behavior, research it online, and save a report where every claim carries a file:line citation.

02 Why I built it

Both grew out of one long project: migrating an ~82k-line Blender add-on from 2.79 to 4.5. On a job that size, the dominant cost isn't writing code — it's an agent reconstructing what it already knew after the context window resets, and re-learning old behavior it half-remembers. save-state attacks the first problem: its stated goal is "so that a new Claude Code instance can rapidly regain full project competency with minimal context loss." debug-research attacks the second: it was born from repeated porting mistakes, and it hard-codes the lessons that caused them — read the real file, cite the line, don't trust your memory of it. Notably, the research reports predate the skill by a month; the skill formalized a practice that was already working by hand.

03 What I built & how it works

Two protocols, one goal: make an agent's understanding durable and checkable.

Fig. 1 — debug-research reconstructs legacy behavior with citations; save-state preserves working state between sessions. Both are pure prompt — frontmatter plus a protocol body, no scripts.

The debug-research pipeline, phase by phase:

Scope — explore the canonical 2.79 source, using the 2.79b bundled Python as the API reference; the live 4.5 copy is banned as a reference so the two never get confused.
Trace — open the real files and read them line by line: full call chains, exact code, parameter tables, coordinate spaces — no summarizing from memory.
Map — object hierarchy and data flow, drawn as ASCII coordinate-space chains (Local --(mx)--> World).
Research — parallel agents across seven Blender sources (docs, Stack Exchange, forums, the bug tracker), each finding tagged with a URL and whether it is confirmed in 4.x.
Synthesize — compare the code trace against the community findings, spell out the 4.5 implications, and rank fixes by confidence.
Save — write a templated report (What Happens / Key Params / Exact Code / Coord Chain / Physical Meaning / 4.5 Implications), after a dedup check against prior reports.

save-state is the mirror image: instead of reconstructing the past, it preserves the present. It analyzes the working tree, then writes and updates a named documentation suite — CLAUDE.md, ARCHITECTURE.md, SESSION_SUMMARY.md, LESSONS_LEARNED.md, NEXT_STEPS.md and a few more — plus per-directory notes and a session capture of blockers, intent, and temporary workarounds. Its accuracy rules are explicit: distinguish observed facts from inferred assumptions, and mark uncertainty rather than paper over it.

04 🛠 Skills & tech used

Authoring

MarkdownYAML frontmatterClaude Code skillsslash-command triggerauto-trigger descriptions

Agent engineering

multi-phase prompt protocolsparallel Explore-agent orchestrationanti-hallucination guardrailscontext-window checkpointingAI-handoff optimization

Techniques

legacy code archaeologycall-chain tracingcoordinate-space analysiscomparative-source verificationmandatory file:line citationdedup / knowledge management

Domain / data

Python · Blender bpyPowerShell (documented output)templated report schemaparams tablesASCII coord-chain notation

05 Notable challenges & decisions

The interesting part isn't the prompts — it's the anti-rationalization rules that keep an agent honest under pressure.

Citations

Citations, or it didn't happen

Every "2.79 does X" claim must carry a d3guard-master/<file>:<line> reference. The skill states it plainly: a vague claim "without a line reference is insufficient." This forces the agent to open the file it's asserting about instead of narrating a plausible-sounding memory.

Canonical source

Lock the reference so copies can't drift together

After confusion between the live 4.5 copy and several forks, the skill names d3guard-master/ canonical and bans the working copy as a reference — and pins the API docs to the 2.79b bundled Python, not 2.83. The add-on has nine-plus copies of shared frameworks that diverge; the rule stops the agent from citing the wrong one.

Self-check

"Comments lie. Code is truth."

A Red Flags table lists the rationalizations that let a hurried agent skip the actual reading — "the comment explains it," "this is the same as the other file" — and answers each. It exists because a bulk find-and-replace once missed two subdirectories and quietly broke a clinical workflow; the report on that mistake became its own entry.

Fidelity

save-state records what went wrong, not just what works

On a real run, the output captured dead ends (a Terraform-vs-antivirus mTLS failure), per-step verification evidence, its own not-yet-staged meta-state, and even secrets that had leaked into the transcript — with rotation steps. A snapshot that only records successes is a snapshot you can't trust.

Honest limitation. ~/.claude isn't under version control, so I can't reconstruct these files' edit history — and debug-research still points at D:/dev/ for reports that were later consolidated into _research/, so a fresh run would write to the old path and miss its own dedup check. The skill text was never updated to match.

06 Results

skills authored

debug-research reports produced

5,235

lines of cited research

phase forensic protocol

online sources per research pass

file documentation suite (save-state)

Sources: the two SKILL.md files (137 and 92 lines) and the D:/dev/_research report set (wc -l), 2026-03-28 → 04-24. The port these reports supported reached feature-complete, but that outcome is downstream and not solely attributable to the skills.

07 Media

No live demo — these are files you open. The honest artifact is the protocol beside the report it produced.

[ side by side ]
SKILL.md protocol → generated research report

Left: the debug-research protocol body. Right: one of its reports — params table, exact-code block, and an ASCII coordinate-frame chain, each claim carrying a file:line citation.

[ Red Flags table ]
rationalization → rebuttal

The anti-rationalization self-check that closes debug-research: each excuse for skipping the reading, answered.

[ save-state suite ]
SESSION_SUMMARY · phase table · dead ends

A session snapshot from a router-setup run (secrets and identifiers redacted before any sharing).

08 Honest status

These are write-ups: two Markdown skill files, not a running service. There's nothing to deploy or demo beyond opening them and the reports they produced. They earned a place here because they're a capability built for an agent rather than by one — encoded discipline that made a long, error-prone port more repeatable. The caveats are real and worth stating: authorship history is unverifiable since ~/.claude isn't versioned; the debug-research report path has drifted out of sync with the file; and a few of save-state's eight doc-suite files (INDEX, ARCHITECTURE, SYSTEM_MAP, DIRECTORY_MAP) I've never actually seen generated, so runs appear to be selective rather than exhaustive.

claude-skills — Build Recipe

Install and use two prompt-only Claude Code skills written during an ~82k-line Blender 2.79 → 4.5 addon port: save-state (a session-checkpoint discipline — snapshot the repo, session intent, and lessons learned into a doc suite a fresh agent can resume from) and debug-research (a citation-strict protocol for reverse-engineering legacy code before porting it — line-by-line traces, mandatory file:line citations, and a written research report per topic).

Recipe-only entry. This project deviates from the usual 3-tier container template on purpose: these are Markdown prompt files, not services — there is nothing to containerize. The recipe is structured by what a reviewer can actually do: install (Step A), run save-state on any repo (Step B), adapt debug-research to their own legacy codebase (Step C).

Status: Assembled and de-identified 2026-08-02 from the original working files; not re-executed for this recipe. What was previously real: the debug-research practice was in near-daily use March–April 2026 on the port; save-state was codified 2026-05-10 and has one confirmed run (a router-automation session, 2026-05-16). The shipped samples/show-hide-workflow-research.md is one of 17 real debug-research reports (5,235 lines total, 2026-03-28 → 2026-04-24), included unmodified; samples/save-state-output-CLAUDE.md is a real project doc maintained under the discipline the save-state skill later codified (snapshot 2026-05-08 — two days before the skill file's mtime, so whether that refresh ran the skill or was done by hand is not verifiable), lightly de-identified. No claim here was produced by a fresh run today.

Sensitive data: none in the shipped files. There were never any keys or services involved — the de-identification story is paths and deliverable names only. save-state/SKILL.md needed no changes at all (it is fully generic); the debug-research original ships with its project-specific paths intact as an authentic exhibit (they are local dev paths, not secrets); the CLAUDE.md sample had absolute machine paths and client deliverable filenames generalized.

What these are

Claude Code discovers skills in ~/.claude/skills/<name>/SKILL.md — a YAML frontmatter block plus Markdown instructions. No code runs; the file is the tool.

Skill	What it encodes	Size
`save-state`	End-of-session checkpoint: analyze repo state, sync a doc suite (CLAUDE.md, SESSION_SUMMARY.md, LESSONS_LEARNED.md, NEXT_STEPS.md, …), mark observed vs. inferred, capture blockers and intent so the next session starts warm	92 lines
`debug-research`	6-phase forensic protocol for legacy code: scope → line-by-line trace → interaction map → online research (7 named sources) → synthesize → save a templated report. Two enforcement ideas do the work: citations-or-it-didn't-happen (`<file>:<line>` required for any "the legacy code does X" claim) and a Red Flags table of rationalizations to catch yourself making	137 lines

The debug-research original is hard-coded to one project (a dental-CAD Blender addon port) — that specificity is deliberate and is why it ships in two forms:

skills/debug-research/SKILL.md — the original, verbatim. Shows what a real, working version looks like: a canonical-source lockdown (pristine 2.79 master allowed, live working copy banned), the exact matching Blender version pinned (2.79b, not 2.83), a dedup list of prior reports.
skills/debug-research-template/SKILL.md — a generalized variant with three placeholders (<LEGACY_SOURCE_ROOT>, <WORKING_COPY>, <REPORTS_DIR>) so you can point it at your own legacy codebase. It also fixes a known path-drift bug in the original (see Limitations).

Repo layout

claude-skills/
├── RECIPE.md                                  ← this file
├── skills/
│   ├── save-state/SKILL.md                    ← verbatim original (fully generic)
│   ├── debug-research/SKILL.md                ← verbatim original (project-specific exhibit)
│   └── debug-research-template/SKILL.md       ← generalized, 3 placeholders, drift bug fixed
└── samples/
    ├── show-hide-workflow-research.md         ← real debug-research output, unmodified
    └── save-state-output-CLAUDE.md            ← real project doc in the save-state style, de-identified

Prerequisites

No accounts, no hardware, no GPU, nothing from the author's machines.

Step	You need
A — install	Claude Code CLI (any version with skills support)
B — save-state	any git repo of your own with a bit of work-in-progress
C — debug-research	some legacy codebase you want to understand or port (yours)

Step A — Install

Copy the skill folders into your user-level skills directory and restart Claude Code:

# macOS / Linux
mkdir -p ~/.claude/skills
cp -r skills/save-state ~/.claude/skills/save-state
cp -r skills/debug-research-template ~/.claude/skills/debug-research

# Windows
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse skills\save-state "$env:USERPROFILE\.claude\skills\save-state"
Copy-Item -Recurse skills\debug-research-template "$env:USERPROFILE\.claude\skills\debug-research"

Note the template folder is installed as debug-research — the folder name must match the skill's frontmatter name: (debug-research), and that is the name Step C invokes. Restart Claude Code and confirm both appear in the available-skills listing (the frontmatter description is what shows). Install the template variant of debug-research, not the original — the original's hard-coded paths point at a machine you don't have.

Step B — Try save-state (zero setup)

At the end of a working session on any repo — ideally one with uncommitted changes and a half-finished thought — ask:

run save-state

What to expect: the skill names an 8-file doc suite, but in practice runs are selective — in the real sessions observed, 4 of the 8 named files were actually produced or updated (CLAUDE.md, SESSION_SUMMARY.md, LESSONS_LEARNED.md, NEXT_STEPS.md); INDEX.md / ARCHITECTURE.md / SYSTEM_MAP.md / DIRECTORY_MAP.md were never observed generated. The useful test is the accuracy rules: observed facts should be distinguishable from inferences, and uncertainty should be marked, not smoothed over. samples/save-state-output-CLAUDE.md shows what a CLAUDE.md maintained this way looked like mid-project — port status, "never write inside milestones/" warnings, a latent-cleanup note, and per-sweep bug lists with file:line specifics.

Step C — Adapt debug-research

Open ~/.claude/skills/debug-research/SKILL.md (the installed copy of the template) and fill the three placeholders in the table at the top: your canonical legacy source root (read-only reference), your working copy (banned as a reference), and one reports directory. Delete the template note.
Run it on a real question:

/debug-research <some feature you need to understand before changing it>

Compare the output against samples/show-hide-workflow-research.md. Things the protocol should have forced into existence:
file:line citations on every behavioral claim (the sample cites livecurves_ui_tools.py lines and the specific commit)
exact legacy code blocks, not paraphrase — the sample shows the 2.79 code, the wrong port, and the corrected port side by side
a before/after API mapping table (the sample's hide → hide_set vs. hide_viewport table is the whole bug in four rows)
a validation checklist separating what was verified from what remains

Provenance — the numbers

All from the original machine, verified by file inspection (not re-run):

2 skills; nothing else in the user-level skills directory, and no commands directory (re-checked at assembly time, 2026-08-02)
17 debug-research reports, 5,235 lines total (verified wc -l), 4.9–29 KB each, dated 2026-03-28 → 2026-04-24
The reports predate the skill file (mtime 2026-04-27) by up to a month — the skill formalized a practice that was already working, which is the honest order these things happen in
Save-state output: one confirmed skill run — the 4-doc suite from a router-automation session (2026-05-16, not shipped — it contains live network credentials). The shipped d3guard CLAUDE.md snapshot (2026-05-08) predates the skill file's mtime (2026-05-10): it was maintained under the discipline the skill later codified, but whether that refresh ran the skill or was manual is not verifiable

Known limitations (stated honestly)

Output quality is model- and session-dependent. A skill is a prompt; it raises the floor and standardizes the artifact, it does not guarantee the ceiling. Your first report will not match the sample without iteration.
The original debug-research is single-project by design. Its value to a reviewer is the pattern — canonical-source lockdown, citations-or-it-didn't- happen, the Red Flags self-check — not drop-in reuse. That is what the template variant extracts.
Known bug shipped as-is in the original: the skill text points both the Phase 6 write and the dedup check at the dev root, but the actual reports had later been consolidated into a _research/ subfolder and the skill text was never updated — a fresh run of the original would write to (and dedup against) the stale root location and miss its own prior work. Kept in the shipped original because it is the authentic file; avoided in the template by making <REPORTS_DIR> a single placeholder you point at the real reports directory.
Authorship history is unverifiable. ~/.claude was never a git repo, so there are file mtimes but no commit trail for the skills themselves.
Attribution is limited. The port these skills served did reach 24/24 workflow steps verified in an 11,977-line zero-traceback session — but that outcome is not solely attributable to the skills, and this recipe makes no such claim.