context-extract

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Context Extract Skill

CUMULATIVE context extraction - always appends, never overwrites.

累积式上下文提取 - 始终追加，绝不覆盖。

Triggers

触发词

"extract context"
"save conversation"
"export context"
"dump context"

"extract context"
"save conversation"
"export context"
"dump context"

Core Principle: APPEND ONLY

核心原则：仅追加

Each extraction ADDS to existing context files. This builds a complete project history over time.

每次提取都会添加到现有的上下文文件中，随着时间推移构建完整的项目历史。

Output Structure

输出结构

<project>/.claude/context/
├── HISTORY.md          # Cumulative session log (append-only)
├── DECISIONS.md        # All decisions ever made (append-only)
├── DIRECTIONS.md       # Direction changes and pivots (append-only)
└── archive/            # Old files if manual cleanup needed
    └── HISTORY_pre_YYYY-MM-DD.md

<project>/.claude/context/
├── HISTORY.md          # 累积会话日志（仅追加）
├── DECISIONS.md        # 所有已做出的决策（仅追加）
├── DIRECTIONS.md       # 方向变更与转向（仅追加）
└── archive/            # 需要手动清理时存放旧文件
    └── HISTORY_pre_YYYY-MM-DD.md

Workflow

工作流程

Step 1: Read Existing Context Files

步骤1：读取现有上下文文件

bash

PROJECT=$(basename $(pwd))
CONTEXT_DIR=~/local_workspaces/$PROJECT/.claude/context
TIMESTAMP=$(date +%Y-%m-%d_%H%M)

mkdir -p $CONTEXT_DIR/archive

bash

PROJECT=$(basename $(pwd))
CONTEXT_DIR=~/local_workspaces/$PROJECT/.claude/context
TIMESTAMP=$(date +%Y-%m-%d_%H%M)

mkdir -p $CONTEXT_DIR/archive

Read existing files to understand current state

读取现有文件以了解当前状态

cat $CONTEXT_DIR/HISTORY.md 2>/dev/null || echo "[No history yet]" cat $CONTEXT_DIR/DECISIONS.md 2>/dev/null || echo "[No decisions yet]" cat $CONTEXT_DIR/DIRECTIONS.md 2>/dev/null || echo "[No direction changes yet]"

undefined

cat $CONTEXT_DIR/HISTORY.md 2>/dev/null || echo "[尚无历史记录]" cat $CONTEXT_DIR/DECISIONS.md 2>/dev/null || echo "[尚无决策记录]" cat $CONTEXT_DIR/DIRECTIONS.md 2>/dev/null || echo "[尚无方向变更记录]"

undefined

Step 2: Detect Direction Changes

步骤2：检测方向变更

CRITICAL: Compare what was PLANNED vs what actually HAPPENED.

Check these sources for planned direction:

Previous
```
HISTORY.md
```
"Next Actions" section
```
CONTEXT.md
```
"Resume" section
User's initial request this session

If work diverged from plan, document it in DIRECTIONS.md:

markdown

undefined

关键： 对比计划内容与实际执行内容。

检查以下来源获取计划方向：

之前
```
HISTORY.md
```
中的“下一步行动”部分
```
CONTEXT.md
```
中的“恢复”部分
本次会话中用户的初始请求

如果实际工作与计划偏离，将其记录在DIRECTIONS.md中：

markdown

undefined

Direction Change: YYYY-MM-DD HH:MM

方向变更：YYYY-MM-DD HH:MM

Original Plan: [What was supposed to happen]

What Actually Happened: [What we did instead]

Why the Pivot: [Reason - user request, blocker discovered, better approach found, etc.]

Impact: [What this means for the project going forward]

undefined

原计划： [原本要执行的内容]

实际执行： [实际完成的内容]

转向原因： [原因 - 用户请求、发现障碍、找到更优方案等]

影响： [对项目后续进展的影响]

undefined

Step 3: Append to HISTORY.md

步骤3：追加到HISTORY.md

APPEND a new session block (never replace):

markdown

---

追加新的会话块（绝不替换）：

markdown

