Agent-Skills-for-Context-EngineeringAGENTS.md 作为 Agent 工作区记忆的持久化工程范式【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering本篇以仓库根目录的 AGENTS.md 为核心讲解它如何被设计为Agent 工作区记忆workspace memory三条结构学习到的用户偏好、学习到的工作区事实、仓库操作默认值分别承载什么信息、为什么这样分层以及这些记忆条目如何与researcher/目录下的确定性脚本、CI 门禁和 launchd 持续循环一一对应、形成可验证的落地机制。读完后你能掌握如何为协作 Agent 编写不腐化的持久记忆文件如何用状态机、只读表面locked surfaces和基准测试让记忆中的每一条操作规范都有代码级依据。一、什么是工作区记忆AGENTS.md 的定位AGENTS.md 的第一句话定义了它的职责边界Workspace memory for agents collaborating on this repository. Keep entries durable and broadly applicable; one-off task state belongs in chat or in a run thread, not here.也就是说这个文件不是给人看的 README而是写给后续接手仓库的 Agent 的长期记忆。它有一条明确的准入标准条目必须持久durable且广泛适用broadly applicable一次性的任务状态应该留在聊天记录或某个 run 的线程文件里而不是写进这个文件。这条规则直接决定了文件的结构全文只有三个小节分别对应三种不同半衰期的知识。这种分层与仓库自身的运行机制是自洽的。仓库是研究到技能research-to-skill的自主组织外部研究经过评分标准rubrics蒸馏后更新为上下文工程与 harness 工程技能按次运行的状态存放在researcher/runs/run-id/run-state.json中而 researcher/README.md 明确说明该目录刻意做成基于文件的file-based这样 Agent 可以在没有托管调度器的情况下检查、恢复和审计工作。AGENTS.md 存跨 run 的共识run-state.json存单次 run 的状态THREAD.md 存单次 run 的决策流水三层各管各的互不污染。二、三条分层结构偏好、事实、操作默认值2.1 Learned User Preferences把人的口味固化为 Agent 约束第一条偏好条目要求自主研究类工作在范围清晰时通过具体研究循环、子 Agent、验证与编辑推进而不是提出宽泛的流程问题语气条目要求技术型 CTO 风格直接、无营销语言、无感叹号、无 emoji、无 em dash先陈述取舍与复杂度。这类条目看似主观但它解决的是 Agent 协作中最常见的摩擦每个新 Agent 都要重新试探用户的沟通边界。把试探结果写回 AGENTS.md后续 Agent 直接继承。另一条值得注意的偏好是技能与脚本中避免过时的正则或关键词列表启发式优先采用机制级判据、评分标准和有证据支撑的验证。这条偏好不是口号仓库的校验脚本本身就是按这个标准写的researcher/scripts/validate_repo.py 与 researcher/scripts/validate_platform_compat.py 走的是结构化检查frontmatter 解析、manifest 同步、行上限而不是文件名里必须包含某关键词之类的脆弱匹配。2.2 Learned Workspace Facts每个事实条目都指向可查证的仓库位置第二节是全文信息密度最高的部分。它的写法有一个可复用的特点每条事实都绑定一个具体文件路径或命令使记忆可以被随时回查证伪。逐条对应如下按次运行状态机researcher/runs/run-id/run-state.json记录状态且明确规定用research_loop.py的子命令推进状态绝不手改 run-state.json。从源码结构看researcher/scripts/research_loop.py 的set_state()第 110-122 行是唯一的状态写入路径更新current_state、向state_history追加带时间戳和证据的记录、写回 JSON并同步向THREAD.md追加一条决策。子命令层面retrieve/evaluate/propose/novelty/validate-run/pr-ready/close分别驱动状态迁移close只接受accepted、rejected、reference-only、abandoned四种状态VALID_CLOSE_STATUS第 33 行。两级校验是不同问题仓库健康validate_repo.py和单次 run 的就绪度validate_run.py被明确区分为不同的问题对应源码中run_validator()与run_run_validator()两个独立函数各自生成独立的报告文件validation-report.*与run-readiness.*。机制注册表是百科主干researcher/mechanisms/registry.jsonl的晋升必须经research_loop.py promote-mechanisms且记录审查人台账accepted/rejected落在researcher/mechanisms/ledgers/。源码中promote_mechanisms()第 508-572 行强制执行这一点缺少--reviewed-by直接抛错accepted/candidate机制在 run 就绪度未通过时拒绝晋升除非显式--allow-unready注释标明仅用于引导期 fixtures重复mechanism_id直接报错。声明溯源任何数字型或易变声明数值、基准结果必须在researcher/claims/index.jsonl登记溯源语料地图在researcher/corpus/index.json。持续循环的成本边界researcher/scripts/loop_*.py由 launchd 驱动从不调用付费 LLMHTTP 抓取只用标准库1.5 MB 上限、30 秒超时。与 researcher/orchestration/launchd/run-loop-step.sh 一致守护进程只跑loop_step.py --allow-fetch --jsonstdlib HTTP无付费 API且文档注明--allow-fetch可移除以退化为纯记账模式。运行时状态不入库.gitignore实际规则与文档逐条对应见下文第五节。种子 run20260515-035228-executable-autonomous-research-frameworks是唯一被提交的 runclosure.json 显示其关闭状态为reference-only、审查人release-team作用是可运行的完整示例worked example。版本一致性发布版本 2.5.0 同时出现在 .claude-plugin/marketplace.json、.plugin/plugin.json 与根 SKILL.md 三处当前发布 17 个技能目录。基准分阶段Stage 0 确定性 harness已交付、Stage 1 逐技能健康度skill_health.py、Stage 2 路由器已交付结果发布在researcher/benchmarks/router/results-published/、Stage 3 有效性脚手架就绪已完成一个任务、Stage 4 组合规划中方法论单一事实源是 researcher/benchmarks/PLAN.md。语料加固基线与 SDK 运行器当前基线为 16 个已接受机制、12 条带溯源声明、19 个激活用例、严格技能健康分 0.9117 且 0 个被标记技能且规定除非文案、机制注册表、声明索引、语料索引、激活 fixtures 与校验器全部一致不得把一次技能改进描述为完成。基准执行用researcher/benchmarks/sdk-runner/TypeScriptCursor SDK 1.0.13支持--concurrency N、--no-resume、逐 run 进度日志、格式失败重试与最坏情况成本预估已发布的 Stage 2 结果在 2026-05-19.md600/600 可用记录、0 格式失败top-1 Gemini 0.920 / Composer 0.913 / GPT-5.5 0.913 / Claude Opus 4.7 0.840定向改写使context-fundamentalstop-1 提升 23.4pp、project-developmenttop-1 到 1.000。需要说明适用前提以上基线数字是 AGENTS.md 在 2.5.0 发布点的快照属于易变声明仓库约定其权威溯源在researcher/claims/index.jsonl读者引用时应以该索引和最新发布文档为准而不是以本文转述为准。2.3 Repository Operating Defaults操作默认值即防呆设计第三节列出 9 条操作默认值。它们与第二节不同不是这个仓库是什么而是在这个仓库里做事时必须遵守什么。挑几条有源码支撑的展开。先确定性检查后模型裁判。任何技能格式或打包变更声明完成前必须先跑validate_platform_compat.py --require-reference-validator和validate_repo.py --strict。CI 工作流 .github/workflows/validate.yml 把这条默认值变成了硬性门禁在pull_request与push到 main 时依次执行全部 researcher 脚本的py_compile、frontmatter 解析器单元测试、平台兼容性校验、validate_repo.py --strict、skill_health.py --strict --no-history、check_activation_cases.py与run_benchmarks.py整条流水线超时 5 分钟。原子写与文件锁。凡循环触碰的共享文件必须原子写tempfileos.replace并加fcntl锁。researcher/scripts/loop_common.py 完整实现了这两条_atomic_write()第 47-65 行用tempfile.mkstemp在同目录建临时文件、写盘、fsync后再os.replace原子替换失败时清理临时文件queue_lock()第 123-142 行用fcntl.flock排它锁按队列文件族一把锁防止loop_step与loop_discover并发抢改 inbox 或 parked 队列。容错层面read_jsonl()对坏行不是崩溃而是隔离到researcher/reports/jsonl-quarantine/gitignored并继续。付费 API 的三件套约束。任何在循环里调付费 API 的 runner执行前必须具备--concurrency有界并行、基于结果目录扫描的断点续跑、以及能暴露单次调用内部卡顿的逐 run 进度日志。researcher/benchmarks/sdk-runner/src/common.ts 中可以看到前两条的实现参数解析支持--dry-run、--no-resume、--max-runs、--max-budget-usd、--concurrency并且拒绝在无成本上限时运行Refusing to run without a cost cap--dry-run可打印执行计划与成本预估而零 API 调用。这与 AGENTS.md 中成本门禁必须在任何 SDK 调用之前设置一一对应。技能是多表面产物。只改 frontmatter 的description不算完成SKILL.md 正文的When to Activate与Integration小节必须在同一天审计否则正文会与路由它的 description 矛盾。这条默认值点出了一个真实的测量盲区路由器基准只看到 descriptionsettingSources: []测不到正文不一致只有真正加载技能正文的 Stage 3 有效性基准才能度量正文对齐的影响。密钥即视为泄露。聊天中提供的 API key 用后必须立即轮换runner 侧通过apiKeyFingerprint()只记录 key 的最后 4 位来配合这一策略见 common.ts 第 208 行起的导出函数。三、状态机实践种子 run 的完整生命周期AGENTS.md 要求用子命令推进状态绝不手改 run-state.json。仓库里唯一提交的种子 run 给出了这条规则的标准答案可以直接当教程读。run 目录 researcher/runs/20260515-035228-executable-autonomous-research-frameworks/ 的结构由research_loop.py init一次性生成create_run()第 575-606 行sources/含queue.jsonl、evaluations/、evidence/raw/、proposals/、reports/、logs/外加THREAD.md、run-state.json、从模板填充的source-evaluation-draft.json和skill-proposal.md。目录名本身是时间戳-slug格式slugify()截断到 64 字符。run-state.json的关键字段值得逐一看current_state/close_status/close_reason当前状态与关闭语义locked_surfaces本 run 不可触碰的表面包括三份 rubric、机制注册表、两处 manifest.claude-plugin/marketplace.json、.plugin/plugin.json和validate_repo.py本身。设计意图很清楚被评分的对象不能修改评分标准这对应 researcher/README.md 治理规则第 1 条rubric 必须比产出物更难被改editable_surfaces只有本 run 自己的sources/、proposals/、reports/、logs/state_history每次迁移都追加state / timestamp / reason / evidence四元组形成不可删改的审计轨迹。关闭语义也有讲究。该 run 的 closure.json 记录status: reference-only理由写明它的原始证据和 THREAD.md 留作自主循环生命周期的完整示例而技能变更本身早已发布不会再从这个 run 派生 PR。也就是说reference-only与accepted/rejected是两个维度的关闭前者回答这个 run 是否完成使命后者才回答产物是否被采纳。机制晋升的门禁流程可以在promote-mechanisms子命令中完整复现读取proposals/mechanism-proposal.jsonl逐条检查mechanism_id非占位符、先跑validate_run.py确认 run 就绪除非--allow-unready、检查注册表去重然后把注册表条目追加到registry.jsonl、事件追加到 accepted 或 rejected 台账最后把 run 状态迁到validated有晋升或closed全被拒。整个过程没有任何人工判断入口被绕过审查人以--reviewed-by参数显式记录。四、持续循环launchd 编排与零付费默认AGENTS.md 声明持续循环从不调用付费 LLM。编排层落在 researcher/orchestration/launchd/三个 plistloop-step、loop-discover、loop-daily配合install.sh/uninstall.sh安装到 macOS launchd三个run-loop-*.sh包装脚本把输出重定向到researcher/reports/logs/。researcher/orchestration/config.json 给出了循环的全部预算与节律这是 AGENTS.md 未逐字展开、但读源码时应补上的参数面mode: dry-run配置注释明确 HTTP 抓取由loop_step的--allow-fetch开关控制budgets最多 3 个活跃 run、每天最多新建 6 个 run、最多 12 个 parked、每天最多 5 次失败、inbox 上限 200intervalsloop_step 每 10 分钟、loop_discover 每 12 小时、loop_daily 在 UTC 6 点human_review判定为HUMAN_REVIEW/REJECT或新颖度检查为human_review/likely_duplicate的 run 自动 park 到researcher/reports/parked-review.md等待人工limits每轮 discover 最多新增 8 个候选、loop_step每轮最多推进 1 个状态。从源码结构看researcher/scripts/loop_discover.py 的默认数据源只有researcher/discovery/manual-seed.jsonlenable_parallel_deep_research与enable_web_search两个 feed 即使被打开当前也只打印未实现适配器、跳过的提示。去重逻辑existing_urls()覆盖 inbox、quarantine 以及所有活跃/已关闭 run 的 source URL。run-loop-step.sh 的注释还解释了一个运维细节loop_step在无工作时以退出码 78 结束属正常现象不能中断随后的状态刷新。五、运行时状态与仓库卫生gitignore 即契约AGENTS.md 把什么进版本库、什么不进写成显式事实条目而 .gitignore 中第 49-75 行提供了逐条对应的实际规则类别路径处置队列运行时researcher/queue/下inbox.jsonl、parked.jsonl、done.jsonl、quarantine.jsonl、.locks/gitignored报告运行时researcher/reports/logs/、snapshots/、jsonl-quarantine/、loop-events.jsonl、loop-failures.jsonl、status.md、parked-review.md、skill-health.json含历史gitignored基准结果researcher/benchmarks/{router,effectiveness}/results/、sdk-runner/{node_modules,dist}/、router-history.jsonl、effectiveness-history.jsonlgitignored研究 runresearcher/runs/*/但显式例外保留种子 run!researcher/runs/20260515-035228-executable-autonomous-research-frameworks/这里唯一提交进版本库的 run 就是文档所称的唯一已提交 rungitignore 中的例外规则!行是这条记忆的直接代码证据。这个设计使仓库同时满足两个矛盾需求Agent 本地跑循环产生的大量中间态不污染历史同时保留一个经过审计、可复现的参考 run 供新 Agent 学习完整生命周期。六、如何复现与核验命令清单以下命令均可在仓库根目录直接执行来自 AGENTS.md、researcher/README.md 与源码 argparse 定义构成该工作区记忆的可操作接口# 仓库健康PR 门禁同款 python researcher/scripts/validate_platform_compat.py --require-reference-validator python researcher/scripts/validate_repo.py --strict python researcher/scripts/skill_health.py --strict --no-history python researcher/scripts/check_activation_cases.py python researcher/scripts/run_benchmarks.py # 创建一次研究 run生成目录、THREAD.md、run-state.json、评估与提案草稿 python researcher/scripts/research_loop.py init --title Source title --url https://example.com/source # 推进状态子命令retrieve / evaluate / propose / novelty / validate-run / pr-ready / close / promote-mechanisms python researcher/scripts/research_loop.py retrieve --run-dir researcher/runs/run-id --file ./evidence.md python researcher/scripts/research_loop.py novelty --run-dir researcher/runs/run-id python researcher/scripts/research_loop.py close --run-dir researcher/runs/run-id --status reference-only --reason ... # 机制晋升需审查人 python researcher/scripts/research_loop.py promote-mechanisms --run-dir researcher/runs/run-id --reviewed-by name # 单次 run 就绪度 python researcher/scripts/validate_run.py --run-dir researcher/runs/run-id --json # 新颖度与技能修订预检 python researcher/scripts/novelty_check.py --file researcher/fixtures/skill-proposals/harness-engineering-proposal.md python researcher/scripts/compare_skill_revisions.py skills/evaluation/SKILL.md skills/advanced-evaluation/SKILL.md # 持续循环本地模拟 launchdexit 78 表示无工作属正常 python researcher/scripts/loop_discover.py --json python researcher/scripts/loop_step.py --allow-fetch --json python researcher/scripts/loop_status.py --json # SDK 基准运行器成本门禁先于调用--dry-run 零 API 调用 # 见 researcher/benchmarks/sdk-runner/src/common.ts 参数解析 # --concurrency N / --no-resume / --max-runs / --max-budget-usd / --dry-run七、可借鉴的三条设计原则记忆条目必须可回查。AGENTS.md 中每条工作区事实都绑定文件路径或命令新 Agent 接手时不需要信任记忆本身只需要跑一遍对应的校验器。这把文档漂移问题转化为校验失败问题而后者 CI 会替它发现。状态推进必须经过唯一入口。run-state.json不允许手改set_state()是唯一的写路径且自动留痕promote-mechanisms必须带审查人且前置 run 就绪检查。凡是Agent 可能绕过的地方都设了代码级栅栏而不是依赖提示词自觉。成本与安全边界写进默认值而非文档。无成本上限拒绝运行、API key 指纹化、循环默认零付费 LLM、坏行隔离而非崩溃这些默认值使安全运行不依赖操作者记住清单。对任何要托管自主 Agent 的仓库AGENTS.md 加上这套researcher/scripts/的确定性校验骨架是一个可以直接照搬的最小参考实现。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考