# Session Distill > Extract project knowledge from the current session into docs/. Keeps docs current, atomic, and indexed. - Skill: `lucastamoios/session-distill` (Agent Skill) - Install (CLI): `npx skillmds@latest add lucastamoios/session-distill` - Raw SKILL.md: https://api.skillmd.com/api/skills/lucastamoios/session-distill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: lucastamoios (https://skillmd.com/u/lucastamoios) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lucastamoios/session-distill --- # Session Distill Extract project-relevant knowledge from the current conversation and persist it into the `docs/` folder. Keeps documentation current, atomic, and organized behind `docs/index.md`. ## Step 1: Relevance check Before doing any work, check if this session produced knowledge worth distilling. Look for: - Files created or modified in the project - Architecture or design decisions discussed - Rationale given for choices (why X over Y) - New components, patterns, or gotchas discovered - Infrastructure or deployment configured - Existing docs now outdated due to session work If none apply (quick config tweak, question-only session, non-project work), skip silently. Do not announce that you're skipping. ## Step 2: Extract knowledge atoms Scan the conversation and produce a mental list of **knowledge atoms** - self-contained facts worth persisting. For each atom, note: - **Topic** (e.g., "webhook routing", "dev environment setup") - **Type**: architecture, decision, gotcha, infrastructure, or component - **Action needed**: create new doc, update existing doc, or remove outdated content ### What to extract | Type | What to look for | |------|-----------------| | architecture | How components connect, data flow, system boundaries, protocols | | decision | Choices made and WHY (e.g., "Django over FastAPI - company tech stack") | | gotcha | Non-obvious behavior, workarounds, things that caused trouble | | infrastructure | Deployment, tunnels, docker, secrets management, dev environment | | component | New modules - purpose, interface, how to use them | ### What to ignore - Code already in the codebase (code documents itself) - Debugging steps that led nowhere - Transient state (PIDs, temp files, session-specific URLs, port numbers that might change) - Things already in CLAUDE.md or Claude memory files - Conversation mechanics ("let me check that", "running tests") - Implementation details that are obvious from reading the code ## Step 3: Check for skill impacts Before touching docs, scan the session for changes that might affect existing skills in `.claude/skills/`. Look for: - **Changed conventions** - naming patterns, commit rules, separator formats, file structures that a skill might reference or assume - **New tools or workflows** - if the session introduced a new library, framework, or workflow pattern that a skill should use or know about - **Changed processes** - if an implementation flow, review process, or deployment pipeline changed in a way that contradicts what a skill currently describes - **New capabilities** - if something was built that could enhance an existing skill (e.g., a new helper that a coding skill should use) For each potential skill impact, **ask the user** before making any changes: > "This session changed [X]. The skill [skill-name] currently assumes [Y]. Should I update it?" Do NOT update skills without explicit approval. Skills are shared across all projects and sessions - silent changes can have unintended effects. If no skill impacts are found, move on silently. ## Step 4: Reconcile with existing docs Read `docs/index.md` (if it exists) to understand what documentation already exists. For each knowledge atom: 1. **Find the right file** - check if an existing doc covers the topic 2. **If a doc exists** - read it, update the relevant section. If the file now covers clearly separate topics, split it into focused files. 3. **If no doc exists** - create a new file. One focused topic per file. 4. **If content is outdated** - remove it. Delete the file if entirely obsolete. 5. **Flag stale planning docs** - if the session completed the last task of a plan, note that the plan/design/requirements files should be graduated (the `/code-tdd` skill's Step 8 handles the actual graduation). If `/code-tdd` was not used, flag the stale docs to the user and ask if they want you to graduate them now. ### Doc conventions - **Atomic files** - one focused topic per file. Prefer small and focused over large and mixed. - **Mermaid.js** for ALL diagrams - never ASCII art. Use ```mermaid fenced blocks. - **Hyphens** (-) instead of em-dashes in all text. - **Subdirectories** are fine when a topic has multiple related files (e.g., `docs/github/`). - **No fluff** - write for an AI that needs facts, not prose. Lead with the what, then the why. Skip introductions and summaries. ## Step 5: Rebuild docs/index.md After all changes, rebuild `docs/index.md` as a structured list of every doc file, grouped by category: ```markdown # Documentation Index ## Architecture - [System Overview](architecture.md) - Components, data flow, Temporal workflows ## Development - [Dev Environment](dev-environment.md) - 1Password setup, SSH tunnel, justfile ## Reference - [Key Files](key-files.md) - Task-to-file navigation - [Gotchas](gotchas.md) - Non-obvious patterns and pitfalls ``` Categories emerge from the content - don't force a fixed structure. Each entry has the file link and a one-line description (under 80 chars). The index must include ALL .md files in docs/ (recursively), excluding any working artifacts (plans/specs) that are still pending. ## Step 6: Verify After writing, do a quick check: - Every file listed in `docs/index.md` actually exists - No orphan docs (files in docs/ not listed in the index) - No broken Mermaid diagrams (valid syntax) - No em-dashes anywhere - CLAUDE.md has the instruction to read `docs/index.md` when context is needed ## Important notes - Be efficient with token usage - don't read files you don't need to update. - Don't announce what you're doing step by step. Just do the work and report what changed at the end. - Report format: a short list of files created, updated, or removed. Nothing more.