---

Session: YYYY-MM-DD HH:MM

会话：YYYY-MM-DD HH:MM

Goal

目标

[What this session aimed to accomplish]

[本次会话要完成的内容]

Accomplished

已完成

Files Changed

修改的文件

```
path/file.ts
```
- [what changed]
```
path/new.ts
```
- NEW: [purpose]

```
path/file.ts
```
- [修改内容]
```
path/new.ts
```
- 新增：[用途]

Commands Run

执行的命令

bash

[key commands only]

bash

[关键命令]

Errors & Solutions

错误与解决方案

Error: [description] Fix: [how resolved]

错误： [描述] 修复： [解决方法]

Next Actions

下一步行动

[Priority 1]
[Priority 2]

[优先级1]
[优先级2]

Notes

备注

[Any context for future sessions]

undefined

[供后续会话参考的上下文信息]

undefined

Step 4: Append to DECISIONS.md

步骤4：追加到DECISIONS.md

APPEND any new decisions (check for duplicates first):

markdown

---

追加任何新决策（先检查是否重复）：

markdown

---

YYYY-MM-DD: [Decision Title]

YYYY-MM-DD: [决策标题]

Context: [Why this decision was needed]

Options Considered:

[Option A] - [pros/cons]
[Option B] - [pros/cons]

Decision: [What was chosen]

Rationale: [Why]

Affected Files: [list]

Reversible: [Yes/No - and how if yes]

undefined

背景： [做出该决策的原因]

考虑的选项：

[选项A] - [优缺点]
[选项B] - [优缺点]

决策： [最终选择]

理由： [选择原因]

影响的文件： [列表]

可撤销： [是/否 - 若是，说明方式]

undefined

Step 5: Append to DIRECTIONS.md (if applicable)

步骤5：追加到DIRECTIONS.md（如适用）

Only add if direction changed from what was planned:

markdown

---

仅当与计划方向发生变更时添加：

markdown

---

YYYY-MM-DD HH:MM: [Pivot Description]

YYYY-MM-DD HH:MM: [转向描述]

Was Planning To: [original plan]

Instead Did: [what happened]

Trigger: [user request / blocker / discovery / better idea]

Old Direction: [brief description of abandoned path]

New Direction: [brief description of new path]

Carryover: [what from old direction still applies]

