/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 0: Detect PreCompact Hook (Fast Path) [v6.10.0+]

**Before doing anything else**, check whether the project has the PreCompact hook installed.

HAS_HOOK=$(grep -l "nav_pre_compact" .claude/settings.json .claude/settings.local.json 2>/dev/null | head -1)

**If the hook is present**:

→ **Fast path activated**. The `PreCompact` hook will write the marker automatically when the user runs `/compact` (or when Claude Code auto-compacts). Skip Steps 2–5 (marker creation + `.active` writing) — the hook owns those. Just print:

╔══════════════════════════════════════════════════════╗
║  🗜️  Navigator Compact (hook-managed)                 ║
╚══════════════════════════════════════════════════════╝

✅ PreCompact hook is installed — Navigator will write the
   marker automatically when you run /compact.

Auto-compact is also covered: when Claude Code compacts
silently near the context limit, the hook still fires and
writes a marker tagged with `-auto-` in the filename.

Just run:    /compact

The PostCompact hook will append Claude Code's official
summary to the marker once compact finishes. On your next
session, "Start my Navigator session" picks up the marker
via .active and offers restore.

That's it. Don't create a duplicate marker — the hook handles it deterministically.

**If the hook is absent** (legacy project, manually disabled, or pre-v6.10 install):

→ **Legacy path**. Execute Steps 1–5 below as documented. Manual marker creation, then user runs `/compact`.

---

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

##