nav-compact

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)

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:

```bash

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:

```bash

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!

```

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!

```

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

```

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]:

```

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

compact.py: Automated compact workflow

• Create marker
• Set active file
• Generate restore instructions

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

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.