Skip to content
BranchesTags

Repository files navigation

Save Progress Skill

简体中文 | English | 日本語

一个同时支持 OpenAI Codex 和 Claude Code 的会话续接 Skill。

English: Create a verified CONTINUE.md handoff checkpoint while preserving manual notes and protecting secrets.

日本語: 手動メモを保持し、機密情報を保護しながら、検証済みの CONTINUE.md 引き継ぎチェックポイントを作成します。

结束长会话前运行：

  • Codex：$save-progress
  • Claude Code 独立安装：/save-progress
  • Claude Code 插件安装：/save-progress:save-progress

Skill 会检查真实仓库状态并在项目根目录创建或更新 CONTINUE.md，让一个完全没有旧会话上下文的新会话可以直接接手。

Save the project state, not the chat transcript.

为什么需要它

普通的“总结一下当前对话”很容易遗漏：

  • 未提交、已暂存和未跟踪文件；
  • 当前分支、commit 和 worktree 状态；
  • 哪些功能真的验证过，哪些只是写完了；
  • 已失败的方案以及失败原因；
  • 新会话第一步到底应该做什么；
  • 测试、构建和命令的真实结果；
  • Codex 的 AGENTS.md 约束或 Claude Code 的 CLAUDE.md / .claude/rules 约束。

save-progress 以代码、Git 状态和实际命令结果为依据，而不是只依赖聊天记忆。

核心输出

Skill 会在项目根目录创建或更新：

CONTINUE.md

它包含：

  • 当前任务、交付物和完成标准；
  • 已实现并验证、已实现未验证、部分完成和未开始的内容；
  • 卡点、未知项和已尝试方案；
  • 带验收标准的下一步行动；
  • 技术决策和原因；
  • 不要重复踩的坑；
  • Git、worktree、未提交文件和远端状态；
  • 已运行、失败及未运行的验证；
  • 重要文件、环境变量名称和启动方式；
  • 可以直接复制到 Codex 或 Claude Code 新会话的接管提示词。

手工写入以下区块的内容会在下一次刷新时原样保留：

<!-- continue:manual-notes:start -->
你的人工备注
<!-- continue:manual-notes:end -->

仓库结构

.
├── .codex-plugin/
│   └── plugin.json
├── .agents/plugins/
│   └── marketplace.json
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── skills/save-progress/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── assets/CONTINUE.template.md
│   └── scripts/
│       ├── render_continue.py
│       └── validate_continue.py
├── examples/
│   ├── AGENTS.md.snippet
│   └── CLAUDE.md.snippet
├── tests/
├── README.en.md
├── README.ja.md
├── CHANGELOG.md
├── LICENSE
└── README.md

核心工作流只维护在一份 skills/save-progress/SKILL.md 中。Codex 和 Claude Code 都读取这份 Skill，避免两套提示词逐渐不一致。

Codex 安装

方式一：用户级独立 Skill

macOS / Linux：

git clone https://github.com/xiaomihu1992/save-progress-skill.git
mkdir -p ~/.agents/skills
ln -s "$(pwd)/save-progress-skill/skills/save-progress" ~/.agents/skills/save-progress

或者直接复制：

cp -R save-progress-skill/skills/save-progress ~/.agents/skills/save-progress

重新启动 Codex，然后运行：

$save-progress

方式二：Codex Plugin

本仓库包含 .codex-plugin/plugin.json 和 .agents/plugins/marketplace.json。上传 GitHub 后添加 marketplace：

codex plugin marketplace add xiaomihu1992/save-progress-skill

然后在 Codex 中打开 /plugins，从 save-progress-marketplace 安装并启用 save-progress。安装后开启新会话，再运行：

$save-progress

Claude Code 安装

方式一：用户级独立 Skill（命令最短）

macOS / Linux：

git clone https://github.com/xiaomihu1992/save-progress-skill.git
mkdir -p ~/.claude/skills
ln -s "$(pwd)/save-progress-skill/skills/save-progress" ~/.claude/skills/save-progress

或者直接复制：

cp -R save-progress-skill/skills/save-progress ~/.claude/skills/save-progress

Claude Code 会把目录名注册为 slash command：

/save-progress

方式二：项目级独立 Skill

将目录复制到项目中：

mkdir -p .claude/skills
cp -R /path/to/save-progress-skill/skills/save-progress .claude/skills/save-progress

提交 .claude/skills/save-progress/ 后，该项目中的协作者都可以使用：

/save-progress

方式三：Claude Code Plugin / Marketplace

添加 GitHub 仓库作为 marketplace：

