| 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:
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:
- Automatic marker creation
- Setting up auto-restoration
- Guiding user through process
- Preserving context seamlessly
This provides same functionality as /nav:compact command but with natural language invocation.
