用途：在同步维护来源后收紧仓库本地的 agent 上下文，目标不是增加文档，而是减少噪声，只保留 agent 无法从代码树中低成本推断的指引、偏好、工作流陷阱和仓库特有规则。
主要能力：先同步已安装技能并刷新文档，再对仓库内 AGENTS.md 和项目级 .agents/skills/<name>/SKILL.md 做精简整理；支持 path 参数限定仓库相对子树范围，支持 --dry-run 预览不写文件；默认覆盖整个 git 仓库。
必要用法：该技能依赖安装在同级的两个兄弟技能 ../agent-skills-update/SKILL.md 与 ../md-docs/SKILL.md。运行前需确认二者存在，缺失时须停止并提示用户安装：npx skills add PaulRBerg/agent-skills，然后重跑 agent-context-polish；不得手动模拟缺失技能。执行时先运行 $agent-skills-update（不转发 path，转发 --dry-run），再运行 $md-docs update-all（转发 path 与 --dry-run）；若未提供 update-all，则回退执行 update-readme 与 update-agents。之后重新发现目标并只整理这些文件。
适用场景：维护仓库内面向 agent 的上下文文件，消除文件夹结构倾倒、技能清单、通用工具科普、逐字复制的脚本清单、教程式说明和历史写作笔记等噪声，同时保留编码偏好、架构约束、非显然命令顺序、安全与凭据规则、生成文件警告、仓库特有陷阱等。
限制：仅在当前 git 仓库内工作，禁止扫描或写入 ~/.agents、~/.claude 等全局技能；文件系统根目录、HOME 仓库根等场景会中止；目标 frontmatter 无法解析且无显然安全修复时停止；改动后应使用仓库可用的 Markdown 格式化/检查命令验证，若无则报告跳过。