agents-brain

Agents Brain

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

优先遵循用户的明确指示和已确立的授权，再采用此技能的默认设置。对于未改变的决定，不要再次询问。保留宿主限制，并遵守对破坏性操作的必要审批要求。

路由

• maintain [path] [target ...] [flags]：维护上下文，并应用有任务依据的技能生命周期变更。默认使用此路由进行上下文维护或检查。阅读 references/maintain.md。
• create-skill [skill-name]：根据明确请求创建项目本地技能。阅读 references/create-skill.md。在搭建之前，先应用仓库目录防护规则。 明确的创建请求无需提供重复使用的证据。
• create-agents-md [path] [--root-only] [--dry-run] [--force]：根据明确请求，为指定范围初始化 AGENTS.md 文件。创建范围根目录文件，并判断每个子树是否需要嵌套文件。阅读 references/create-agents-md.md。

在探索或写入之前选择路由。所有路由都必须遵循以下提示和 STE 要求。维护部分适用于 maintain。每份创建参考文件分别规定其路由的范围、工作流、验证和报告要求。

维护范围

将仓库本地上下文作为一个完整系统来维护。包括以下目标：

• 面向用户的 README.md 文件。
• 面向 Agent 的 AGENTS.md 文件；仅适用于尚未原生支持 Claude Code 的情况，并附带 CLAUDE.md 符号链接。参见下文的 Claude Code 兼容性。
• .agents/skills 下已安装到项目中的技能，以及 skills/<name>/ 下符合条件的源目录技能。
• 上下文文档：任何名称或目录下，为 Agent 或用户提供持久指导的其他 Markdown 文件。 例如：约定、命令目录、数据格式规则、工作流操作手册和参考资料。

随着任务推进，维护由仓库管理的技能，淘汰过时的工作流、处理重要重叠，或记录值得复用的重复流程。

成功意味着每个选定目标都符合以下标准：

• 其内容有仓库证据支持。
• 符合其受众和范围。
• 仅包含会改变行为的指导，不浪费 Agent 上下文。
• 通过仓库定义的最精简验证。

报告已完成或计划中的变更、验证情况以及任何阻碍后，即可停止。

提示词与上下文优化

为当前的 Claude 和 GPT Agent 模型编写技能及其他面向 Agent 的上下文，而不是为某一个模型编写。在这类文字中，不要点名模型、模型版本或特定模型的默认行为。选择、配置或归属模型的内容除外，例如路由表、model: 字段和 API 参数。将 README.md 保持为清晰、面向人的文档。

在处理复杂、耗时、多工具或编排密集型的上下文工作前，相对于此技能目录解析 scripts/fetch-guidance.sh。对于这类工作，分别为 anthropic 和 openai 运行一次。两次运行互不依赖，因此应在同一轮中并行启动，或通过一条 shell 命令启动。以一个并行批次完整阅读两个返回的文件。只有在任务要编写或修改提示词、技能或其他面向 Agent 的文字时，才运行此辅助脚本并阅读指南。其他编辑不要运行辅助脚本，也不要阅读任一指南。在这种情况下，报告 guides: skipped (no agent-facing prose)。

该辅助脚本会获取 Anthropic 的 提示词最佳实践和 OpenAI 的最新模型指南，因为其中的建议可能会变化。Anthropic 指南涵盖所有当前 Claude 模型，并链接到各模型的提示词页面。OpenAI 指南涵盖当前 GPT 模型系列，其中的提示词建议来自对该系列中一个模型的测试。简单的上下文工作无需参考这两份指南。

将点名模型的建议视为针对该模型测得的结果。只有跨模型指南支持时，才将其应用于其他模型。若要核实此类说法，请阅读链接的各模型页面。当指南针对不同模型给出相反的修正建议时，直接说明所需行为。不要针对某个模型的默认行为作出修正，例如“简洁一些”或“写得更详细”。

接受通过完整性验证且在 24 小时内的 cached 指南。对于明确要求最新信息、对变化敏感的工作、存在重大争议的指南，或与观察到的模型行为不符的情况，使用 --refresh。准确解释辅助脚本的诊断信息：

