Never Lose Progress Again: A Session Summary Skill for AI Agents

If you’ve used any AI agent for a complex or multi-step project, you’ve probably noticed this: somewhere in the middle of a long session, things start going sideways. The agent misses something it knew earlier. It repeats a fix you already tried. The responses feel less sharp. And when you eventually start a new session, you’re back to explaining everything from scratch.

There’s a straightforward fix. It’s a “skill” — a short instruction file that tells the agent exactly how to create a structured session summary before you close out. The next time you open any agent, you hand it that summary file and pick up exactly where you left off. No re-explaining, no lost context.

Getting Started

Download the skill file: SKILL.md — drop it into your agent’s skills folder (e.g. ~/.claude/skills/session-summary/SKILL.md for Claude Code, or ~/.hermes/skills/session-summary/SKILL.md for Hermes).
At the end of any complex session, say: “Summarize the session and write .session_summary.md”
Next session: “Read .session_summary.md and resume from where we left off”

That’s it. One file, one habit, no more lost progress. Read on for why this works.

The Real Problem: Context Degradation

Every AI agent, regardless of the model powering it, has a context window — a working memory that holds the current conversation. They all have one, and they all suffer from the same problem as it grows.

The hard limit (hitting the maximum and getting cut off) is only part of it. The more insidious issue is that model quality degrades well before the limit. As the context grows:

Early information gets less attention — the model focuses on what’s recent
The agent starts repeating suggestions it already made
Subtle details from 50 messages ago get lost or misremembered
Responses slow down and lose focus

This isn’t a problem with any specific model. It’s a fundamental property of how transformer-based models handle long sequences. The longer the context, the more the signal-to-noise ratio drops.

The real issue isn’t the context window size. It’s that there’s no structured handoff when quality starts to slip.

The Fix: A `.session_summary.md` File

The idea is simple. Before ending a session (or at any major milestone), you ask your agent to write a summary file — .session_summary.md — in your project’s root directory. This file captures:

What the project is and what you’re trying to accomplish
What was done in this session (with exact file paths and line numbers)
Where work currently stands
What comes next, in priority order
Any running services, ports, or config values to know about
Issues encountered and how they were resolved

Then, next session:

“Read .session_summary.md and resume from where we left off.”

That one line is all it takes. The agent reads the file and has everything it needs.

The Skill File

A “skill” is a Markdown file with a YAML header that defines the skill’s name, description, and triggers. Most modern AI agents — Claude Code, Hermes, Cursor — support this format. You add it once, and the agent knows to generate a properly structured summary whenever you ask.

Here’s what triggers it:

You say “summarize” or “save state” or “help me document”
A complex session is ending with work still in progress
You hit a milestone you want to checkpoint

Download the skill file — save it to your agent’s skills folder, or browse the full repo at hooooolea/agent-skills.

What the Summary Looks Like

Here’s the structure the agent fills in:

# Session Summary — My Project

Created: 2026-05-21 14:32
Last Agent: Claude (claude-sonnet-4-6)

---

## Project Overview
Building a static blog with Astro and deploying via Cloudflare Pages.
Tech stack: Astro v6, Tailwind CSS v4, GitHub Actions CI/CD.

## Current Active Work
Writing a GitHub Trending page at src/pages/trending.astro.
Stopped mid-way through adding language filter buttons.

## Goal
Get the trending page live with time period + language filters working.

## Completed Actions
1. Created trending.astro with basic GitHub Search API integration
   - File: /Users/you/project/src/pages/trending.astro
   - Result: Page renders, API call works

2. Fixed scoped style issue — changed <style> to <style is:global>
   - File: trending.astro
   - Result: Repo cards now render correctly

## Next Steps
1. Add language filter buttons (same pattern as time period buttons)
2. Run prettier before committing — CI format check will fail otherwise
3. Open PR to merge dev → main

## Known Issues
- GitHub API has 60 req/hour anonymous limit — not a problem for now

Clean, specific, and immediately actionable.

Why This Works Better Than Hoping the Agent Remembers

No AI agent persists memory between sessions by default. When you close a chat or start a new agent run, the context window is gone. There’s no background storage, no automatic journaling.

Even within a session, if you’ve noticed quality starting to drift, the right move is often to start a fresh session with a clean context — not to keep pushing into a degraded one. The summary file makes that practical. Fresh context, full information.

Writing a structured file sidesteps the degradation problem entirely. The file lives on your computer, in your project. You control it. You can read it yourself, edit it, or share it. And because it’s just a Markdown file, any agent can read it back instantly at the start of a new session.

The structured format matters too. A freeform “here’s what we did” paragraph is easy to write but hard to parse quickly. The skill enforces specific sections — current state, next steps, known issues — so the new session gets oriented in seconds rather than minutes. This works the same regardless of which agent you use.

A Note on API Keys and Sensitive Data

The skill file explicitly tells the agent never to write actual API keys or credentials into the summary. If a service requires a key to run, the summary notes that a key is needed (and where to set it), but writes [REDACTED] for the value. Keep this in mind if you edit summaries manually — the whole point is that the file might get committed to a repo or shared.

If you try this out and have feedback or improvements, send them to ejuer_z@163.com — I’d like to know what works and what doesn’t for different kinds of projects.