Project Context Skill

project-context 是一个面向 Codex 的轻量语义工作流 Skill，用 Git 仓库中的分层 Markdown 文档维护项目上下文。

它适合在多台 PC 或多个 Codex 会话之间切换工作：上一台 PC 收尾并推送整个项目，下一台 PC 拉取项目后即可恢复当前阶段、重点、停止位置和下一步。

目录

• 主要功能
• 工作方式
• 项目中生成的结构
• 使用前提
• 安装
• 使用方法
• 多-PC-日常流程
• 设计边界
• 发布到-GitHub
• 更新
• 常见问题

主要功能

Skill 提供五个操作：

操作	用途	是否修改项目文件
init	初始化项目上下文目录和模板	是
resume	在新会话或另一台 PC 上恢复当前现场	否
handoff	工作结束时更新当前状态和最近交接	可能
cleanup	整理重复、过期或放错层级的信息	是
check	检查上下文结构和内容质量	否

核心特点：

• 项目上下文随 Git 仓库同步；
• 不依赖聊天记录、账号记忆或原设备本地状态；
• 按任务选择性读取，不默认加载全部文档；
• init 可重复执行，不应覆盖已有有效内容；
• 没有实质变化时，handoff 可以保持零修改；
• 保留项目已有语言和格式；
• 不自动执行 Git commit、push 或 pull；
• 不需要 Python、Node.js、数据库或额外运行时。

工作方式

Skill 是“操作方法”，项目仓库里的上下文文档是“项目数据”：

project-context Skill
        │
        ├─ 初始化上下文
        ├─ 恢复上下文
        ├─ 整理交接
        ├─ 清理上下文
        └─ 检查质量
                 │
                 ▼
项目 Git 仓库中的 AGENTS.md 和 docs/

这是一个语义工作流 Skill。Codex 会结合当前任务、仓库内容和模型能力理解并执行规则，而不是像传统程序一样依靠严格的参数解析。

建议在写操作后检查 Git diff，再由用户提交和推送整个项目。

项目中生成的结构

执行 $project-context init 后，目标项目通常包含：

project/
├─ AGENTS.md
└─ docs/
   ├─ context/
   │  ├─ overview.md
   │  └─ constraints.md
   ├─ state/
   │  ├─ current.md
   │  └─ handoff.md
   └─ decisions/
      └─ README.md

各文件职责：

• AGENTS.md：项目级入口规则，说明何时恢复或收尾。
• docs/context/overview.md：长期有效的项目目标、范围、组成和术语。
• docs/context/constraints.md：项目自身的长期限制、边界和外部要求。
• docs/state/current.md：当前有效状态、重点、待办、风险和结论。
• docs/state/handoff.md：最近一轮工作现场、停止位置和下一步。
• docs/decisions/：已经确认并会长期影响后续工作的正式决定。
• Git：保存历史版本。

使用前提

• 使用支持本地 Skills 的 Codex；
• 目标项目由 Git 管理；
• 每台需要使用该工作流的 PC 安装一次 project-context；
• 项目代码、资料和上下文仍由项目自己的 Git 仓库同步。

安装

方法一：使用 $skill-installer

可以在 Codex 中提出：

使用 $skill-installer 安装：
https://github.com/PandaDancing/Project-Context-Skill/tree/main/project-context

安装器会从本仓库的 main 分支读取 project-context/ 目录，并将 Skill 安装到 $CODEX_HOME/skills/project-context/。未设置 CODEX_HOME 时，通常使用 ~/.codex/skills/project-context/。安装完成后，在下一轮对话中使用；如果没有立即出现，重启 Codex。

方法二：手动复制

克隆本仓库：

git clone https://github.com/PandaDancing/Project-Context-Skill.git

然后把仓库中的 project-context/ 目录复制到：

$CODEX_HOME/skills/project-context/

未设置 CODEX_HOME 时使用：

~/.codex/skills/project-context/

复制后的目录必须直接包含：

SKILL.md
agents/openai.yaml
references/templates.md
references/quality-rules.md

不要多嵌套一层仓库目录。

方法三：克隆仓库并建立链接

这种方式最适合持续更新：Skill 源码由 Git 管理，Codex 的 Skills 目录只保留一个本地链接。

先克隆本仓库：

git clone https://github.com/PandaDancing/Project-Context-Skill.git

Windows PowerShell

确保用户级 Skills 目录存在：

New-Item -ItemType Directory -Force "$HOME\.codex\skills"

创建目录 Junction：

New-Item -ItemType Junction `
  -Path "$HOME\.codex\skills\project-context" `
  -Target "<仓库克隆目录>\project-context"

Junction 不要求开启 Windows 开发者模式。目标路径应替换为实际绝对路径。

macOS / Linux

mkdir -p "$HOME/.codex/skills"
ln -s "/absolute/path/to/Project-Context-Skill/project-context" \
  "$HOME/.codex/skills/project-context"

验证安装

开启新的 Codex 对话，然后输入：

$project-context check

也可以通过 Codex 的 Skills 列表确认 project-context 是否出现。如果未出现，检查安装层级并重启 Codex。

使用方法

初始化项目

进入需要维护上下文的 Git 项目后：

$project-context init

Skill 会：

1. 检查项目已有的 AGENTS.md 和 docs/。
2. 创建缺失的上下文目录和文件。
3. 保留已有有效内容。
4. 根据仓库材料填写能够确定的信息。
5. 将未知内容标记为“待确认”。

