nav-compact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

清除对话上下文，同时将所有知识保留在上下文标记中。就像切换分支前执行git commit一样——保存当前状态，然后重新开始。

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)

在以下情况调用此技能：

用户说“清除上下文”、“重新开始”、“重置对话”
用户说“我完成了这个任务”、“切换到下一个功能”
用户提到“接近token限制”、“上下文已满”
用户说“压缩”、“清理上下文”
完成独立子任务后

请勿调用的情况：

用户正在进行实现工作的过程中
下一步需要当前上下文
对话消息少于20条（收益不大）

Execution Steps

执行步骤

Step 1: Check If Worth Compacting

步骤1：检查是否值得压缩

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

估算对话规模：

若少于20条消息：建议等待
若20-50条消息：可以安全压缩
若超过50条消息：强烈建议压缩

显示以下消息：

📊 当前会话：~[N]条消息

压缩将：
- 创建包含当前状态的标记
- 清除对话历史
- 释放约[X]k tokens用于新工作

是否继续？[Y/n]:

Step 2: Create Automatic Marker

步骤2：创建自动标记

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

调用

nav-marker

技能（或直接创建标记），使用自动生成的名称：

标记名称：before-compact-{YYYY-MM-DD}-{HHmm}
备注："自动创建于压缩前"

此标记应包含：

最后10-15条消息的摘要
修改过的文件
技术决策
当前进度
下一步计划

Step 3: Set Active Marker

步骤3：设置活跃标记

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.

将标记文件名写入

.active

文件：

bash

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

这会让

nav-start

在下次会话时提供恢复选项。

Step 4: Display Compact Instructions

步骤4：显示压缩说明

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

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

向用户展示如何压缩：

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

✅ 已创建上下文标记：
   .agent/.context-markers/{marker-filename}.md

📋 标记包含：
   - 对话摘要（最后15条消息）
   - 您修改过的文件
   - 已做出的技术决策
   - 当前进度与下一步计划

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

🔹 压缩操作步骤：

Claude Code不允许在对话内通过编程方式清除对话。您需要手动执行：

**方法1：新建对话**
1. 开启新对话
2. 说“加载我的上下文”或“启动我的会话”
3. 我会检测到活跃标记并恢复您的状态

**方法2：使用/clear命令**（若可用）
1. 输入/clear
2. 说“加载我的上下文”
3. 活跃标记将被恢复

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

💡 您的进度已保存，不会丢失任何上下文。

下次会话：
1. 说“启动我的会话”或运行/nav:start
2. 我会检测到标记："{marker-filename}"
3. 确认恢复后，您将回到之前的状态

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

Step 5: Confirm Marker Location

步骤5：确认标记位置

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!

验证标记已创建：

bash

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

显示文件大小并确认成功：

✅ 标记保存成功
   文件：{marker-filename}.md
   大小：{X} KB（约{Y} tokens）

您的上下文已被保留！

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!

为何需要手动压缩？

Claude Code无法在对话内通过编程方式清除对话。用户必须：

开启新对话，或者
使用/clear命令（若可用）

此技能会创建标记并设置自动恢复，但实际的清除操作必须由用户手动完成。

自动恢复工作流：

会话1：
  用户：“清除上下文”
  → nav-compact创建标记
  → 设置.active文件
  → 指导用户如何清除对话

会话2（新对话）：
  用户：“启动我的会话”
  → nav-start检测到.active文件
  → 提供恢复标记的选项
  → 用户确认
  → 上下文已恢复！

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

用户：“功能已完成，清除上下文以进行下一个任务”
→ 创建标记："before-compact-2025-10-16-1430"
→ 记录：功能实现细节
→ 用户开启新对话
→ 恢复标记，开始下一个功能

Approaching Token Limit

接近Token限制时

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

用户：“上下文已满，我们来压缩一下”
→ 创建标记："before-compact-2025-10-16-1500"
→ 保留：所有当前工作内容
→ 用户清除对话
→ 使用全新上下文继续工作

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

用户：“完成认证模块，切换到支付模块”
→ 创建标记："auth-feature-complete"
→ 清除上下文
→ 新会话：为支付模块重新开始
→ 之后若需要可恢复认证标记

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

标记创建失败：

❌ 标记创建失败

无法在不保留上下文的情况下进行压缩。
请先修复标记创建问题。

可保留的上下文不足：

⚠️ 上下文极少（<10条消息）

现在压缩不会节省太多资源。建议：
- 继续工作
- 取得更多进展后再压缩

是否仍要继续？[y/N]:

已存在活跃标记：

⚠️ 已存在活跃标记：
   .agent/.context-markers/.active

这意味着您有一个来自上次压缩的未恢复标记。

选项：
1. 先加载该标记（推荐）
2. 用新标记覆盖
3. 取消压缩

请选择[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

压缩成功的条件：

上下文标记创建成功
标记包含全面的摘要
已创建.active文件（用于自动恢复）
用户知晓如何清除对话
用户知晓标记将在下次会话时自动恢复

Scripts

脚本

compact.py: Automated compact workflow

Create marker
Set active file
Generate restore instructions

compact.py：自动化压缩工作流

创建标记
设置活跃文件
生成恢复说明

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

何时压缩：

✅ 完成独立功能/子任务后
✅ 完成重大文档更新后
✅ 切换到不相关的工作前
✅ 当token使用率接近70%及以上时
❌ 正在进行实现工作的过程中
❌ 下一步需要当前上下文时
❌ 每几条消息后就压缩（浪费资源）

压缩频率：

小型任务（30分钟）：无需压缩
中型任务（2-3小时）：完成后压缩
大型任务（全天）：在合理的断点处压缩
多日任务：每个会话结束后压缩

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.

此技能可自动完成压缩的准备工作，但无法自行清除对话（Claude Code限制）。

其价值在于：

自动创建标记
设置自动恢复
指导用户完成流程
无缝保留上下文

此技能提供与/nav:compact命令相同的功能，但支持自然语言调用。