• cached 表示复用了不超过 24 小时前验证的指南，未访问网络。
• revalidated 表示成功收到条件请求的 304 响应后，刷新了验证元数据。
• fetched 表示使用来自固定官方 URL 且通过完整性验证的内容，原子性地替换了缓存。
• stale 表示实时获取失败后，复用了不超过七天前验证的指南。只有在阅读后才能继续。须在未决问题与注意事项中披露验证时间戳和获取失败的情况。

强制刷新、条目过期、完整性验证失败以及意外重定向均应按失败关闭处理。如果任一必需指南无法返回，在编写前停止相关工作。不得用记忆或其他来源替代。绝不要在仓库或技能安装目录中创建缓存。

仅保留会影响决策、防止有证据表明会发生的错误，或提供不可通过其他方式发现的约束的内容。每项含义只在最窄且可靠的加载范围内说明一次；独立安装的产物需要保持自包含时除外。保留权威性、安全要求、重要例外、语义上的成功标准，以及由机器读取的精确文本。仅限文档的权限不允许修改辅助脚本或架构。应报告可提取内容的机会。

STE 编写与审阅

在编写或修改面向 Agent 的文本之前，请完整阅读 references/asd-ste100.md。 编写时应用其中基于 STE 的规范。报告完成前，请完成其中的含义与风格审阅。保留义务强度、不确定性、条件、技术精度和受保护的字面内容。遵循目标受众要求，以及保留准确的用户撰写文本的任何指示。该规范不代表符合 ASD 官方词典要求。在当前运行期间完整阅读该参考文件一次，即可满足此技能后续所有阅读该文件的要求；除非文件发生更改。

维护工作流

使用 $agents-brain maintain 进行上下文维护，以及处理有任务依据的技能生命周期变更。在请求范围内，更新现有上下文，创建有必要的新上下文，并应用有任务依据的技能生命周期变更。

每次运行 maintain 时，都要记录更正。扫描会话中用户所做的更正，例如重述指示、“不要做 X”、“始终做 Y”或撤回某项选择。将每项持久更正作为规则记录在范围内最近的指导文件（例如 AGENTS.md）或所属技能中。若更正不具持久性，请在报告中说明原因：仅适用于单次任务、已说明或项目特定例外。

仅在创建或重新生成上下文时阅读 references/create-docs.md。仅在处理技能生命周期决策或建立持续维护时阅读 references/maintain-skills.md。这些参考文件用于支持工作流，并非独立模式。

创建技能时，在应用维护证据门槛后，使用此技能的 references/create-skill.md。若有适用的源目录生命周期指示，请遵循。此仓库之外的安装和技能管理属于专门工作流。若意图仅为检查或不明确，请使用 maintain --dry-run，并报告最小且有用的计划变更集。

维护授权

• 明确要求创建、更新、修复、维护或类似操作，即授权在范围内进行本地写入。仅检查的意图、Plan Mode 和 --dry-run 均不授权写入。若请求或现行仓库指示授权这些生命周期操作，则执行有证据支持的删除、合并和创建。
• 删除 README.md、AGENTS.md、常规 CLAUDE.md 文件或上下文文档目标前，必须取得明确确认。--force 授权执行有文档依据的覆盖操作，不授权删除。唯一的常设例外是指向同级 AGENTS.md 的 CLAUDE.md 符号链接，且已安装的 Claude Code 原生读取 AGENTS.md（参见 Claude Code 兼容性）：无需询问，直接删除。
• 根据请求的结果确定范围。对于大型变更集，先预览，再在已有授权的情况下继续。文件数量本身不是审批界限。只有未解决的选择会改变范围或预期含义时才提问。
• 上下文编辑仅限文档。获得授权时，技能生命周期工作可以修改受影响技能所拥有的文件及其本地使用方。仓库边界始终禁止外部写入。

报告完成前，完成所有已授权的发现、编辑和验证。若某个目标需要用户输入，继续处理其他独立目标。指出确切的未解决选择。若技能规则要求暂停，请引用该规则，并说明现有授权为何不涵盖下一步操作。

