context-extract_skill

Overview

This skill appends conversation context into a cumulative project history and never overwrites existing records. It builds and maintains append-only HISTORY.md, DECISIONS.md, and DIRECTIONS.md inside a project's .claude/context directory to preserve a complete session log and rationale over time. The output supports reproducibility, audits, and future agent onboarding.

How this skill works

On each invocation the skill reads existing context files, compares planned actions to what actually happened, and appends a formatted session block to HISTORY.md. If new decisions or pivots occurred it appends structured entries to DECISIONS.md and DIRECTIONS.md respectively. It can archive oversized histories and commits the updated context to Git for traceability.

When to use it

• After each interactive session where work progressed or decisions were made
• When you need a durable, chronological project memory that accumulates over time
• Before handing work to another developer, agent, or onboarding process
• When a pivot or design decision must be recorded for future reference
• Prior to releases or show-and-tell to capture what changed and why

Best practices

• Always read existing HISTORY.md, DECISIONS.md, and DIRECTIONS.md before appending to avoid duplicate decision entries
• Compare planned next actions vs actual work to detect and document pivots
• Keep session blocks concise: goal, accomplishments, files changed, commands run, errors & fixes, next actions
• Append decisions with context, options considered, rationale, affected files, and whether the decision is reversible
• Archive HISTORY.md when it grows too large and start a new file with a reference to the archive

Example use cases

• Run after a 30–60 minute coding session to capture what was done, files changed, and next steps
• Record a design pivot mid-sprint so future contributors understand why priorities shifted
• Append a new decision when choosing a library or architecture and include alternatives considered
• Archive long histories before a major release to keep context files manageable
• Integrate with onboarding so new agents read the full cumulative project memory before acting