agentleFS
abhaylaabhayla/claude-best-practices/.claude/skills/start-session/SKILL.md

start-session

Skill9 starsChanged 7 months agoMITView on GitHub

Restore a previously saved session checkpoint. Reads a session file from .claude/sessions/, loads working files into context, and presents a structured briefing with task progress and resume notes. Use when starting a new conversation to pick up where you left off.

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before restoring, sweep open PRs so any PRIOR session's green work lands now.

    line 30

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Start Session — Restore a Saved Checkpoint

Load a session file created by /end-session and restore working context for seamless resumption.

Key distinction: /start-session restores file-level context from a structured checkpoint. /continue gives a lightweight git-state briefing without session files. Use /start-session when you have a saved session; use /continue for a quick orientation.


STEP 0: Reconcile + Land Leftover PRs (catch-up — runs first)

Before restoring, sweep open PRs so any PRIOR session's green work lands now. This is the catch-up for sessions that ended without /end-session (the unreliable SessionEnd path): a finished, CI-green PR otherwise sits open until some later session sweeps it.

Skip silently if gh is unavailable, the repo has no GitHub remote, or AUTO_MERGE=0. Never touch the current HEAD branch (active work must not be merged out from under you).

Single source of truth for the landing logic: .claude/hooks/session-git-landing.sh

(shared with /end-session's STEP 5 and the auto-pr hooks). reconcile arms native auto-merge on

every open, non-draft PR EXCEPT the current branch — each lands when its required CI passes.

bash "$(git rev-parse --show-toplevel 2>/dev/null)/.claude/hooks/session-git-landing.sh" reconcile


Report what it armed (or "no leftover PRs"). Then continue to restore the session.

---

## STEP 1: Find Session

Determine which session to load based on the argument:

### If `--list` is provided:
```bash
ls -lt .claude/sessions/*.md 2>/dev/null

Present a numbered list of available sessions with dates and names. Ask the user to pick one. If no sessions exist, inform the user and suggest running /end-session first.

If a session name is provided:

Look for .claude/sessions/{name}.md. If not found:

  1. Try fuzzy match — list sessions containing the provided name
  2. If exactly one match, confirm and use it
  3. If multiple matches, present them and ask the user to pick
  4. If no matches, inform the user and list available sessions

If no argument is provided:

Load the most recent session file (by filesystem modification time):

ls -t .claude/sessions/*.md 2>/dev/null | head -1

If no sessions exist, inform the user and suggest /end-session.


STEP 2: Parse Session File

Read the session file and extract these sections:

  • Working Files — file paths, statuses, and notes
  • Git State — branch, recent commits, uncommitted changes
  • Key Decisions — architectural choices and rationale
  • Task Progress — completed, in-progress, and blocked items
  • Resume Notes — what to do first, gotchas, context needed

Handle missing sections gracefully — if a section is absent, note it as "not captured" rather than failing.


STEP 3: Restore Context

Load working files into context in priority order:

Priority order:

  1. Modified files — most likely to need immediate attention
  2. Created files — new code that needs continuation
  3. Read files with specific lines noted — targeted context
  4. Read files without specific lines — background context

Constraints:

  • Limit to 10 files maximum — if more than 10 working files are listed, load the top 10 by priority and note the remainder
  • Verify files exist — before reading each file, check it exists. If a file is missing, warn: "File {path} from session no longer exists (may have been renamed or deleted)"
  • Check branch match — compare the current branch to the session's branch:
    git branch --show-current
    If branches differ, warn: "Session was on branch {session-branch} but you're on {current-branch}. Some files may have different content."

Read each existing file using the Read tool.


STEP 4: Present Briefing

Present a structured briefing — do NOT auto-start any work.

## Session Restored: {session-name}

**Saved:** {date}
**Branch:** {session-branch} {⚠️ current: {current-branch} if different}

### Working Files Loaded
- {file} ({status}) — {notes}
- ... ({N} of {total} files loaded)

### Task Progress
**Completed:** {count}
**In Progress:** {count}
- {in-progress item 1}
- {in-progress item 2}
**Blocked:** {count}
- {blocked item} — {blocker}

### Key Decisions
- {decision summary}

### Resume Notes
> {what to do first}
> {watch out for}

### Suggested Action
> {specific next step based on in-progress/blocked items}

CRITICAL RULES

  • MUST NOT modify any local files — the restore path (STEP 1+) is strictly read-only. The ONLY write is STEP 0's CI-gated PR landing (a remote git op, never a local file change)
  • MUST reconcile + land leftover green PRs in STEP 0 (merge if CLEAN, else arm auto-merge), but MUST NOT touch the current HEAD branch, and MUST skip silently on no-gh/no-remote/AUTO_MERGE=0
  • MUST NOT auto-start work after presenting the briefing — wait for user direction
  • MUST warn if the current branch differs from the session's branch
  • MUST handle missing files gracefully — warn and continue, do not fail
  • MUST limit file reads to 10 maximum to avoid context overload
  • MUST handle missing sections in session files without errors
  • MUST inform the user if no sessions exist and suggest /end-session

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.