context-save

Skill + Hook Integration Reference — Claude Code v2.1.71 — linuxserver.lan

What This Skill Does

context-save (formerly project-context) maintains 7 persistent knowledge files in docs/context/ for AI agent continuity across sessions. Each file answers one question:

File	Question It Answers
architecture.md	What IS this system?
decisions.md	Why was it built this way?
security.md	What must never be violated?
operations.md	How do you run/deploy it?
testing.md	How is correctness verified?
gotchas.md	What will waste your time?
specs.md	What are the business rules?

Invocation Methods

/context-save — Manual update of all context files
/context-save init — Scaffold docs/context/ for a new project
Hooks — Automatic reminders via shell script

Hook Script

~/.claude/hooks/context-save-check.sh

Three-tier logic: Silent (already updated), Soft reminder (minor/no changes), Strong reminder (significant code changes without docs update).

All Claude Code Hook Events (v2.1.71)

Complete grid of all 15 hook event types. Recommendation column shows which hooks should trigger the context-save script.

Hook Event	When It Fires	Key Payload Fields	context-save?	Rationale
`Stop`	Agent finishes its turn (main agent)	`stop_hook_active`, `cwd`	ACTIVE	Primary save point — session work is complete, context should be persisted.
`SubagentStop`	A subagent finishes its delegated task	`stop_hook_active`, `agent_id`, `agent_type`	ACTIVE	Subagents often make significant changes that need capturing.
`PreCompact`	Before context window compaction (manual or auto)	`trigger` (`manual`\|`auto`), `custom_instructions`	NEW	Critical — compaction erases conversation history. Save context before it's lost.
`SessionEnd`	Session terminates (exit, clear, logout)	`reason` (`clear`\|`logout`\|`prompt_input_exit`\|`other`)	NEW	Critical — last chance to persist context before session disappears.
`SessionStart`	Session begins (startup, resume, clear, compact)	`source`, `agent_type`, `model`	NO	Nothing to save yet — session just started.
`PreToolUse`	Before any tool executes	`tool_name`, `tool_input`, `tool_use_id`	NO	Too frequent. Would fire on every tool call — massive overhead.
`PostToolUse`	After a tool executes successfully	`tool_name`, `tool_input`, `tool_response`	NO	Too frequent. Same issue as PreToolUse.
`PostToolUseFailure`	After a tool execution fails	`tool_name`, `error`, `is_interrupt`	NO	Errors don't represent knowledge to persist.
`UserPromptSubmit`	User submits a prompt	`prompt`	NO	Fires on every user message — too early, no work done yet.
`SubagentStart`	A subagent is spawned	`agent_id`, `agent_type`	NO	Nothing to save — subagent hasn't done any work yet.
`Notification`	System notification displayed	`message`, `title`, `notification_type`	NO	Informational only. No relationship to code changes.
`PermissionRequest`	Tool requests permission from user	`tool_name`, `tool_input`, `permission_suggestions`	NO	Permission flow — not a context persistence point.
`Setup`	Initial setup or maintenance	`trigger` (`init`\|`maintenance`)	NO	One-time setup event. No project context to save.
`TeammateIdle`	A teammate agent becomes idle	`teammate_name`, `team_name`	NO	Coordination event. Not related to context persistence.
`TaskCompleted`	A background task finishes	`task_id`, `task_subject`, `teammate_name`	MAYBE	Could be useful if tasks make significant changes, but Stop/SubagentStop already cover this.

Current Hook Configuration

File: ~/.claude/settings.json

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/context-save-check.sh" }]
    }],
    "SubagentStop": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/context-save-check.sh" }]
    }],
    "PreCompact": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/context-save-check.sh" }]
    }],
    "SessionEnd": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/context-save-check.sh" }]
    }]
  }
}

Hook Script Logic

File: ~/.claude/hooks/context-save-check.sh

Condition	Output	Effect
`stop_hook_active == true`	Silent (no output)	Prevents infinite loop from hook re-triggering
Not a git repo	Silent	Skip — no context tracking outside git
No `docs/context/` directory, >5 tracked files	Suggest `/context-save init`	Onboard new projects
No file changes at all	Soft: "consider updating decisions.md"	Catch decision-only sessions
`docs/context/` already modified	Silent	Agent already did the right thing
Code changed, >15 diff lines, docs not updated	Strong reminder listing all 7 files	Significant changes need context update
Code changed, ≤15 diff lines, docs not updated	Soft: "if changes affect architecture..."	Minor changes get gentle nudge

Writing Rules

MUST DO

Terse — Bullet points and tables only
Factual — Only truth, or mark [PLANNED]
Scoped — Each entry in exactly one file
Bounded — Each file ≤200 lines
Atomic — Self-contained bullet points

MUST NOT

No filler or narrative prose
No timestamps (git tracks this)
No duplicates from CLAUDE.md
No empty section headers
No separate commits for context-only changes

Recommended Changes (Applied)

Changes Made

#	Change	Status
1	Renamed skill directory from `project-context/` to `context-save/`	DONE
2	Updated `SKILL.md` name, description, and all `/project-context` references to `/context-save`	DONE
3	Renamed hook script from `project-context-check.sh` to `context-save-check.sh`	DONE
4	Updated `~/.claude/skills/CLAUDE.md` skill index	DONE
5	Added `PreCompact` hook — saves context before compaction erases conversation	DONE
6	Added `SessionEnd` hook — last-chance save when session terminates	DONE
7	Updated `~/.claude/settings.json` with all 4 hook bindings	DONE

Still Needed (Manual)

Update ~/.claude/CLAUDE.md user-level context references from project-context to context-save
Update MEMORY.md references (e.g., project-context hook fix entry)
Any project-level CLAUDE.md files that reference the old skill name

Files Changed

File	Action
`~/.claude/skills/project-context/`	Renamed to `~/.claude/skills/context-save/`
`~/.claude/skills/context-save/SKILL.md`	Updated name, description, invocation commands
`~/.claude/skills/CLAUDE.md`	Updated skill index entry
`~/.claude/hooks/project-context-check.sh`	Renamed to `~/.claude/hooks/context-save-check.sh`
`~/.claude/settings.json`	Updated hook paths + added PreCompact & SessionEnd