agent-scripts：Peter Steinberger 的 AI Agent 工作台
AI Agent 用久之后，真正麻烦的往往不是“能不能调用工具”，而是另一件更隐蔽的事：规则散落在不同仓库，Skill 越装越多，提示词预算被一点点吃掉，重复的能力还会在不同目录里互相打架。
agent-scripts 解决的正是这类工程化问题。它不是一个面向终端用户的 Agent 产品，而是 Peter Steinberger 用来管理个人工作流的一套共享基础设施：统一的 agent 指令、可复用的 skills、跨项目的小脚本，以及一些本地 guardrails。
本项目由 “OpenClaw 之父” Peter Steinberger 开发，agent-scripts 是他把自己日常使用的 Agent 工作台公开出来的一部分。
它不是脚本合集，而是 Agent 操作系统的一层配置面
agent-scripts 主要包括四块内容：
AGENTS.MD：给 Codex、Claude 这类代码 Agent 使用的共享硬规则。skills/：可复用的工作流 Skill，其中既有仓库内维护的个人 Skill，也有通过 symlink 暴露出来的 OpenClaw 公共 Skill 或其他项目内 Skill。scripts/：跨项目使用、尽量少依赖的小工具，例如提交辅助、Skill 校验、文档列表生成和浏览器调试工具。hooks/：本地校验钩子，例如在提交前验证 Skill front matter。
这套结构背后的判断很清楚：Agent 的能力不只来自模型，也来自可维护的上下文与工具分发方式。
一个简单例子是 Skill 的 front matter。仓库要求每个 skills/<name>/SKILL.md 都有 name 和简短的 description，而且 description 要为路由服务，不要写成长篇说明。换句话说，Skill 的描述不是文档首页，而是模型在有限上下文里决定“该不该调用它”的索引词。
为什么 Peter 需要这样一个仓库
Peter Steinberger 同时维护 OpenClaw 相关项目、macOS 应用发布流程、GitHub triage、浏览器调试、1Password、Cloudflare、npm 发布等大量工作流。把每个项目都复制一份完整规则，迟早会出现三个问题。
第一是漂移。某条安全规则在 A 仓库更新了，B 仓库忘了同步，Agent 在不同项目里的行为就会变得不一致。
第二是噪声。规则越写越长、Skill 越装越多，模型每轮启动时能看到的“能力清单”就会越来越臃肿。对于 Codex 这类把 Skill 描述渲染进上下文的系统，描述本身就是成本。
第三是重复。一个 Skill 可能来自 Codex 内置、插件缓存、个人 skill 目录、仓库本地 .agents/skills，甚至 symlink 到另一个项目。人还能勉强记住，Agent 却可能被重复入口误导。
agent-scripts 的做法是把共享部分集中维护，再让全局配置和下游仓库指向它。例如 README 建议让 ~/.codex/skills、~/.claude/skills 指向这个仓库的 skills/，下游项目的 AGENTS.MD 则只保留一个指针和项目特有规则。
graph TD
A[agent-scripts] --> B[AGENTS.MD 共享硬规则]
A --> C[skills 统一入口]
A --> D[scripts 轻量工具]
A --> E[hooks 本地校验]
C --> F[Codex / Claude 全局 Skill 发现]
C --> G[OpenClaw 公共或项目 Skill]
B --> H[下游仓库指针式 AGENTS.MD]
这不是炫技式抽象，而是很实际的维护策略：能共享的集中，必须本地化的留在项目里。
最近新增的 skill-cleaner 值得重点看
skill-cleaner 在 2026-05-25 被加入，用来审计已加载的 Codex/OpenClaw skills、重复副本、近期使用情况，以及提示词预算里的 description 候选项。同一天它还做了一轮增强：加入 realpath 去重、默认不扫描 Dropbox 归档、输出 Codex 规则下 GPT-5.5 的 2% 预算占用、修正 disabled plugin 解析，并按正文相似度排序重复删除建议。
这说明它不是“删目录脚本”，而是一个 Skill 树审计器。它的默认工作方式是生成报告，先让人看到问题，再决定要不要改。
运行方式也很直接：
| |
如果不想扫描日志，可以加 --no-logs；如果要把更久的 Codex 归档会话和常见 OpenClaw/Clawd 日志也纳入，可以用 --deep-logs；如果要模拟不同上下文窗口和预算比例，也可以显式传入 --context-tokens 与 --budget-percent。
skill-cleaner 到底查什么
skill-cleaner 的报告不是简单列目录，而是围绕几个治理问题组织。
1. Skill Budget：提示词预算到底花在哪
它会按照 Codex 可见的 Skill 行格式估算成本，也就是类似：
| |
脚本说明里提到，它参考 Codex 的渲染规则：默认使用模型上下文窗口的 2% 作为 Skill 预算，并按 ceil(utf8_bytes / 4) 估算 token 成本。它还会读取 ~/.codex/models_cache.json 获取 GPT-5.5 的 context_window，拿不到时回退到 272,000 tokens。
这部分价值很大。很多人优化 prompt 时只盯着正文，却忽略了工具说明、Skill 列表、插件描述本身也在占上下文。skill-cleaner 把这笔账直接摊开：完整描述要多少 token，最小无描述行要多少，预算后实际用了多少，还有多少 Skill 被截断或省略。
2. Description Candidates：哪些描述应该压缩
仓库的 Skill 规则反复强调：description 要短，要为路由服务。
skill-cleaner 会找出过长的 description 或渲染行，并给出更紧凑的建议。这类优化看似细碎，但对于一个有几十甚至上百个 Skill 的环境，收益会叠加：模型看到的是更短、更可判别的触发词，而不是一堆像 README 摘要的长句。
3. Duplicates：哪些 Skill 是重复副本
重复 Skill 是 Agent 环境里很常见的问题。一个名字可能同时出现在 Codex system skills、插件缓存、个人目录、repo-local .agents/skills，甚至通过 symlink 指向同一份真实文件。
skill-cleaner 会按名称、正文 hash、description/body 相似度来找重复项，并给出默认保留优先级。它还会做 realpath 去重，避免把 ~/.codex/skills/agent-scripts -> ~/Projects/agent-scripts/skills 这种 symlink 当成两份不同 Skill。
更重要的是，它给的是 deletion suggestions，而不是直接删除。Skill 的重复有时是坏事，有时是策略：repo-local Skill 可能承载了某个项目的运维规则，不能因为名字相似就删。
4. Unused Candidates：哪些能力最近没有证据表明被使用
默认情况下，脚本会扫描 ~/.codex/history.jsonl 和近期 ~/.codex/sessions/**/*.jsonl，寻找 $skill、Use $skill、skills/<name>/SKILL.md 这类使用证据。开启 --deep-logs 后，还会扩大到归档会话和常见 OpenClaw/Clawd 日志目录。
这里要注意，它输出的是启发式结果，不是审判。没有日志命中不代表 Skill 一定没用，可能只是最近没触发、日志不完整，或者它通过别的路径被引用。把它当成清理候选清单，而不是删除命令，会更符合这个工具的设计。
从 skill-cleaner 看 Agent 工程的一个新问题
过去我们管理的是依赖树：npm 包、Go module、容器镜像、Terraform provider。现在，使用 AI Agent 的团队还要管理一棵新的树：规则、Skill、插件、工具提示、会话日志和模型可见上下文。
这棵树也会腐化。
它会出现重复依赖，会出现废弃入口，会出现“写了规则但模型根本看不到”的预算问题，也会出现跨工具的行为漂移。skill-cleaner 的意义就在这里：它把“感觉我的 Skill 太乱了”变成可以被报告描述的问题。
我尤其喜欢它的保守边界。Skill 文档里的 Output Policy 写得很明确：先建议，只有用户要求时才编辑；如果要应用清理，也应该把 description 修改、删除、配置禁用分成小批次处理。
这和好的基础设施工具一样：观察优先，自动化其次，破坏性操作最后。
谁适合关注 agent-scripts
如果你只是偶尔用一下 Claude Code 或 Codex，agent-scripts 可能显得过于个人化。里面有不少 Peter 本地机器、OpenClaw 维护、macOS 发布、GitHub triage 相关的具体流程，不适合直接照搬。
但如果你已经开始维护自己的 Skill 库，或者在多个仓库里复用 Agent 规则，它很值得读。真正值得借鉴的不是某个具体脚本，而是这几条工程原则：
- 共享规则集中维护，下游仓库只保留指针和项目差异。
- Skill description 为路由服务，越短越好，避免把说明文塞进模型启动上下文。
- 可重复的流程沉淀到
skills/<name>/scripts/，不要让 Agent 每次临场拼命令。 - 对 Skill 树做定期审计，尤其关注重复项、长期不用的入口和提示词预算。
- 清理动作保持可逆，先报告，再人工确认，再分批修改。
这些原则放到任何 Agent-heavy 的开发环境里都成立。
小结
agent-scripts 表面上是 Peter Steinberger 的个人脚本仓库，实际展示的是 AI Agent 工作流进入“基础设施化”阶段后的真实需求：规则要同步，Skill 要治理，工具要可复用，上下文预算也要被当成资源管理。
最近新增的 skill-cleaner 把这个趋势说得更直白。Agent 能力越多，不代表系统越强；只有当这些能力能被正确发现、准确路由、低噪声加载，并且可以被审计和清理时，它们才真的变成生产力。