AI Agent Config: Rules & Skills

Nơi đặt rule, skill và cấu trúc folder config của Cursor, Claude Code, Codex.

Tổng quan

Cursor cũng đọc AGENTS.md và CLAUDE.md.

Rule vs skill: rule là convention ngắn áp dụng mọi phiên. Skill là kiến thức chuyên sâu theo chủ đề, agent chỉ nạp description lúc start, đọc full khi task khớp (progressive disclosure).

Cursor: .cursor/

.cursor/
├── rules/*.mdc    # rule có frontmatter: description, globs, alwaysApply
└── skills/        # skills riêng của Cursor, cùng format SKILL.md

• globs: **/*.ts thì rule chỉ nạp khi đụng file match.
• alwaysApply: true thì nạp mọi phiên.

Skill: Cursor đọc từ 8 nơi, project-level (.agents/skills/, .cursor/skills/, .claude/skills/, .codex/skills/) và user-level (~/.agents/skills/, ~/.cursor/skills/, ~/.claude/skills/, ~/.codex/skills/). Đọc luôn folder của Claude và Codex để tương thích, nên skill đặt ở .agents/skills/ là Cursor thấy.

Claude Code: .claude/

.claude/
├── settings.json         # commit: permissions, hooks, env, model
├── settings.local.json   # gitignore: override cá nhân
├── commands/             # slash commands, mỗi .md là một /lenh
├── agents/               # subagent definitions (frontmatter: name, description, tools, model)
├── skills/               # skills chỉ Claude Code đọc
└── worktrees/            # git worktrees cho task song song

Memory nằm ngoài folder: CLAUDE.md (commit) và CLAUDE.local.md (gitignore). Cấp user có ~/.claude/ cùng cấu trúc, thêm plugins/ và CLAUDE.md global.

Codex

• Rule: AGENTS.md ở root repo, hỗ trợ nested AGENTS.md theo folder.
• Skill: đọc native .agents/skills/ (scan từ CWD lên repo root) và ~/.agents/skills/. .codex/skills/ là đường dẫn cũ, deprecated.
• Global: ~/.codex/AGENTS.md, config ở ~/.codex/config.toml.
• Custom prompts: ~/.codex/prompts/*.md. Mỗi file .md thành một slash command (file review.md thì gõ /review), tương đương .claude/commands/. Nội dung là prompt template, hỗ trợ $1..$9 và $ARGUMENTS. Do bạn chủ động gọi, không tự nạp. Nằm ở cấp user, dùng chung mọi repo, không commit theo project.

Chuẩn chung: .agents/

Chuẩn Agent Skills cross-tool, nhiều agent cùng đọc. Chỉ chứa skills/:

.agents/skills/<name>/
├── SKILL.md      # bắt buộc: frontmatter name + description, body là hướng dẫn
├── references/   # docs chi tiết, đọc khi cần
├── scripts/      # script chạy được
└── assets/       # template, file mẫu

Mức hỗ trợ khác nhau:

• Cursor: đọc native, kèm luôn folder của Claude và Codex.
• Codex: đọc native.
• Claude Code: chưa hỗ trợ đọc .agents/skills/, chỉ đọc .claude/skills/ và ~/.claude/skills/. Workaround: symlink .claude/skills trỏ sang .agents/skills (lưu ý symlink không ổn định trên git cross-platform).

Skill mới đặt .agents/skills/, Cursor và Codex thấy ngay. Muốn Claude Code thấy thì thêm symlink hoặc copy vào .claude/skills/.

Structure khuyến nghị cho project multi-agent

project/
├── AGENTS.md                        # rule chung, nguồn duy nhất: Codex + Cursor đọc native
├── CLAUDE.md                        # chỉ 1 dòng "@AGENTS.md" import, tránh duplicate
│
├── .agents/
│   └── skills/                      # skills chung: Cursor + Codex đọc native
│       └── <skill-name>/
│           ├── SKILL.md
│           ├── references/
│           └── scripts/
│
├── .cursor/
│   └── rules/*.mdc                  # chỉ cho rule cần glob theo file type
│
└── .claude/
    ├── settings.json                # permissions, hooks (commit)
    ├── settings.local.json          # override cá nhân (gitignore)
    ├── commands/                    # slash commands
    ├── agents/                      # subagent definitions
    └── skills -> ../.agents/skills  # symlink, Claude Code chưa đọc .agents/

Nguyên tắc:

• Rule viết một lần trong AGENTS.md. CLAUDE.md import bằng @AGENTS.md, không copy nội dung.
• .cursor/rules/*.mdc chỉ dùng khi cần glob, thứ AGENTS.md không làm được.
• Skill viết một lần trong .agents/skills/. Claude Code cần symlink; team có Windows hoặc CI không giữ symlink thì copy vào .claude/skills/.
• Không dùng .codex/skills/ (deprecated).