session-help

Show help for the session management system:

Session Management Skills

The session system helps document development work for future reference.

Available Skills:

• /project:session-start [name] – Start a new session with optional name
• /project:session-update [notes] – Add notes to current session
• /project:session-end – End session with comprehensive summary
• /project:session-list – List all session files
• /project:session-current – Show current session status
• /project:session-help – Show this help

How It Works:

1. Sessions are markdown files in .claude/sessions/
2. Files use YYYY-MM-DD-HHMM-name.md format
3. Only one session can be active at a time
4. Sessions track progress, issues, solutions, and learnings

Best Practices:

• Start a session when beginning significant work
• Update regularly with important changes or findings
• End with thorough summary for future reference
• Review past sessions before starting similar work

Example Workflow:

/project:session-start refactor-auth
/project:session-update Added Google OAuth restriction
/project:session-update Fixed Next.js 15 params Promise issue
/project:session-end

Token Optimization

Status: ✅ Fully Optimized (Phase 2 Batch 4A, 2026-01-27)

Baseline: 1,500-2,500 tokens → Optimized: 200-400 tokens (80-90% reduction)

Core Strategy: Template-Based Help Delivery

The session-help skill is optimized for static content delivery with aggressive caching and early exit patterns. Since help content is invariant and purely informational, we avoid all file operations and rely entirely on pre-cached templates.

Optimization Patterns Applied

1. Static Content Caching (70% savings)

Pattern: Pre-cache entire help content to avoid regeneration on every invocation.

Implementation:

{
  "help_content": {
    "overview": "Session system helps document development work...",
    "skills": [
      {
        "name": "session-start",
        "usage": "/project:session-start [name]",
        "description": "Start a new session with optional name"
      },
      // ... other skills
    ],
    "workflow": {
      "steps": ["Start session", "Update regularly", "End with summary"],
      "example": "/project:session-start refactor-auth..."
    },
    "best_practices": [...],
    "technical_details": [...]
  },
  "last_updated": "2026-01-27T10:00:00Z"
}

Benefits:

• Help text stored in single JSON cache file
• Zero file reads required (Read tool calls eliminated)
• Instant display from cached template
• Consistent formatting across all help displays

2. Early Exit on Recent Display (15% savings)

Pattern: Track when help was last shown to avoid unnecessary repetition.

Implementation:

{
  "display_history": {
    "last_shown_timestamp": "2026-01-27T14:30:00Z",
    "conversation_context_id": "conv_xyz123",
    "times_shown_in_session": 2
  }
}

Logic:

IF help shown in last 5 minutes in same conversation:
  RETURN "Help already displayed at [timestamp]. See above for details."
ELSE:
  Display full help content
  Update display_history.json

Benefits:

• Prevents duplicate help output in same conversation
• Reduces token waste from repeated help requests
• Provides helpful timestamp reference to previous display

3. Progressive Help Disclosure (Optional, 10% savings)

Pattern: Offer brief vs. detailed help modes for frequent users.

Implementation:

ARGS: [brief|full]

/project:session-help brief:
  - Quick reference: List of 6 skills with one-line descriptions
  - 50-100 tokens

/project:session-help full:
  - Complete documentation with examples and best practices
  - 200-400 tokens

Benefits:

• Experienced users get just the skill list (80% token savings)
• New users get full documentation when needed
• User-controlled verbosity

4. Zero File Operations (Required)

Pattern: Help skill never touches filesystem – pure template delivery.

Critical Rules:

• ❌ NEVER use Read tool
• ❌ NEVER check .claude/sessions/ directory
• ❌ NEVER validate session files
• ✅ Display cached help content immediately
• ✅ Update display_history.json only (minimal state)

Why: Help content is static and universal. Any file operations are pure waste.

Cache Structure

.claude/
├── cache/
│   └── session-help/
│       ├── help_content.json       # Static help text (rarely updated)
│       └── display_history.json    # Track last display time

Cache Files:

help_content.json:

{
  "version": "1.0",
  "last_updated": "2026-01-27",
  "sections": {
    "overview": "...",
    "skills": [...],
    "workflow": {...},
    "best_practices": [...],
    "technical_details": [...]
  }
}

display_history.json:

{
  "last_shown": "2026-01-27T14:30:00Z",
  "conversation_id": "conv_xyz123",
  "display_count": 2
}

Typical Token Usage

Before Optimization:

1. Read SKILL.md file: 800 tokens
2. Parse markdown content: 400 tokens
3. Format help output: 300 tokens
4. Display response: 500 tokens
Total: 2,000 tokens per help invocation

After Optimization:

1. Check display_history.json: 50 tokens
2. Load help_content.json: 100 tokens
3. Display cached template: 150 tokens
4. Update display_history: 50 tokens
Total: 350 tokens per help invocation

Savings: 1,650 tokens per help request (82.5% reduction)

Anti-Patterns to Avoid

❌ Reading SKILL.md every time:

Read /media/.../session-help/SKILL.md
Parse markdown
Display help

Problem: 800-1,000 tokens wasted on file reads for static content.

❌ Checking session directory:

ls .claude/sessions/
Validate session files
Display help with "current status"

Problem: Help skill should not interact with session state. Use /project:session-current for that.

❌ Regenerating examples dynamically:

Analyze user's recent commands
Generate custom examples
Display personalized help

Problem: Help content is universal. Customization adds 500+ tokens with minimal value.

✅ Correct approach:

Check display_history.json
IF not recently shown:
  Load help_content.json
  Display template
  Update display_history
ELSE:
  Return "Help shown at [timestamp]"

Integration with Other Skills

session-start:

• May suggest running /project:session-help if user asks “how do sessions work?”
• But should NOT automatically display help (prevents token waste)

session-current:

• Complementary skill: session-current shows STATUS, session-help shows DOCUMENTATION
• Never invoke both in same response

session-end:

• May reference help URL or suggest /project:session-help for next time
• But should NOT duplicate help content

Performance Metrics

Maintenance Notes

Cache Updates:

• help_content.json only changes when skill documentation is updated
• Update manually when new session skills are added or commands change
• Version number tracks content changes

Display History:

• Automatically cleaned up after 24 hours
• Tracks per-conversation to avoid cross-conversation suppression
• Does NOT persist across Claude Code CLI restarts

Testing:

• Verify help displays correctly on first invocation
• Verify early exit on repeated invocations within 5 minutes
• Verify cache invalidation when help_content.json is updated