Session Documentation Skill

A Claude Code skill for automatically documenting work sessions into permanent, readable markdown summaries.

Overview

This skill enables Claude Code to proactively create comprehensive session documentation that preserves work, technical decisions, and context for future sessions. Unlike the ephemeral /compact command, this creates permanent markdown artifacts that both humans and future Claude sessions can read.

Features

• Automatic activation when context runs low or user requests documentation
• 6 comprehensive templates for different session types (Infrastructure, Skills, Coding, Debugging, Planning, Configuration)
• Progressive disclosure pattern with lean SKILL.md + detailed reference.md + practical examples.md
• Integration with technical-writer subagent for high-quality documentation generation
• Explicit /document-session command for manual invocation

Installation

User-Level (Recommended)

Install at ~/.claude/skills/ to make available across all Claude Code projects:

cd ~/.claude/skills/
git clone https://github.com/josh-stephens/session-documentation.git

Project-Level

Install in specific project's .claude/skills/ directory:

cd /path/to/your/project
mkdir -p .claude/skills
cd .claude/skills/
git clone https://github.com/josh-stephens/session-documentation.git

Optional: Slash Command

Create the /document-session command for explicit invocation:

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/document-session.md \
  https://raw.githubusercontent.com/josh-stephens/session-documentation/main/document-session.md

Optional: Update CLAUDE.md

Add to your ~/.claude/CLAUDE.md to document the skill:

## Custom Skills

- **session-documentation** (`~/.claude/skills/session-documentation/`) - Document Claude Code sessions to create permanent, readable summaries that preserve work and enable future sessions to pick up where you left off. Automatically activated when context runs low or when asked to document/summarize the session. Use `/document-session` command for explicit invocation.

Usage

Automatic Activation

The skill automatically activates when you:

• Mention "running low on context", "out of context"
• Say "document this session", "summarize our work"
• Ask "can we preserve this?"
• End long sessions (>50 messages) with significant work

Manual Invocation

With slash command:

/document-session

Without slash command:

Can you document this session?

Claude will use the technical-writer subagent to create a comprehensive summary at ./SESSION-SUMMARY.md (or custom location).

File Structure

session-documentation/
├── SKILL.md           # Lean core (~200 lines) - Auto-loaded by Claude
├── reference.md       # Detailed templates for 6 session types
├── examples.md        # 3 complete example summaries
├── document-session.md # Slash command definition (optional)
├── README.md          # This file
└── LICENSE            # MIT License

Templates

The skill provides templates for:

1. Infrastructure & DevOps - SSH setup, server configuration, network setup
2. Skills Creation - Creating or improving Claude Code skills
3. Coding & Development - Building features, implementing APIs
4. Debugging - Troubleshooting bugs, performance issues
5. Planning & Architecture - System design, architecture decisions
6. Configuration & Setup - Development environment, tool configuration

See reference.md for detailed templates.

Examples

See examples.md for three complete example summaries:

• SSH Setup Across Tailscale Fleet (Infrastructure)
• Device Management Skills (Skills Creation)
• Windows SSH Authentication (Debugging)

Advantages Over /compact

Feature	/compact	Session Documentation
Persistence	Ephemeral (conversation only)	Permanent file
Audience	Claude only	Humans + future Claude sessions
Detail level	Minimal (token-efficient)	Comprehensive
Format	Plain text summary	Formatted markdown
Use case	Continue current conversation	Preserve for future reference
Discoverability	Lost when conversation ends	Permanent project artifact

When to Use

✅ Use session-documentation when:

• Context is running low (>50-75% token usage)
• Completing complex multi-task sessions
• Work should be preserved for future reference
• Multiple people might need to understand the work
• Technical decisions or discoveries were made

❌ Use /compact when:

• You just need to reduce tokens in current conversation
• Work is exploratory and doesn't need preservation
• No significant decisions were made
• You want to continue working immediately

Integration with Other Tools

With /compact: Use session documentation first to save work, then use /compact to continue current conversation.

With git: Commit SESSION-SUMMARY.md with related changes to provide context for future code archaeology.

With skills: Document skill creation and design decisions so future sessions can understand skill purpose.

Technical Details

Follows: Anthropic Agent Skills Specification v1.0

Uses: Progressive disclosure pattern (lean SKILL.md, detailed reference.md, practical examples.md)

Activation: Model-invoked based on keywords in YAML frontmatter

Subagent: documentation-generator:technical-writer via Task tool

Token Efficiency: Initial skill load is ~200 tokens, detailed docs loaded only when needed

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes (add templates, improve examples, fix bugs)
4. Test with Claude Code
5. Submit a pull request

License

MIT License - See LICENSE file for details

Related Resources

• Anthropic Skills Specification
• Anthropic Skills Repository
• Claude Code Documentation

Version History

v1.0.0 (2025-10-31)

• Initial release
• 6 session type templates
• 3 complete examples
• Progressive disclosure pattern
• Technical-writer subagent integration

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• See examples.md for usage patterns
• See reference.md for template details

---

Created for Claude Code - Preserve your work, empower future sessions