agents-context-management

Agent 上下文管理

如果这些说明已通过斜杠或美元符号调用出现在对话中，请直接遵循； 不要通过技能工具再次调用此技能。

将仓库本地上下文创建或完善为一个连贯的系统：面向人的 README.md 文件、面向 Agent 的 AGENTS.md 文件 及其配套的 CLAUDE.md 符号链接、.agents/skills 下已安装到项目中的技能，以及上下文文档——即任何其他名称或目录下的 Markdown 文件，只要其内容是面向 Agent 或人的持久指南，例如约定、命令目录、数据格式规则、工作流操作手册和参考资料。

成功意味着每个选定目标都有仓库证据作为依据，符合其受众和范围，只将 Agent 上下文用于会改变行为的指南，并通过 仓库定义的最精简验证。完成或计划的更改、验证情况及任何阻碍报告完毕后，即停止。

模型与上下文优化

针对 GPT-5.6 和 Claude Fable 5 优化技能及其他面向 Agent 的上下文，同时确保 README.md 清晰易读，面向人类。 在进行复杂、长时间运行、多工具或涉及大量编排的上下文工作之前，请阅读最新版的 GPT-5.6 提示指南和 Claude Fable 5 提示指南，因为其中的建议可能会变化。

• 仅保留会改变决策、防止有证据表明曾发生的错误，或提供无法通过其他方式发现的约束的面向 Agent 的内容。移除通用建议、教程、历史、清单、无实际作用的文字，以及脚本、操作配方、架构或配置已强制执行的机制。
• 在有效加载链中，每个含义只说明一次。将共享指南放在父级，子级只保留增量或覆盖内容；如果文档会独立加载且需要保持自包含，则保留重复内容。
• 使用范围最窄且可靠的加载位置：通用指南直接内嵌，特定路径的指南放入嵌套上下文，少见流程放入按需查阅的上下文文档或技能。不要将必需指南藏在不可靠的引用之后。
• 优先使用一条正向决策规则，而不是罗列禁令。仅在示例说明精确要求或纠正已测得的错误时，才保留一个最简示例；仅当工具和命令的说明涉及路由、输入、副作用、输出或失败信号时，才予以保留。
• 保留权威性、安全性、实质性例外、语义成功标准、精确的机器读取文本和易读的文字。除非 README.md 的内容也会进入 Agent 上下文，否则不要仅为减少 Agent 令牌数而缩短面向人的 README.md 内容。
• 仅限文档的授权并不允许创建或更改辅助工具或架构。如果不存在此类内容，应保留最精简且准确的文字，并报告可提取为文档的机会，而不是扩大工作范围。

选择工作流

恰好选择一个工作流，并且只阅读其参考文档。

用户意图	工作流	参考文档
更新、刷新、同步、精简、润色、修复或纠正上下文	polish	references/brain-polish.md
创建、初始化、生成或重新生成上下文文件	create	references/create-docs.md
审计、检查、审阅、查看或提出修改建议，但不编辑	polish，使用 --dry-run 模式	references/brain-polish.md
创建或搭建技能	停止	参阅 skills/skill-writing
安装、发现、移除或重命名技能	停止	使用专用的技能管理工作流

如果意图不明确，选择 polish 的 --dry-run 模式，并报告最小且有用的计划变更集。

权限

• 明确提出创建、更新、润色、修复、纠正或等效意图，即授权在范围内进行本地写入。仅检查意图和 --dry-run 不授权写入。
• 删除 README.md、AGENTS.md、CLAUDE.md 或上下文文档目标前，必须获得明确确认。--force 授权执行文档规定的覆盖操作，但不授权删除。
• 对宽泛的写入请求，将其视为已授权所请求的范围。否则，如果变更集涉及的文件超过少数几个，应先预览变更集，并在写入前停止。
• 不得将文档工作扩展为源代码修改、技能创建或外部写入。

参数

• path：可选的相对于仓库的子树路径。将文档、包根目录、项目技能和上下文文档的发现范围限制在该子树内。
• target ...：polish 期间的可选筛选条件：现有的 .agents/skills/<name>/ 技能名称，或用于选择特定上下文文档的仓库相对 Markdown 路径。
• --root-only：仅选择根目录下的 README.md、AGENTS.md 和 CLAUDE.md 目标。除非通过 target 明确选择，否则排除项目技能和上下文文档。
• --dry-run：报告计划写入内容和简洁的差异，不更改文件。
• --preserve：polish 期间保留准确的用户撰写文本和结构；只修正偏差和明显冗余。
• --minimal：生成满足完成标准的最精简上下文。
• --thorough / --full：仅在能增加持久且特定于仓库的上下文时进行深入分析。
• --force：create 期间无需提示即可重新生成现有的 README.md 或 AGENTS.md 目标。不适用于技能或删除操作。

