Brief

Session Brief

Run this at the end of a session to capture context and checkpoint all work to GitHub.

Steps

1. Review Existing Brief

Read brief/session-brief.md to understand what was there from last session.

2. Write the New Brief

Overwrite brief/session-brief.md with a comprehensive brief covering:

• Date, time, and session number at the top — run date "+%A %Y-%m-%d %H:%M %Z" to get the real date, day of week, and local timezone rather than guessing (LLMs are unreliable at computing the day of the week, especially for future dates)
• Important progress made in the current session
• Key decisions and architectural changes
• Unfinished tasks and next steps
• Technical details that need to be preserved
• Any context that would be lost between sessions

This is NOT about brevity — be as thorough as needed to retain all important context.

2.5. Reflect on Skills

After writing the brief, run the reflect skill to scan the conversation for learnings. This is a delegation, not a repeat of the reflect instructions. Load and follow the reflect skill.

• If learnings are found: present them to the user alongside the brief, before asking about git
• If no learnings: report "no new skill learnings detected" in one line and continue to Step 3
• Any approved skill updates will be committed together with the brief in Step 4

2.7. Sync Skills (opt-in projects only)

If the project has an .agents/ directory, run the sync-skills skill with project scope (no prompt) so .agents/skills/ mirrors .claude/skills/ before committing. Only mention it if something was added or removed. If there is no .agents/ directory, skip silently — never create one.

3. Ask About Git

After writing the brief, always ask the user which option they want:

1. Commit + push — full checkpoint to GitHub
2. Commit only — local save point, push later
3. Brief only — just the file update, no git operations

Present these as a quick choice. Do NOT assume commit+push.

4. If Committing (options 1 or 2)

1. Run git status to see all changes (staged + unstaged + untracked)
2. Run git log --oneline -3 to match commit message style
3. Stage all relevant files (git add — use specific paths, not -A)
4. Commit with message format: Session [N]: [1-2 sentence summary of session work]
5. If option 1, push to origin: git push

Commit rules:

• Do NOT stage files that look like secrets (.env, credentials, tokens)
• If there are uncommitted changes unrelated to this session, ask the user before including them
• If push fails (e.g., remote is ahead), stop and ask the user — do not force push

When to Use

• At the end of significant sessions
• When important decisions have been made
• Before ending a session where critical details might be lost
• When the user explicitly requests /brief

Read-Only Mode

When asked to "read the brief" (typically at session start via /start), just read the file without modifying it. Do not commit or push in read-only mode.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: t0ddharris
• Source: t0ddharris/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.