Abandoned: [what's being dropped]

undefined

原本计划： [原计划内容]

实际执行： [实际完成的内容]

触发因素： [用户请求 / 障碍 / 新发现 / 更优方案]

旧方向： [简要描述已放弃的方向]

新方向： [简要描述新方向]

延续内容： [旧方向中仍适用的部分]

放弃内容： [不再推进的部分]

undefined

Step 6: Git Commit

步骤6：Git提交

bash

cd ~/local_workspaces/$PROJECT

git add .claude/context/

git commit -m "$(cat <<'EOF'
docs(context): Append session context YYYY-MM-DD HH:MM

- Added session to HISTORY.md
- [N] new decisions recorded
- [Direction change noted / No direction change]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

git push origin $(git branch --show-current) 2>/dev/null || echo "Push skipped"

bash

cd ~/local_workspaces/$PROJECT

git add .claude/context/

git commit -m "$(cat <<'EOF'
docs(context): Append session context YYYY-MM-DD HH:MM

- Added session to HISTORY.md
- [N] new decisions recorded
- [Direction change noted / No direction change]

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

git push origin $(git branch --show-current) 2>/dev/null || echo "Push skipped"

Step 7: Confirm

步骤7：确认

Context appended successfully!

HISTORY.md:
  + Session YYYY-MM-DD HH:MM added
  Total sessions: [N]

DECISIONS.md:
  + [N] new decisions added
  Total decisions: [M]

DIRECTIONS.md:
  + Direction change recorded: [title]
  OR
  (no direction change this session)

Git: [commit hash] pushed to origin/main

上下文已成功追加！

HISTORY.md:
  + 已添加会话YYYY-MM-DD HH:MM
  总会话数：[N]

DECISIONS.md:
  + 已添加[N]项新决策
  总决策数：[M]

DIRECTIONS.md:
  + 已记录方向变更：[标题]
  或
  （本次会话无方向变更）

Git: [提交哈希]已推送到origin/main

Direction Change Detection

方向变更检测

Ask yourself before extracting:

What did CONTEXT.md say to do next?
What did the user actually ask for?
Did we do what was planned, or something different?

Common direction changes:

User requested different feature mid-session
Discovered blocker that required pivot
Found better approach than originally planned
Scope change (bigger or smaller)
Priority shift (different feature first)

Always document WHY - future agents need to know the reasoning.

提取前请自问：

CONTEXT.md中指定的下一步是什么？
用户实际请求的是什么？
我们是按计划执行的，还是做了其他事情？

常见的方向变更：

会话中途用户请求不同功能
发现需要转向的障碍
找到比原计划更优的方案
范围变更（扩大或缩小）
优先级转移（先开发不同功能）

务必记录原因 - 未来的Agent需要了解背后的逻辑。

File Size Management

文件大小管理

If HISTORY.md exceeds ~500 lines:

bash

undefined

如果HISTORY.md超过约500行：

bash

undefined

Archive old content

归档旧内容

mv $CONTEXT_DIR/HISTORY.md $CONTEXT_DIR/archive/HISTORY_pre_$(date +%Y-%m-%d).md

Start fresh with reference

以参考内容重新开始

echo "# Project History (continued)

Previous history archived: archive/HISTORY_pre_$(date +%Y-%m-%d).md

" > $CONTEXT_DIR/HISTORY.md

undefined

echo "# 项目历史（续）

之前的历史已归档：archive/HISTORY_pre_$(date +%Y-%m-%d).md

" > $CONTEXT_DIR/HISTORY.md

undefined

Example: Direction Change Entry

示例：方向变更记录

markdown

---

markdown

---

2026-01-19 22:00: Gemini Migration Instead of Voice Improvements

2026-01-19 22:00: 迁移到Gemini而非优化语音功能

Was Planning To: Improve voice input detection and add wake word support

Instead Did: Migrated Council backend from Claude CLI to Gemini API

Trigger: User request - provided detailed migration plan

Old Direction: Voice UX improvements - better mic handling, wake word "Hey Claude"

New Direction: Backend modernization - direct Gemini API, streaming, no subprocess

Carryover: Voice improvements still on roadmap, now lower priority

Abandoned: Nothing permanently - voice work deferred

undefined

原本计划： 优化语音输入检测并添加唤醒词支持

实际执行： 将Council后端从Claude CLI迁移到Gemini API

触发因素： 用户请求 - 提供了详细的迁移计划

旧方向： 语音用户体验优化 - 更好的麦克风处理、唤醒词“Hey Claude”

新方向： 后端现代化 - 直接调用Gemini API、流式传输、无子进程

延续内容： 语音优化仍在路线图中，优先级降低

放弃内容： 无永久放弃 - 语音工作被推迟

undefined

Integration with Other Skills

与其他Skill的集成

Skill	Relationship
`session-save`	Quick ~250 token summary; context-extract is comprehensive history
`onboard`	Reads HISTORY.md and DECISIONS.md for full project context
`synopsis`	Visual snapshot; context-extract is text archive

Skill	关系
`session-save`	快速的约250令牌摘要；context-extract是全面的历史记录
`onboard`	读取HISTORY.md和DECISIONS.md获取完整项目上下文
`synopsis`	可视化快照；context-extract是文本归档

Key Differences from session-save

与session-save的主要区别

Aspect	session-save	context-extract
Size	~250 tokens	Unlimited (cumulative)
Overwrites	Yes (CONTEXT.md)	Never (append only)
Purpose	Quick handoff	Full project memory
Direction tracking	No	Yes
Decision log	No	Yes

维度	session-save	context-extract
大小	约250令牌	无限制（累积式）
是否覆盖	是（覆盖CONTEXT.md）	绝不（仅追加）
用途	快速交接	完整项目记忆
方向追踪	无	有
决策日志	无	有