如果同时提供 --minimal 和 --thorough / --full，不得进行任何写入，并请用户选择。报告无法识别的标志；仅当它们不会影响范围、安全性或写入行为时，才继续执行。

仓库护栏

在发现或写入前运行：

cwd="$(pwd -P)"
case "$cwd" in
  /) printf 'abort: refusing to run at the filesystem root\n' >&2; exit 1 ;;
esac
repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
  printf 'abort: not inside a git repository\n' >&2; exit 1; }
managed_skill_root=
case "$repo_root" in
  /|"$HOME") printf 'abort: unsupported repo root: %s\n' "$repo_root" >&2; exit 1 ;;
  "$HOME/.agents"|"$HOME/.codex"|"$HOME/.claude") managed_skill_root="$repo_root/skills" ;;
  "$HOME/.agents/"*|"$HOME/.codex/"*|"$HOME/.claude/"*)
    printf 'abort: repo root is nested under an agent configuration repository: %s\n' "$repo_root" >&2; exit 1 ;;
esac
if [ -n "$managed_skill_root" ]; then
  case "$cwd" in
    "$managed_skill_root"|"$managed_skill_root/"*)
      printf 'abort: installed skills must be edited in their source catalog: %s\n' "$cwd" >&2; exit 1 ;;
  esac
fi

如果设置了 managed_skill_root，允许在该仓库的其他位置处理 README.md、AGENTS.md 和 CLAUDE.md，但在所有工作流中排除整个已安装的 skills/ 树。发现、规范化或遍历符号链接之前，先应用此排除规则。如果 path、target 或明确请求会进入该树，则不得在那里进行任何写入，并报告必须在技能的源目录中编辑。--force 不会覆盖此边界。

进行大范围编辑前，保存 git status --short 的快照。保留无关的既有更改，并在生成器或大范围命令执行后重新检查预期路径。

共享约束

限定在解析后的仓库范围内，并保留无关更改。所选工作流参考文档对 README.md、AGENTS.md、CLAUDE.md 和项目技能的行为具有权威性；此处不要重复或扩大其针对特定文件的规则。

发现与工具路由

使用感知 Git 的发现方式，将每个候选项规范化为位于 repo_root 下的路径，并排除 VCS、依赖项、环境和构建产物。仅当选定项目技能时，才有意包含被忽略的 .agents/skills/*/SKILL.md。优先使用 fd；若结果少得可疑，则回退一次；写入前综合独立的仓库证据。

通过 README.md、AGENTS.md、CLAUDE.md 和 SKILL.md 文件中的 Markdown 链接发现上下文文档，然后扫描其余内容符合条件的已跟踪 Markdown 文件。根据内容分类，绝不依据文件名或位置。排除变更日志、许可证、法律和政策声明、生成或供应商提供的文档，以及属于产品内容而非指导的文字。分类不确定时，将文件排除在范围之外，并将其报告为候选项。

完成与报告

写入后，如果仓库定义了 Markdown 格式化或检查流程，则运行这些流程。如果目录中的技能 frontmatter 或 agents/openai.yaml 已更改，则运行其调用元数据检查。验证已更改的 CLAUDE.md 符号链接能解析到同级的 AGENTS.md。在 --dry-run 模式下，对于依赖计划创建文件的命令，报告命令而不运行。

仅在写入和所需验证通过后，以 ### ✅ 上下文已更新 开头； 文件已写入但所需检查失败时，以 ### ⚠️ 上下文已更新 — 验证失败 开头； 在 dry-run 模式下，以 ### 🔎 上下文预览 — 未写入文件 开头；或在写入前停止时，以 ### ⛔ 上下文受阻 — 未写入文件 开头。随后仅报告：

1. 🧭 模式和范围：工作流、dry-run 状态、目标数量和相对路径，以紧凑表格呈现。
2. 📦 更改：按目录分组列出已完成或计划中的更改；路径归属更清晰时使用树状结构。
3. 🧪 验证：以表格列出确切命令、结果和任何合理的跳过项。
4. ⚠️ 阻碍和风险：冲突、提示和无法识别的标志；为空时省略。

路径、命令、护栏错误、符号链接目标和用户编写的内容必须保持原样，不得添加装饰。省略空的细节；所选目标满足完成标准后即停止。

参考资料

• polish：阅读 references/brain-polish.md。
• create：阅读 references/create-docs.md。