持续维护仓库技能

在获授权的实施任务中，阅读相关指南时、修改其所述工作流后，以及提交最终报告前，都要留意技能是否受到影响。只检查与该任务相关的技能。当仓库指示或用户授权持续维护时，应根据已核实的机会采取行动并完成相应更改。仅提出建议不算完成。除必要的前置工作外，应先完成范围固定的调用方工作流，再进行独立维护。只读任务必须保持只读。

持续维护意味着在正常任务过程中反复留意，而非后台监控、定时任务或全目录审计。将边界限定在任务所在的仓库。绝不能跟随技能的来源或安装路径进入其他仓库或全局 Agent 目录。即使主要任务失败或受阻，只要有已核实证据支持，仍可进行独立且获授权的技能改进。

如果用户要求为今后的任务建立这一行为，请根据 references/maintain-skills.md 中的常驻指示指南，更新或创建适用的 AGENTS.md。仅在某个会话中加载此技能，并不会自动让今后的 Agent 执行它。

维护参数

• path：可选的仓库相对路径子树。将文档、包根目录、项目技能、源目录技能和上下文文档的发现范围限制在该子树内。
• target ...：可选筛选条件：现有 .agents/skills/<name>/ 或符合条件的 skills/<name>/ 目录树中的技能名称，或用于选择上下文文档的仓库相对 Markdown 路径。未指定筛选条件时，在所选目录树中发现上下文。持续技能生命周期审查仍只考虑当前任务证据所涉及的技能。
• --root-only：仅选择根目录下的 README.md、AGENTS.md 和 CLAUDE.md 目标。排除项目安装的技能、源目录技能和上下文文档，除非通过 target 明确选择。
• --dry-run：报告计划写入的内容和简明差异，但不更改文件。
• --preserve：保留准确的用户编写的文本和结构。只修正偏差和明显的冗余内容。
• --minimal：生成满足完成标准所需的最少上下文。
• --thorough / --full：仅在能增加持久且针对仓库的上下文时进行深入分析。
• --force：无需提示即可重新生成现有 README.md 或 AGENTS.md 目标。不适用于技能或删除操作。

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

仓库防护栏

对于 maintain 和 create-agents-md，请在发现或写入前运行：

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 不能覆盖此边界。

在受管 Agent 配置根目录之外，符合条件且由 Git 跟踪的 skills/<name>/ 源目录可按照 references/maintain.md 进行事实性上下文修正，或按其所属仓库的生命周期规则进行处理。开展生命周期工作前，须遵守 references/maintain-skills.md 中更严格的归属权和仓库边界要求。

Claude Code 兼容性

Claude Code v2.1.277 及更高版本会在工作目录或其上级目录中不存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，直接读取 AGENTS.md，因此不再需要 CLAUDE.md 符号链接。在工作流操作 CLAUDE.md 之前，每次运行只检测一次已安装的版本：

claude_version=$(claude --version 2>/dev/null | head -n 1 | cut -d ' ' -f 1)
agents_md_native=false
if [ -n "$claude_version" ] &&
  [ "$(printf '%s\n' 2.1.277 "$claude_version" | sort -V | head -n 1)" = 2.1.277 ]; then
  agents_md_native=true
fi

当 agents_md_native=true 时：

• 不要创建 CLAUDE.md 符号链接。
• 在同一轮操作中，遍历整个选定树，删除所有指向同级 AGENTS.md 的 CLAUDE.md 符号链接；如已纳入版本控制，则使用 git rm。保留常规的 CLAUDE.md 和 CLAUDE.local.md 文件，并报告这些文件。 仓库根目录及其上级目录中的此类文件仍会阻止直接加载 AGENTS.md，除非用户在 /config 中将 Project instructions 设为 claude-md-and-agents-md。

当找不到 claude 或其版本较旧时，保留原有行为。在这种情况下，仅在缺少 CLAUDE.md 或其已是符号链接时，创建或更新同级符号链接。旧行为下绝不删除符号链接。

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

