# Agents Md Gen

> 为项目自动生成 AGENTS.md 配置文件。当用户需要为代码仓库创建 AGENTS.md、想让 Codex/LLM 更好理解项目结构、或需要为多个子目录生成 agent 指令时触发。分析语言、框架、构建工具、测试框架、CI 配置和目录结构，输出专业的 AGENTS.md。

- Skill: `xut82429-glitch/agents-md-gen` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xut82429-glitch/agents-md-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xut82429-glitch/agents-md-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: xut82429-glitch (https://skillmd.com/u/xut82429-glitch)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xut82429-glitch/agents-md-gen

---


# AGENTS.md 生成器

为代码仓库生成专业、结构化的 AGENTS.md 文件，使 Codex/LLM 能高效理解和操作项目。

## 工作流

### 1. 项目扫描

执行以下探测命令收集项目元信息：

```bash
# 语言和框架检测
find . -maxdepth 3 -name "*.py" -o -name "*.ts" -o -name "*.go" -o -name "*.rs" | head -20
cat package.json 2>/dev/null | head -30
cat pyproject.toml 2>/dev/null | head -30
cat Cargo.toml 2>/dev/null | head -30
cat go.mod 2>/dev/null | head -10

# 构建工具
ls Makefile Dockerfile docker-compose.yml .github/workflows/ 2>/dev/null

# 测试框架
rg -l "pytest|jest|vitest|cargo test|go test" --type-add 'code:*.{py,ts,js,rs,go}' -t code 2>/dev/null | head -5

# 目录结构（2层）
find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' | sort

# 已有 AGENTS.md
find . -name "AGENTS.md" -type f
```

根据项目规模调整深度，大型项目（>100 文件）只扫描 `maxdepth 2`。

### 2. 信息提取与分析

从扫描结果中提取：
- **主语言**：文件扩展名统计最多的语言
- **框架**：package.json/pyproject.toml/Cargo.toml 中的依赖
- **构建命令**：Makefile targets、scripts 字段、cargo commands
- **测试命令**：test 配置、测试文件模式
- **CI 配置**：.github/workflows、Jenkinsfile、.gitlab-ci.yml
- **代码风格**：lint 配置文件（.eslintrc、ruff.toml 等）
- **目录语义**：src/lib/test/cmd/api 等目录的用途推断

### 3. 生成 AGENTS.md

按以下结构输出，根据实际情况裁剪：

```markdown
# AGENTS.md

## 项目概述
- 一句话说明项目用途
- 主语言 + 框架 + 运行时版本

## 目录结构
- `src/` — 源码入口
- `lib/` — 核心库代码
- `tests/` — 测试文件
- `cmd/` — CLI 入口（如适用）

## 构建与运行
- 安装：`npm install` / `pip install -e .` / `cargo build`
- 启动：`npm run dev` / `python -m app`
- 构建：`npm run build` / `cargo build --release`

## 测试
- 运行全部：`npm test` / `pytest`
- 运行单个：`pytest tests/test_api.py::test_login`
- 覆盖率：`pytest --cov`

## 代码规范
- Lint：`npm run lint` / `ruff check .`
- 格式化：`npm run format` / `black .`
- 提交前检查：`pre-commit run --all-files`

## CI/CD
- 平台：GitHub Actions / GitLab CI
- 流程：lint → test → build → deploy
- 分支策略：main 保护 + PR review

## 注意事项
- 不要修改的文件/目录
- 特殊配置或约定
- 已知的技术债或待重构区域
```

### 4. 质量检查

生成后验证：
- 所有提到的命令在项目中确实可用
- 目录结构描述与实际一致
- 没有包含过时或不存在的工具
- 语言简洁，无冗余解释

## 输出格式

最终文件写入项目根目录 `AGENTS.md`。内容应：
- 控制在 100 行以内
- 使用中文或英文（与项目文档语言一致）
- 每个 section 只包含实际存在的工具/配置
- 命令可直接复制执行

## 边界情况

- **单文件脚本**：只生成概述 + 运行方式，跳过目录结构
- **Monorepo**：为根目录和每个 package 各生成一个 AGENTS.md，根目录的列出子包导航
- **已有 AGENTS.md**：读取现有内容，在其基础上优化，保留用户自定义部分
- **无 CI 配置**：跳过 CI/CD section，不臆造