save-progress
Runs deterministic pre-commit checks and updates PILOT.md and SESSION-CONTEXT.md to reflect project state.
Install
mkdir -p .claude/skills/save-progress && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/17199" && unzip -o skill.zip -d .claude/skills/save-progress && rm skill.zipInstalls to .claude/skills/save-progress
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Pre-commit checklist + context update — runs deterministic checks, updates PILOT.md and SESSION-CONTEXT.md. Does NOT commit.Key capabilities
- →Run deterministic preflight checks
- →Update `.meta/PILOT.md` with actual state
- →Rewrite `.meta/SESSION-CONTEXT.md` with architectural snapshot
- →Capture active decisions and traps to avoid
- →Report readiness to commit
- →Skip pytest run for mid-session checkpoints
How it works
The skill executes a Python script for deterministic preflight checks, then updates project metadata files (`PILOT.md`, `SESSION-CONTEXT.md`) with the current state, architectural context, and open questions.
Inputs & outputs
When to use save-progress
- →Pre-commit checklist execution
- →Updating project documentation
- →Capturing architectural session decisions
- →Validating preflight status
About this skill
You are in SAVE-PROGRESS mode. Run the deterministic preflight, then update project context.
Hard rules
- DO NOT create a commit — that is a separate action.
- If preflight fails, STOP and report — do not update
.meta/files.
Step 1 — preflight (deterministic, one command)
uv run python scripts/save_progress_preflight.py
The script runs: pytest, ruff check, ruff format --check, git status,
and a check for stray drafts at the project root or code in .meta/scratch/.
It prints a JSON summary and exits non-zero on any failure.
Step 2 — narrative update (LLM, only if step 1 is green)
- Update
.meta/PILOT.md— status table reflects actual state, not aspirational. Mark completed items. Add new next steps. - Rewrite
.meta/SESSION-CONTEXT.md— architecture snapshot, active decisions (why), traps to avoid (what broke or could break), open questions. Rewrite, don't append. - Report: "Ready to commit. Run
git addandgit commit."
Verification
- Preflight JSON shows
"ok": truefor all 5 checks - PILOT.md reflects actual state
- SESSION-CONTEXT.md captures traps and open questions, not just wins
Quick-pause mode (--skip-tests)
For mid-session checkpoints where tests are genuinely WIP, you may skip the pytest run:
uv run python scripts/save_progress_preflight.py --skip-tests
When to use: only when tests are intentionally red (e.g., mid-refactor, scaffold not yet wired). Not for "tests are slow" or "I can't fix this now."
Required: when using --skip-tests, add a Skip-Tests: true trailer to
the commit message so the bypass is machine-readable in git history:
fix: partial scaffold for new module
Skip-Tests: true
Also note in SESSION-CONTEXT.md under "Traps to avoid" that tests are red and why, so the next session does not ship without fixing them.
Rationalizations you must not accept
| Excuse | Why it's wrong |
|---|---|
| "Tests are passing, that's enough." | Lint and format issues compound — preflight catches them. |
| "I'll update PILOT.md later." | You won't. Next session reads PILOT.md first; stale = wrong. |
| "SESSION-CONTEXT.md is fine from last time." | Context decays every session. Rewrite, don't append. |
| "Small change, skip the preflight." | Small changes break things. The script takes 30 seconds. |
| "Tests are slow, I'll use --skip-tests." | --skip-tests is for intentionally red tests, not slow ones. |
When not to use it
- →When creating a commit
- →When preflight fails
- →When tests are slow but not intentionally red
Prerequisites
Limitations
- →Does not create a commit
- →Preflight must pass for context files to be updated
- →Skipping tests requires a specific commit message trailer
How it compares
This skill enforces a structured pre-commit checklist and updates project context files, providing a more disciplined approach to saving progress than ad-hoc commits.
Compared to similar skills
save-progress side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| save-progress (this skill) | 0 | 4mo | Review | Beginner |
| openspec-archive-change | 4 | 6mo | Review | Intermediate |
| session-wrap | 1 | 7mo | Review | Intermediate |
| proof-of-work | 1 | 7mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
openspec-archive-change
studyzy
归档实验性工作流中已完成的变更。当用户想要在实现完成后最终确定并归档变更时使用。
session-wrap
team-attention
This skill should be used when the user asks to "wrap up session", "end session", "session wrap", "/wrap", "document learnings", "what should I commit", or wants to analyze completed work before ending a coding session.
proof-of-work
MadAppGang
Proof artifact generation patterns for task validation. Covers screenshots, test results, deployments, and confidence scoring.
health
matteocervelli
Holistic project audit across endpoints, versions, docs, security, quality, CI, and library dimensions. Use when checking overall project health or running a periodic cross-cutting audit. Trigger on "project health", "audit the project", "health check", "is this project in good shape".
semantic-commits
lipkau
>-
gsd-validate-phase
lza6
Retroactively audit and fill Nyquist validation gaps for a completed phase