初始化完成后，检查：

git status
git diff

确认无误后再提交。

恢复项目

新会话、切换设备或上下文不足时：

$project-context resume

输出包括：

• 当前阶段；
• 当前重点；
• 上轮停止位置；
• 阻塞或风险；
• 建议下一步。

resume 只读取和总结，不修改项目文件。

工作收尾

结束本轮工作或准备切换 PC 时：

$project-context handoff

Skill 会根据本轮实际结果：

• 更新 docs/state/current.md；
• 重写 docs/state/handoff.md；
• 必要时更新长期背景或约束；
• 必要时记录已经确认的重要决策；
• 清除已经失效的状态。

如果本轮没有实质变化，可以不修改任何文件。

整理上下文

上下文开始重复、混乱或过长时：

$project-context cleanup

Skill 会按文件职责整理当前上下文，把历史版本留给 Git。

检查质量

只检查、不修改：

$project-context check

检查结果使用：

ERROR
WARNING
INFO
PASS

多 PC 日常流程

推荐采用串行工作方式：同一时间只在一台 PC 上继续项目。

PC1

正常工作，结束前执行：

$project-context handoff

然后检查并推送整个项目：

git status
git diff
git add .
git commit -m "chore: hand off project state"
git push

PC2

在干净的工作区拉取同一分支：

git pull

然后恢复：

$project-context resume

项目代码、资料和上下文文档会一起通过 Git 同步。Skill 本身只需在每台 PC 安装一次。

设计边界

第一版刻意保持轻量，不提供：

• 自动 commit、push 或 pull；
• 自动解决 Git 冲突；
• 后台监控或定时运行；
• 完整聊天记录保存；
• 多项目中央数据库；
• 向量知识库；
• 复杂配置文件；
• 项目运行脚本。

Skill 不替代 Git，也不替代用户对最终 diff 的确认。

发布到 GitHub

推荐仓库结构

<仓库根目录>/
├─ README.md
├─ LICENSE                         # 推荐，但不是 Skill 运行必需
└─ project-context/
   ├─ SKILL.md
   ├─ agents/
   │  └─ openai.yaml
   └─ references/
      ├─ templates.md
      └─ quality-rules.md

必须发布

以下文件构成可安装 Skill：

project-context/SKILL.md
project-context/agents/openai.yaml
project-context/references/templates.md
project-context/references/quality-rules.md

仓库根目录的 README.md 用于 GitHub 展示、安装和使用说明，也应发布。

推荐发布

• LICENSE：如果准备公开使用，建议选择许可证，例如 MIT。
• 与 Skill 直接相关的设计说明：可以放在仓库级 docs/ 中，但不是安装必需。

不需要发布

• 本机 .agents/skills/project-context Junction 或符号链接；
• 临时测试目录；
• Python 虚拟环境或依赖缓存；
• Codex 会话记录；
• 密钥、令牌和本机配置；
• 目标项目执行 init 后产生的 AGENTS.md 与 docs/，这些属于各自项目仓库。

当前仓库中的方案讨论文档不是 Skill 运行必需。可以作为设计资料保留，也可以在发布前移入仓库级 docs/。

首次发布示例

在 GitHub 创建一个空仓库，例如：

codex-project-context

本地确认准备发布的文件后：

git status
git add README.md project-context/
git commit -m "feat: add project-context skill"
git branch -M main
git remote add origin https://github.com/<你的 GitHub 用户名>/<仓库名>.git
git push -u origin main

如果同时发布 LICENSE 或设计文档，将它们加入 git add。

发布后，确认以下地址可以访问：

https://github.com/<你的 GitHub 用户名>/<仓库名>/tree/main/project-context

该地址可直接提供给 $skill-installer。

可选：创建首个版本

稳定后可以创建版本标签：

git tag v0.1.0
git push origin v0.1.0

然后在 GitHub Releases 中以 v0.1.0 发布首个版本。

更新

使用 Git 克隆和链接安装

进入仓库目录：

git pull

因为 Skills 目录指向同一份源码，无需再次复制。

使用复制方式安装

拉取新版仓库后，重新复制整个 project-context/ 目录。

使用 $skill-installer 安装

安装器发现目标 Skill 目录已经存在时会停止，避免覆盖。更新前应先备份或移除旧安装，再重新安装；如果本地修改过 Skill，应先保留这些修改。

常见问题

它会同步 Codex 聊天记录吗？

不会。它只维护项目仓库中的结构化上下文文件。

它会自动提交或推送项目吗？

不会。Git 操作由用户检查后执行。

已有 AGENTS.md 会被覆盖吗？

不会。init 只增加或更新带有以下标记的托管区块：

<!-- project-context:start -->
<!-- project-context:end -->

区块外的项目规则应保持不变。

为什么不把所有内容放进 AGENTS.md？

AGENTS.md 只作为稳定入口。项目背景、当前状态、最近交接和历史决策分层保存，可以减少无关上下文加载。

为什么 handoff 有时没有修改文件？

没有实质变化时，零修改就是正确结果。Skill 不会为了形成交接而制造内容。

Skill 未安装时项目还能恢复吗？

可以。初始化后的 AGENTS.md 会提示 Codex直接读取：

docs/state/current.md
docs/state/handoff.md

这可以完成最小恢复。