# Save

> Save all session progress to status tracking files. Use when you want to checkpoint work mid-session or before ending.

- Skill: `kimon1230/save` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kimon1230/save`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kimon1230/save/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kimon1230 (https://skillmd.com/u/kimon1230)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kimon1230/save

---


# Save Progress

This skill must only be invoked from the main session, never from a subagent.

1. **Determine the project name** (used for file paths in all later steps):
   a. If a `~/.claude/status/*/session-progress.md` was written earlier this session, reuse that project name.
   b. Else if inside a git repo with a remote, use the `origin` remote. Parse the last path component, stripping any trailing `.git` (e.g., `my-lib` from `git@github.com:user/my-lib.git` or `https://github.com/user/my-lib.git`).
   c. Else use the basename of the git root (`git rev-parse --show-toplevel`).
   d. Else use the basename of the current working directory.
   e. If still ambiguous, ask the user.

2. **Capture test state** (do NOT run tests yourself — a Stop hook already runs pytest automatically):
   - If tests ran recently in this session, reference those results (pass/fail counts).
   - If no test results are available, record "No test results available this session."
   - Do NOT invent results.

3. **Create the directory** `~/.claude/status/<project-name>/` if it does not exist.

4. **Write/update** `~/.claude/status/<project-name>/session-progress.md` with:
   - **Timestamp**: `YYYY-MM-DD HH:MM UTC`
   - **Current task**: what you were working on
   - **Completed**: detailed progress using typed entries. Each entry is classified and formatted as follows:

     **Entry types:**
     - **Decision**: The change involved choosing between alternatives or a non-obvious approach. MUST include a `Why:` line.
     - **Observation**: A factual record of what happened with no meaningful alternatives considered. Plain body, no `Why:` required.
     - When in doubt, prefer `decision` — better to over-document rationale than lose it.

     **Entry format:**
     ```markdown
     ### [decision] Title describing the choice <!-- id:a1b2c3d4e5f6a7b8 -->
     Why: Rationale for this decision (SACRED — never compress or paraphrase).
     What: Implementation details (optional).

     ### [observation] Title describing what happened <!-- id:e5f6a7b8c9d0e1f2 -->
     Plain body text describing the change.
     ```

     **Entry IDs:** Generate a unique ID for each new entry — 16 hex characters (e.g., `a1b2c3d4e5f6a7b8`). Just produce a random-looking 16-char hex string.

     **Appending to existing files:** When updating an existing `session-progress.md`, preserve all existing entries verbatim — only append new ones.

     **Auto-captured entries:** If a `## Auto-captured` section exists (added by the auto-capture hook), review those entries:
     - Promote useful ones to the main **Completed** section.
     - Upgrade observations to decisions with a `Why:` line where appropriate.
     - Remove the `## Auto-captured` section after processing.

     **Entry body content** — draw from these details as appropriate:
     - **Per-batch/phase breakdown** when following a plan — what each batch accomplished
     - **Files created, modified, or deleted** — explicit paths (e.g., `src/foo/bar.py` — added `MyClass`, refactored `process()`)
     - **Implementation specifics** — functions, classes, modules, config options added or changed
     - **Issues encountered and workarounds** — anything the next session should know about (e.g., "ruff F401 requires atomic edits", "had to retry due to X")
     - **Prior session context** — when resuming multi-session work, summarize what earlier sessions completed so the file is self-contained
   - **Remaining**: bullet list of what's left, with enough detail to pick up without re-reading the plan
   - **Test state**: from step 2
   - **Key decisions**: any architectural or design choices made
   - **Active plan**: path to the current plan file in `~/.claude/plans/<project-name>/`, or "None"
   - **Context needed to continue**: anything a fresh session needs to know (key file paths, uncommitted state, critical checkpoints, next batch to start)

5. **Update or create** `~/.claude/status/<project-name>/project-status.md` — the cumulative project history across all sessions:

   **If the file does not exist**, create it with these sections (adapt to the project):
   - **Overview**: one-line project description
   - **Last Updated**: timestamp
   - **Version History**: table of released versions with features (if applicable)
   - **Phase Progress**: table of completed items with status and key files touched
   - **Plans on Disk**: paths to active/completed plan files with status
   - **Test Results**: latest pass/fail/skip counts, coverage, lint status
   - **Next Steps**: what comes next
   - **Deferred Work**: backlog items with references to where they're documented
   - **Git State**: uncommitted changes summary (user handles git)

   **If the file already exists**, read it first and update the sections that changed this session:
   - Add new rows to phase/version tables for completed work
   - Update test results with latest counts
   - Update plans on disk (add new plans, mark completed ones)
   - Update next steps to reflect current state
   - Update git state if relevant
   - Update last updated timestamp
   - Do NOT delete or rewrite sections that haven't changed
   - If the file uses different section names, match its existing structure — don't force the template above

6. Confirm to the user what was saved and where.