claude plugin marketplace add xiaomihu1992/save-progress-skill

安装插件：

claude plugin install save-progress@save-progress-marketplace

也可以在 Claude Code 中运行：

/plugin install save-progress@save-progress-marketplace

插件 Skill 会自动带命名空间：

/save-progress:save-progress

本地发布前测试：

claude --plugin-dir ./save-progress-skill

进入 Claude Code 后运行：

/save-progress:save-progress

使用方法

结束长会话

Codex：

$save-progress

Claude Code 独立 Skill：

/save-progress

Claude Code Plugin：

/save-progress:save-progress

也可以附加要求：

$save-progress 重点记录当前数据库迁移的风险，以及哪些测试还没运行。

/save-progress 重点记录当前数据库迁移的风险，以及哪些测试还没运行。

开启新会话

完整阅读 CONTINUE.md，然后阅读当前代理适用的项目指令文件：
Codex 读取 AGENTS.md / AGENTS.override.md；
Claude Code 读取 CLAUDE.md、CLAUDE.local.md 和 .claude/rules/*.md。
重新检查仓库根目录、分支、commit、worktree 和 git status。
如果交接文档与当前代码不一致，以代码和命令结果为准并更新 CONTINUE.md。
不要重复“Failed approaches and pitfalls”中的失败方案。
从“Next actions”的第一项开始执行，并按验收标准验证。

推荐加入项目指令文件

这样新会话会优先读取 CONTINUE.md，但生成交接快照仍然需要显式调用 Skill。

为什么禁止隐式触发

生成 CONTINUE.md 会修改项目文件，不应该因为一句普通的“总结一下”就自动触发：

  • Codex 通过 agents/openai.yaml 的 allow_implicit_invocation: false 禁止隐式调用；
  • Claude Code 用户应显式运行 /save-progress 或 /save-progress:save-progress；Skill description 同时明确排除普通总结和状态问题。

安全渲染与校验

Skill 先在系统临时目录起草候选文件，再使用确定性渲染器保留原有人工备注并原子写入：

python3 /absolute/path/to/skills/save-progress/scripts/render_continue.py \
  /absolute/path/to/temporary-candidate.md \
  /absolute/path/to/project-root/CONTINUE.md \
  --project-root /absolute/path/to/project-root

随后独立校验最终文件：

python3 /absolute/path/to/skills/save-progress/scripts/validate_continue.py \
  /absolute/path/to/project-root/CONTINUE.md \
  --project-root /absolute/path/to/project-root

渲染器和校验器会检查：

  • 必需结构标记是否齐全且顺序正确；
  • 必需章节、元数据、第一步行动和验证信息是否真正填写；
  • 人工备注是否逐字保持；
  • 目标是否为项目根目录中的普通 CONTINUE.md 文件，而不是符号链接；
  • 是否存在明显占位符；
  • 是否疑似包含 Token、私钥、Bearer Header、密码或带凭据 URL；
  • 密钥检测结果只报告类型和行号，不回显任何命中内容。

如果原有人工备注包含疑似密钥，渲染器会拒绝覆盖并保持原文件不变，等待用户手工脱敏。自动检测仍不能替代人工安全检查。

Codex Plugin 使用 ${PLUGIN_ROOT}/skills/save-progress；Claude Code Plugin 使用 ${CLAUDE_PLUGIN_ROOT}/skills/save-progress 定位脚本。

测试

python3 -m unittest discover -s tests -v

测试覆盖空模板拒绝、合法快照、密钥漏报和回显、中文/日文内容、人工备注保持、无效候选文件、符号链接、目录越界及多平台版本同步。GitHub Actions 会在 push 和 pull request 时运行同一套测试。

设计原则

  1. 代码和命令结果优先于聊天记忆。
  2. 已完成不等于已验证。
  3. 交接文档是当前快照，不是永久规范。
  4. 记录失败原因，而不是只写“不要这样做”。
  5. 下一步必须可以立即执行，并有验收标准。
  6. 只记录环境变量名称，不记录值。
  7. 默认只修改 CONTINUE.md。
  8. Codex 与 Claude Code 共用同一份工作流。

发布维护

当前版本为 1.2.0。每次发布新版本时，请同步更新 Codex 和 Claude Code manifest 的版本号，运行完整测试，并重新生成发布包与 SHA-256 校验文件。

License

MIT

About

Verified CONTINUE.md checkpoints for Codex and Claude Code sessions

Topics

agent-skillsclaude-codecodexdeveloper-toolssession-continuity

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages