capturing-session-learnings

Capture session learnings into AGENTS.md or CLAUDE.md instruction files.

Updated Mar 18, 2026
One-click install
npx skills add https://github.com/pgoell/pgoell-claude-tools --skill capturing-session-learnings-pgoell
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: capturing-session-learnings
Source: https://github.com/pgoell/pgoell-claude-tools/tree/main/plugins/agent-system-management/skills/capturing-session-learnings
Command: npx skills add https://github.com/pgoell/pgoell-claude-tools --skill capturing-session-learnings-pgoell

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Useful context discovered during a coding session—commands, conventions, environment quirks—is lost when the session ends, forcing the agent to rediscover it next time. This Skill reviews the current session and proposes concise, scoped additions to the right agent-instruction file. ## Core Features & Use Cases - Session Reflection: Identifies missing context such as bash commands, code style patterns, testing approaches, and tool preferences encountered during the session. - Scoped File Routing: Discovers AGENTS.md, CLAUDE.md, and local variants, dedupes symlinked files via realpath, and classifies each learning as project-shared, project-local, or user-global. - Approval-Gated Edits: Drafts one-line additions with reasons, shows them grouped by target file as diffs, and applies only user-approved changes to the canonical realpath. - Use Case: After a debugging session where you learned the project requires pnpm test -- --run instead of npm test, invoke the skill to record that command in the project's AGENTS.md so future sessions use it directly. ## Quick Start Ask the agent to review this session and capture anything it learned into the appropriate AGENTS.md or CLAUDE.md file.

Frequently Asked Questions about capturing-session-learnings

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I save session learnings to AGENTS.md or CLAUDE.md?

Invoke the skill at the end of a session; it reflects on missing context, drafts one-line additions, and shows them as diffs grouped by target file. Only the edits you approve are applied to the canonical file path.

How does the skill decide between project and user-global instruction files?

Each learning is classified by scope: team-wide conventions go to project AGENTS.md or CLAUDE.md, personal project overrides go to local variants, and cross-project preferences go to ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md.

Does this work with both Claude Code and Codex?

Yes. The skill includes a platform adaptation table mapping actions like file search, reading, and editing to Claude Code tools (Glob, Read, Edit) and Codex equivalents (shell, apply_patch), so the host agent uses its own tool inventory.

How are symlinked AGENTS.md and CLAUDE.md files handled?

Discovered paths are resolved with realpath and deduplicated, so symlinked pairs are treated as one logical file. Edits target only the canonical realpath, and symlinks update automatically.

What kinds of learnings should not be captured?

Avoid verbose explanations, obvious information, and one-off fixes unlikely to recur. Prohibitions should include the reason or preferred alternative, and rules already present in the user-global file should not be duplicated project-locally.