nav-compact

name	nav-compact
description	Clear conversation context while preserving knowledge via context marker. Use when user says "clear context", "start fresh", "done with this task", or when approaching token limits.
allowed-tools	Read, Write, Bash
version	1.0.0

Navigator Compact Skill

Clear your conversation context while preserving all knowledge in a context marker. Like git commit before switching branches - save your state, then start fresh.

When to Invoke

Invoke this skill when the user:

• Says "clear context", "start fresh", "reset conversation"
• Says "I'm done with this task", "moving to next feature"
• Mentions "approaching token limit", "context getting full"
• Says "compact", "clean up context"
• After completing isolated sub-task

DO NOT invoke if:

• User is in middle of implementation
• Context is needed for next immediate step
• Less than 20 messages in conversation (not much to gain)

Execution Steps

Step 1: Check If Worth Compacting

Estimate conversation size:

• If < 20 messages: Suggest waiting
• If 20-50 messages: Safe to compact
• If > 50 messages: Highly recommended

Show message:

📊 Current session: ~[N] messages

Compacting will:
- Create marker with current state
- Clear conversation history
- Free up ~[X]k tokens for new work

Continue? [Y/n]:

Step 2: Create Automatic Marker

Invoke nav-marker skill (or create marker directly) with auto-generated name:

Marker name: before-compact-{YYYY-MM-DD}-{HHmm}
Note: "Auto-created before compact"

This marker should capture:

• Last 10-15 messages summary
• Files modified
• Technical decisions
• Current progress
• Next steps

Step 3: Set Active Marker

Write the marker filename to .active file:

echo "{marker-filename}.md" > .agent/.context-markers/.active

This tells nav-start to offer restoration on next session.

Step 4: Display Compact Instructions

Show user how to compact:

╔══════════════════════════════════════════════════════╗
║                                                      ║
║  🗜️  Navigator Compact                                ║
║                                                      ║
╚══════════════════════════════════════════════════════╝

✅ Context marker created:
   .agent/.context-markers/{marker-filename}.md

📋 Marker contains:
   - Conversation summary (last 15 messages)
   - Files you modified
   - Technical decisions made
   - Current progress & next steps

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔹 TO COMPACT:

Claude Code doesn't allow me to clear the conversation
programmatically. You need to do it manually:

**Method 1: New conversation**
1. Start a new conversation
2. Say "load my context" or "start my session"
3. I'll detect the active marker and restore your state

**Method 2: /clear command** (if available)
1. Type /clear
2. Say "load my context"
3. Active marker will be restored

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Your progress is saved. You won't lose any context.

Next session:
1. Say "start my session" or run /nav:start
2. I'll detect the marker: "{marker-filename}"
3. Confirm to restore, and you'll be back where you left off

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 5: Confirm Marker Location

Verify marker was created:

ls -lh .agent/.context-markers/{marker-filename}.md

Show file size and confirm success:

✅ Marker saved successfully
   File: {marker-filename}.md
   Size: {X} KB (~{Y} tokens)

Your context is preserved!

Important Notes

Why manual compact?

Claude Code conversations cannot be programmatically cleared from within a conversation. The user must:

• Start a new conversation, OR
• Use /clear command (if available)

This skill creates the marker and sets up auto-restoration, but the actual clearing must be done by the user.

Auto-restoration workflow:

Session 1:
  User: "Clear context"
  → nav-compact creates marker
  → Sets .active file
  → Instructs user how to clear

Session 2 (new conversation):
  User: "Start my session"
  → nav-start detects .active file
  → Offers to restore marker
  → User confirms
  → Context restored!

Common Use Cases

After Completing Feature

User: "Feature complete, clear context for next task"
→ Creates marker: "before-compact-2025-10-16-1430"
→ Captures: Feature implementation details
→ User starts new conversation
→ Restores marker, begins next feature

Approaching Token Limit

User: "Context getting full, let's compact"
→ Creates marker: "before-compact-2025-10-16-1500"
→ Preserves: All current work
→ User clears conversation
→ Continues with fresh context

Switching Between Tasks

User: "Done with auth, moving to payments"
→ Creates marker: "auth-feature-complete"
→ Clear context
→ New session: Fresh start for payments
→ Can restore auth marker later if needed

Error Handling

Marker creation fails:

❌ Failed to create marker

Cannot compact without preserving context.
Fix marker creation first.

Not enough context to preserve:

⚠️  Very little context (< 10 messages)

Compacting now won't save much. Consider:
- Continue working
- Compact after more progress

Continue anyway? [y/N]:

Active marker already exists:

⚠️  Active marker already exists:
   .agent/.context-markers/.active

This means you have an unrestored marker from previous compact.

Options:
1. Load that marker first (recommended)
2. Overwrite with new marker
3. Cancel compact

Your choice [1-3]:

Success Criteria

Compact is successful when:

• Context marker created successfully
• Marker contains comprehensive summary
• .active file created (for auto-restoration)
• User knows how to clear conversation
• User knows marker will auto-restore on next session

Scripts

compact.py: Automated compact workflow

• Create marker
• Set active file
• Generate restore instructions

Best Practices

When to compact:

• ✅ After completing isolated feature/sub-task
• ✅ After major documentation update
• ✅ Before switching to unrelated work
• ✅ When approaching 70%+ token usage
• ❌ In middle of implementation
• ❌ When context needed for next step
• ❌ After every few messages (wasteful)

Compact frequency:

• Small task (30 min): No compact needed
• Medium task (2-3 hours): Compact after completion
• Large task (full day): Compact at logical breakpoints
• Multi-day task: Compact at end of each session

Notes

This skill automates the preparation for compacting but cannot clear the conversation itself (Claude Code limitation).

The value is in:

1. Automatic marker creation
2. Setting up auto-restoration
3. Guiding user through process
4. Preserving context seamlessly

This provides same functionality as /nav:compact command but with natural language invocation.