init-agent-md

创建和优化 AI Agent 项目指令文件（AGENTS.md + CLAUDE.md）的通用技能。

最快安装

告诉你的 AI Agent 这一句话就行：

帮我装 init-agent-md：clone 到 ~/.agents/skills/init-agent-md，如果用 Claude Code 再加 Junction 到 ~/.claude/skills/

---

双模式

模式	做什么
初始化	为新项目侦察→起草→质量闸门→创建 AGENTS.md + CLAUDE.md
优化	审查已有文档→逐行评分→6 异味检测→提方案→实施→验证

核心特性

• 6 种配置异味检测 — Lint 泄漏 / 上下文膨胀 / 技能泄漏 / 指令冲突 / 初始化化石 / 盲引用（基于 UFMG Brazil 100 仓库审计，91% 文件至少一种）
• 渐进披露四层架构 — AGENTS.md → 引用文件 → Skills → Hooks
• 7 机制决策框架 — 何时用 CLAUDE.md / Rule / Skill / Hook / Subagent / OutputStyle / AppendPrompt（来自 Anthropic 官方指南 2026.06）
• 160 指令崩溃点警示 — 超过 160 条指令后模型完美遵循率→0%（arXiv 2607.19257）
• 知识沉淀协议 — 5 条自然语言触发规则（P1-P5），让 Agent 在对话中自主捕获和积累项目知识，无需 hook 或外部机制

量化效果

3 场景 × 2 配置的对照实验（with-skill vs baseline）：

指标	With Skill	Without	Delta
通过率	100%	53%	+47pp
初始化场景	100%	33%	+67pp

安装

前提

• Git（任意版本）
• 至少一个兼容的 AI 编程工具（见下方工具列表）

一步安装

git clone https://github.com/LShang001/init-agent-md.git ~/.agents/skills/init-agent-md

~/.agents/skills/ 是 Agent Skills 开放标准 约定的跨工具共用路径。克隆到此路径后，Codex / Gemini CLI / Cursor / OpenCode / Copilot 等工具自动发现，无需额外配置。

各工具配置

Claude Code（需要额外的 bridge）

Claude Code 不从 ~/.agents/skills/ 自动加载技能，需要建立符号链接桥接：

Windows（PowerShell，无需管理员）：

# 删除已有目录（如果存在）
Remove-Item -Force "$env:USERPROFILE\.claude\skills\init-agent-md" -ErrorAction SilentlyContinue
# 创建 Junction（不需要管理员权限）
New-Item -ItemType Junction -Path "$env:USERPROFILE\.claude\skills\init-agent-md" -Target "$env:USERPROFILE\.agents\skills\init-agent-md"

Junction vs Symlink：Windows 上 New-Item -ItemType Junction 不需要管理员权限，效果等价于目录符号链接。两个路径写入同一份文件，之后只需维护 ~/.agents/ 下的正本。

macOS / Linux：

ln -s ~/.agents/skills/init-agent-md ~/.claude/skills/init-agent-md

Codex CLI / Gemini CLI / Cursor / OpenCode / Copilot

无需额外配置。这些工具直接读取 ~/.agents/skills/，克隆即生效。

Windsurf

支持 ~/.agents/skills/ 路径，同样克隆即生效。

验证安装

启动你的 AI 编程工具，输入以下任一指令，技能应自动加载：

初始化这个项目的 agent 文档
审查 AGENTS.md 有没有冗余
我的 CLAUDE.md 太臃肿了，帮我精简

或者在 Claude Code 中手动调用：

/init-agent-md init
/init-agent-md optimize

更新

cd ~/.agents/skills/init-agent-md && git pull

Junction/symlink 用户无需额外操作——更新自动同步到所有路径。

文件结构

init-agent-md/
├── SKILL.md                         # 主技能文件（343 行）
├── references/
│   ├── best-practices.md            # 研究依据（12 篇论文/报告）
│   └── quality-checklist.md         # 验证清单 + 异味检测
└── assets/
    └── AGENTS.md.tmpl               # 六节通用模板

许可证

MIT