发现与工具路由

对于由任务驱动的技能生命周期审查，使用 references/maintain-skills.md 中限定范围的发现方法。对于上下文维护，在请求的范围内应用以下发现规则。

使用支持 Git 的发现方式。将每个候选项规范化，确保其位于 repo_root 下。排除 VCS、依赖项、环境和构建输出。

仅在选中项目技能时，才有意纳入被忽略的 .agents/skills/*/SKILL.md。只有在非托管 Agent 配置根目录之外且选中源目录技能时，才发现已纳入 Git 跟踪、未被忽略且非符号链接的 skills/*/SKILL.md。解析每项选中技能的 YAML frontmatter。

在判定某个项目已安装的技能是否符合协调豁免条件之前，只检查其声明的写入边界。优先使用 fd。如果结果范围窄得可疑，再使用一种替代方法。写入前，综合独立的仓库证据。

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

完成与报告

写入后，如果仓库定义了 Markdown 格式化或检查流程，请运行。对于每个新编写或修改的面向 Agent 的文本目标，按照 references/asd-ste100.md 完成含义和风格审查。将现有文本与其来源进行比较，并将新文本与权威要求进行比较。明确检查受保护内容和精度例外。

如果项目中安装的技能的 frontmatter 或 agents/openai.yaml 发生变化，请运行其调用元数据检查。 当 agents_md_native=true 时，验证不存在 CLAUDE.md 符号链接。否则，验证每个保留或创建的符号链接都指向同级的 AGENTS.md。在 --dry-run 模式下，对于依赖计划文件的命令，请报告而非运行。

仅在写入和必需验证均通过后，以 ### ✅ Context updated 开头； 如果文件已写入但必需检查失败，则以 ### ⚠️ Context updated — validation failed 开头； 在 dry-run 模式下，以 ### 🔎 Context preview — no files written 开头； 如果写入前即停止，则以 ### ⛔ Context blocked — no files written 开头。随后说明范围、重要变更、准确的验证命令及结果，以及任何剩余限制。小改动请使用简短文字。只有在有助于整理重复信息时才添加标题或表格。只有在目录归属关系很重要时才添加目录树。遵循用户要求的报告格式。

当问题需要单独列出时，请将有证据支持的已验证修复归入 Resolved，将剩余问题归入 Open，并说明影响和后续操作。没有内容的分组请省略。每项只报告一次。仅将阻碍必需工作的问题称为 blocker；将具体的潜在不利结果称为 risk。变通方案不会消除底层问题。

Open 项只能引用用户提供的输入、仓库之外的操作或确认边界（破坏性操作、购买、部署或外部写入）。如果任务允许写入，且仓库内的更改可以解决某个问题，请依据持续维护授权先完成该更改，再撰写报告。对于常规工程选择，不要写 needs owner decision、report-only 或 residual risk。请自行决定、完成更改，并在报告中说明决定。

路径、命令、护栏错误、符号链接目标和用户编写的内容必须保持原样，不加修饰。省略空项。选定目标达到完成标准后即停止。

参考资料

• 维护：阅读 references/maintain.md 了解工作流程。
• 编写或修改面向 Agent 的文本前：阅读 references/asd-ste100.md，了解基于 STE 的规范和完成审查要求。
• 创建或重新生成上下文：阅读 references/create-docs.md，了解放置和生成规则。
• 更改技能生命周期或建立持续维护流程：阅读 references/maintain-skills.md。
• 创建技能：阅读 references/create-skill.md，了解范围、元数据、符号链接和验证要求。通过 Bash 运行 scripts/fetch-agentskills-spec.sh [--refresh]，以获取规范的绝对缓存路径。默认情况下会重复使用有效期为 24 小时的缓存，之后重新验证。创建参考文档规定了刷新、缓存过期和失败处理规则。
• 初始化 AGENTS.md 文件：阅读 references/create-agents-md.md，了解范围、嵌套文件决策和报告要求。
• 选择新技能的契约或布局前：阅读 references/writing-great-skills.md，了解编写、路由和执行规则。