@easyuseai/ai-infra

One source of truth for AI coding tools — scaffold and symlink-distribute shared skills / rules / hooks / agents / instructions to Claude Code, Cursor, Codex and Windsurf with a single npx command.

各家 AI 编程工具（Claude Code、Cursor、Codex/AntiGravity、Windsurf…）各有各的配置目录与格式，导致同一套 skills/rules/hooks 要复制多份、难以同步。本工具用一个 .agent/ 真实来源 + 软链接分发 的模式解决这个问题：你只维护 .agent/，其余工具目录全部是指向它的软链接。

快速开始

在任意项目根目录执行：

npx @easyuseai/ai-infra init

它会：

1. 若没有 .agent/，从内置模板铺好 .agent/（通用 skills + rules + hooks + AGENTS 模板）。
   • 若项目已有 AGENTS.md / CLAUDE.md，会自动采纳为 .agent/AGENTS.md，不覆盖你的项目指令。
2. 用相对软链接把 .agent/ 分发到各工具目录与根级指令文件。
3. 追加 .gitignore 规则，避免把本地密钥（settings.local.json）和备份文件提交。

之后在 .agent/ 里增删 skill/rule 后，跑一次 sync 即可：

npx @easyuseai/ai-infra sync

命令

| 命令 | 作用 | | ---- | ---- | | init | 铺 .agent/（如缺失）并分发软链接到所有工具 | | sync | 重新分发 .agent/（在其中增删文件后运行） | | status | 概览 .agent/ 内容与各工具软链健康度 | | doctor | 找出断链 / 指向其它工程的「foreign」软链，并给出修复建议 | | clean | 移除所有由本工具管理的软链接（保留 .agent/） |

选项

| 选项 | 说明 | | ---- | ---- | | --cwd <dir> | 指定项目根目录（默认当前目录） | | --force | init 时用内置模板覆盖/重铺 .agent/ | | --dry-run | 只预览将要发生的变更，不写盘 | | -h, --help | 帮助 | | -v, --version | 版本 |

分发映射

| 源（.agent/） | Claude Code | Cursor | Codex | Windsurf | | --- | --- | --- | --- | --- | | AGENTS.md | CLAUDE.md | AGENTS.md | AGENTS.md | .windsurfrules | | rules/* | （并入 CLAUDE.md） | .cursor/rules/* | — | — | | skills/* | .claude/skills/* | .cursor/skills/* ¹ | .codex/skills/* | — | | commands/* | .claude/commands/* | .cursor/commands/* | — | — | | agents/* | .claude/agents/* | — | — | — | | hooks/* | .claude/hooks/* | — | — | — | | settings.json | .claude/settings.json | — | — | — |

¹ Cursor 不会遍历「软链接目录」来发现 skill，因此 .cursor/skills/<name> 会被建成真实目录 + 文件级软链接（递归镜像子目录）。其余工具直接软链整个 skill 目录。

所有软链接都用相对路径，因此项目可被移动、复制或用 git worktree 复用而不破坏链接——这也修复了「从别的工程拷贝配置后软链接指向原工程绝对路径」的常见问题（用 doctor 可一键发现这类 foreign 链接）。

内置模板

init 默认铺入的通用内容：

• Skills：create-skill、ui-ux-pro-max，以及一套与技术栈无关的 spec 驱动研发流（create-feature → generate-prd → create-tech-design → implement-feature → create-test-plan → review-code → archive-feature）。
• Rules：general、typescript、testing、git-commit、agent-config、requirements-convention。
• Hooks：sync-agent.sh（在 .agent/ 变更后自动 sync，纯本地、不联网、不阻断）。
• AGENTS.md 模板与无密钥的 settings.json 模板。

设计理念

• 单一真实来源：只维护 .agent/，杜绝多份复制。
• 可移植：相对软链接，跨机器 / worktree 不失效。
• 零运行时依赖：纯 Node 内置模块实现，npx 即用。
• 幂等：init / sync 可反复运行。

License

MIT