uni-ai-rules

统一 AI Agent 规则与技能编译工具。从统一格式的规则文件编译为各 AI Agent（Cursor、Trae、Claude Code、Devin、GitHub Copilot 等）所需的格式，同时支持技能原样输出。

快速开始

创建规则文件 .uni-ai-rules/my-rule.md：

---
globs: "src/**/*.ts"
---
使用 const 而非 let。

编译：

npx -y uni-ai-rules

默认输出到 AGENTS.md（single 模式）。也可在 ~/.uni-ai-rules/rules/ 下创建跨项目共用的规则文件。

通过环境变量 UNI_AI_TYPE 可切换目标 Agent，详见使用方式。

使用方式

目录结构

项目根目录下需要准备以下内容：

.uni-ai-rules/
├── coding-style.md     # AI Agent 规则文件（.md），支持递归子目录
├── react/
│   └── components.md
└── ...

.agent/
└── skills/             # 技能目录（可选），每个技能是一个子目录
    └── my-skill/
        ├── SKILL.md
        └── assets/
            └── ...

全局规则（home 目录）

除项目规则外，工具还会自动加载 ~/.uni-ai-rules/rules/ 下的规则文件（格式与项目规则相同）。home 规则适用于所有项目，输出时文件名和标题会加 common. 前缀以区分。

规则加载顺序：home 规则在前，项目规则在后。两者允许同名共存，互不冲突。

规则文件格式

规则文件使用 Markdown 格式，支持 YAML frontmatter 元信息：

---
name: "rule-name"                # 手动触发规则的名称，输入指令名称时触发。不能为空、不能重复。
globs: "**/*.ts"  # 文件匹配模式（若有多个，写成符合yml标准的数组，例如["src/**/*.ts", "src/**/*.tsx"]），匹配的文件被查看/编辑/提及时自动生效
description: "规则描述"            # 语义触发条件：Agent 通过语义识别判断上下文是否符合，作为应用规则依据
alwaysApply: false               # 是否始终生效（可选，默认 false）。为 true 时不得设置 globs 或 description
---

技能格式

技能是 .agent/skills/ 目录下的子目录，每个子目录代表一个技能。技能原封不动输出到目标目录，不做任何转换或合并。

.agent/skills/
└── my-skill/
    ├── SKILL.md       # 技能定义（必需）
    ├── scripts/       # 辅助脚本（可选）
    ├── assets/        # 资源文件（可选）
    └── ...

环境变量

推荐使用 .env 文件配置：

# .env 文件
UNI_AI_TYPE=trae

| 变量名 | 必需 | 默认值 | 说明 | |--------|------|--------|------| | UNI_AI_TYPE | 否 | single | 目标 agent 类型，对应 ~/.uni-ai-rules/agents.yml 中的 key。未设置时默认使用 single（输出 AGENTS.md） | | UNI_AI_INPUT_DIR | 否 | .uni-ai-rules | 输入根目录 |

运行

# 方式一（推荐）：已经在 .env 文件中配置了环境变量的情况下，直接运行
npx -y uni-ai-rules

# 方式二：命令行设置环境变量
export UNI_AI_TYPE=trae
npx -y uni-ai-rules

集成到项目

如果项目使用 package.json 管理，可添加到 postinstall 脚本，使每次安装依赖后自动编译规则：

{
  "scripts": {
    "postinstall": "npx -y uni-ai-rules"
  }
}

这样项目成员执行 npm install 后，规则文件会自动编译到各 Agent 的对应目录。

预设 Agent 类型

| 类型 | UNI_AI_TYPE | 编译逻辑 | 规则目录 | 规则文件 | 技能目录 | |------|-----|---------|---------|---------|---------| | Single（默认） | single | B | - | AGENTS.md | - | | Cursor | cursor | A | .cursor/rules/ | - | - | | OpenAI Codex | codex | B | - | .codex/AGENTS.md | - | | Claude Code | claude | A | .claude/rules/ | CLAUDE.md | .claude/skills/ | | Devin | devin | A | .devin/rules/ | - | - | | GitHub Copilot | copilot | A | .github/instructions/ | .github/copilot-instructions.md | - | | Trae | trae | A | .trae/rules/ | - | - | | Continue | continue | A | .continue/ | - | - | | Cline | cline | A | .clinerules/ | - | - | | Roo Code | roo | A | .roo/rules/ | - | - | | Amazon Q Developer | amazonq | A | .amazonq/rules/ | - | - | | CodeBuddy | codebuddy | A | .codebuddy/rules/ | - | - | | Zed | zed | B | - | .zed/.rules | - | | OpenCode | opencode | B | - | .opencode/AGENTS.md | - | | Aider | aider | B | - | CONVENTIONS.md | - | | Gemini | gemini | B | - | GEMINI.md | - |

编译逻辑 A/B 由是否配置 rule-dir 决定：配置 rule-dir 走逻辑 A，否则走逻辑 B。 技能目录仅在 agent 配置中显式设置 skills-dir 时才会输出技能；内置配置目前只有 claude 设置了 skills-dir。如需其他 agent 输出技能，请在其配置中添加 skills-dir。

编译逻辑说明

• 逻辑 A（散装输出）：每个规则输出为独立的 md 文件，保留 frontmatter。若同时配置了 file，不支持对应触发模式的规则（降级规则）会保留完整内容、合并输出到该文件。
• 逻辑 B（单文件输出）：所有规则写入单一 md 文件，去除 frontmatter，按触发类型排序（always → globs → description → manual），添加语义说明。

特殊情况：降级合并

当目标 Agent 不支持规则的触发模式（如不支持 globs、description 或 manual）时，这些规则会降级合并到单一文件，保留完整内容并按触发模式排序（always → globs → description → manual）。

• 对配置了 file 属性的 Agent，降级规则写入 file，例如 CLAUDE.md
• 对未配置 file 属性的 Agent，降级规则写入 rule-dir/AGENTS.md

降级合并文件格式示例：

# my-rule

## 触发条件
文件名匹配glob：`*.ts`

规则内容...

配置说明

首次运行时，会自动创建配置文件 ~/.uni-ai-rules/agents.yml，包含所有预设 Agent 的配置。

自定义 Agent

如果预设列表中没有你使用的 Agent，编辑配置文件添加自定义配置即可。例如：

my-agent:
  rule-dir: .myagent/rules/       # 多文件模式的输出目录。设置此项则走逻辑 A
  extension: .mdc                 # 多文件模式下输出文件后缀。默认为 .md
  file: .myagent/MY_RULES.md     # 单文件模式的输出文件（也用于逻辑 A 的规则降级合并）。设置此项且无 rule-dir 则走逻辑 B
  supports:
    always: true                  # 是否输出 alwaysApply 字段到 frontmatter，默认false
    globs: true                   # true=保留 globs 字段；字符串=支持globs匹配但用其他字段名（参考claude）；false=降级合并
    globs-format: join            # globs有多个表达式时，如何输出。join=逗号分隔；join_no_quote=逗号分隔且无引号包裹；array=YAML 数组
    description: true             # 是否支持 description 模式。false 时降级合并
    manual: true                  # 是否支持 manual模式（用name手动激活）。false 时降级合并