feat: add agents-md-writer skill scaffolding and references
This commit is contained in:
parent
46404095dd
commit
44560829be
88
agentskills/agents-md-writer/SKILL.md
Normal file
88
agentskills/agents-md-writer/SKILL.md
Normal file
@ -0,0 +1,88 @@
|
||||
---
|
||||
name: agents-md-writer
|
||||
description: "Guide for creating AGENTS.md files — the standardized Markdown file that provides context and instructions to AI coding agents. Use this skill when the user wants to (1) Create a new AGENTS.md file for a project, (2) Improve or update an existing AGENTS.md, (3) Understand AGENTS.md best practices and conventions, (4) Migrate from legacy config files like .cursorrules or CLAUDE.md to AGENTS.md, or (5) Learn what AGENTS.md is and why it matters."
|
||||
---
|
||||
|
||||
# AGENTS.md Writer
|
||||
|
||||
Create or improve AGENTS.md files — the open standard for guiding AI coding agents.
|
||||
|
||||
## What AGENTS.md Is
|
||||
|
||||
AGENTS.md complements README.md: README is for humans, AGENTS.md is for AI coding agents. Over 60k open-source projects use it. One file works across 20+ tools (Codex, Cursor, Windsurf, Devin, Aider, Gemini CLI, VS Code, etc.).
|
||||
|
||||
**Key principle:** Information that would help a new teammate onboard faster belongs in AGENTS.md.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Understand the Project
|
||||
|
||||
Before writing, discover the project context:
|
||||
|
||||
- Check for existing config files (`.cursorrules`, `CLAUDE.md`, `.aider.conf.yml` — these may contain content to migrate)
|
||||
- Identify the tech stack (read `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, etc.)
|
||||
- Find build, test, and lint commands
|
||||
- Note the project structure and any existing conventions
|
||||
|
||||
Ask the user about anything unclear: team conventions, preferred code style, security constraints.
|
||||
|
||||
### Step 2: Choose the Right Approach
|
||||
|
||||
Match the AGENTS.md to the project:
|
||||
|
||||
| Project Type | Approach |
|
||||
|-------------|----------|
|
||||
| Single repo (small/medium) | Single AGENTS.md at root |
|
||||
| Monorepo | Root AGENTS.md + nested files per sub-package |
|
||||
| Library/SDK | Lightweight, focus on build/test/API |
|
||||
|
||||
### Step 3: Generate the AGENTS.md
|
||||
|
||||
Use the knowledge gathered in Step 1 to fill in the appropriate template. Read [templates.md](references/templates.md) for template options:
|
||||
|
||||
- **Template 1**: General project (most common)
|
||||
- **Template 2**: Monorepo root
|
||||
- **Template 3**: Frontend project (React/Vue/Next.js)
|
||||
- **Template 4**: Backend project (Node/Python/Go)
|
||||
- **Template 5**: Lightweight (small projects/libraries)
|
||||
|
||||
The base template file is also available at `assets/AGENTS.md.template`.
|
||||
|
||||
### Step 4: Review & Refine
|
||||
|
||||
After generating, check:
|
||||
|
||||
- [ ] Every command listed actually works (test if possible)
|
||||
- [ ] Code style rules match actual project conventions
|
||||
- [ ] No duplicate information from README.md
|
||||
- [ ] Sections are concise (prefer command examples over verbose explanations)
|
||||
- [ ] Nested AGENTS.md files are created for monorepo sub-packages if needed
|
||||
|
||||
## Content Guidelines
|
||||
|
||||
### What to Include (Prioritized)
|
||||
|
||||
1. **Build and test commands** (always) — The most important section. Agents need exact commands.
|
||||
2. **Code style conventions** — Naming, formatting, language features used/avoided
|
||||
3. **Project structure overview** — Where things live, especially non-obvious locations
|
||||
4. **Testing strategy** — Test locations, coverage expectations, how to run specific tests
|
||||
5. **PR/commit conventions** — If the team follows specific rules
|
||||
|
||||
### What to Avoid
|
||||
|
||||
- Duplicating README.md content verbatim (complement, don't repeat)
|
||||
- Overly verbose explanations (commands > paragraphs)
|
||||
- Vague guidance ("write clean code" — be specific)
|
||||
- Information that changes frequently (link to docs instead)
|
||||
|
||||
### Monorepo Rules
|
||||
|
||||
- Root AGENTS.md: global tooling, sub-package overview, cross-cutting conventions
|
||||
- Sub-package AGENTS.md: package-specific commands, conventions, structure
|
||||
- The closest AGENTS.md to a file wins
|
||||
|
||||
## Detailed Reference
|
||||
|
||||
For the full AGENTS.md specification, compatibility list, and migration guides, read [specification.md](references/specification.md).
|
||||
|
||||
For complete template examples across project types, read [templates.md](references/templates.md).
|
||||
49
agentskills/agents-md-writer/assets/AGENTS.md.template
Normal file
49
agentskills/agents-md-writer/assets/AGENTS.md.template
Normal file
@ -0,0 +1,49 @@
|
||||
# AGENTS.md
|
||||
|
||||
## 项目概述
|
||||
<!-- 简要描述项目做什么、技术栈概览 -->
|
||||
|
||||
|
||||
## 开发环境设置
|
||||
|
||||
### 前置要求
|
||||
-
|
||||
|
||||
### 安装依赖
|
||||
```bash
|
||||
|
||||
```
|
||||
|
||||
### 常用命令
|
||||
```bash
|
||||
# 启动开发服务器
|
||||
|
||||
# 运行测试
|
||||
|
||||
# 代码检查
|
||||
|
||||
# 构建
|
||||
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
## 编码规范
|
||||
|
||||
### 命名约定
|
||||
-
|
||||
|
||||
### 代码风格
|
||||
-
|
||||
|
||||
## 测试说明
|
||||
-
|
||||
|
||||
## PR 规范
|
||||
-
|
||||
|
||||
## 注意事项
|
||||
-
|
||||
119
agentskills/agents-md-writer/references/specification.md
Normal file
119
agentskills/agents-md-writer/references/specification.md
Normal file
@ -0,0 +1,119 @@
|
||||
# AGENTS.md 规范参考
|
||||
|
||||
## 什么是 AGENTS.md？
|
||||
|
||||
AGENTS.md 是一个简单、开放的 Markdown 格式文件，专为 AI 编程代理（Coding Agents）设计。它是 AI 助手的"README"——与 README.md（面向人类开发者）互补，提供 AI 代理处理项目时所需的上下文和指令。
|
||||
|
||||
目前已超过 6 万个开源项目采用，由 Linux 基金会旗下 Agentic AI Foundation 管理，获得 OpenAI、Google、Cursor、Cognition 等主流厂商支持。
|
||||
|
||||
## 核心设计理念
|
||||
|
||||
1. **面向 AI 代理**：为 AI 编码工具提供结构化的操作手册
|
||||
2. **跨工具兼容**：同一份文件可被 Codex、Jules、Cursor、Windsurf、Devin、Aider、Gemini CLI、VS Code、Zed 等 20+ 工具识别
|
||||
3. **就近原则**：AI 代理使用离当前编辑文件最近的 AGENTS.md
|
||||
4. **纯 Markdown**：无需特殊格式，AI 直接解析
|
||||
|
||||
## 文件位置与嵌套
|
||||
|
||||
### 根目录放置
|
||||
在项目根目录放置一个 AGENTS.md，覆盖整个项目。
|
||||
|
||||
### Monorepo 嵌套
|
||||
在子包中放置独立的 AGENTS.md：
|
||||
|
||||
```
|
||||
my-monorepo/
|
||||
├── AGENTS.md # 根级通用配置
|
||||
├── packages/
|
||||
│ ├── web/
|
||||
│ │ └── AGENTS.md # 前端特定配置
|
||||
│ ├── api/
|
||||
│ │ └── AGENTS.md # 后端特定配置
|
||||
│ └── shared/
|
||||
│ └── AGENTS.md # 共享库配置
|
||||
```
|
||||
|
||||
AI 代理处理 `packages/web/src/App.tsx` 时会使用 `packages/web/AGENTS.md`，而非根目录的。
|
||||
|
||||
## 优先级规则
|
||||
|
||||
1. **最近的 AGENTS.md**（最靠近被编辑文件的）优先级最高
|
||||
2. **用户聊天中的显式指令** 覆盖一切
|
||||
3. 父目录的 AGENTS.md 作为后备
|
||||
|
||||
## 典型内容板块
|
||||
|
||||
| 板块 | 说明 | 是否必要 |
|
||||
|------|------|---------|
|
||||
| 项目概述 | 技术栈、架构简介、项目目标 | 推荐 |
|
||||
| 构建/测试命令 | 安装依赖、启动、构建、测试的具体命令 | 强烈推荐 |
|
||||
| 代码风格 | 命名约定、格式化规则、语言特性约束 | 推荐 |
|
||||
| 测试说明 | 测试策略、覆盖率要求、测试命令 | 推荐 |
|
||||
| 安全注意事项 | 敏感配置、授权边界、禁止操作 | 按需 |
|
||||
| PR 规范 | 标题格式、提交前检查清单 | 按需 |
|
||||
| 部署步骤 | 发布流程、环境变量 | 按需 |
|
||||
| 已知问题/陷阱 | 常见坑点、注意事项 | 按需 |
|
||||
|
||||
## 支持的 AI 工具
|
||||
|
||||
完整兼容（原生支持）：
|
||||
- OpenAI Codex
|
||||
- Google Jules
|
||||
- Cursor
|
||||
- Windsurf (Cognition)
|
||||
- Devin (Cognition)
|
||||
- Aider
|
||||
- Gemini CLI
|
||||
- VS Code (Copilot)
|
||||
- Goose (Block)
|
||||
- opencode
|
||||
- Zed
|
||||
- Warp
|
||||
- Factory
|
||||
- Amp
|
||||
- RooCode
|
||||
- Kilo Code
|
||||
- Phoenix
|
||||
- Semgrep
|
||||
- UiPath Autopilot
|
||||
- JetBrains Junie
|
||||
- Augment Code
|
||||
- Ona
|
||||
|
||||
## 与其他配置文件的区别
|
||||
|
||||
| 文件 | 面向对象 | 用途 |
|
||||
|------|---------|------|
|
||||
| README.md | 人类开发者 | 项目介绍、快速上手、贡献指南 |
|
||||
| AGENTS.md | AI 编程代理 | 构建命令、测试、代码规范、工具链细节 |
|
||||
| .cursorrules | Cursor 专属 | 已逐步被 AGENTS.md 取代 |
|
||||
| CLAUDE.md | Claude Code 专属 | 正在向 AGENTS.md 靠拢 |
|
||||
| .aider.conf.yml | Aider 专属 | Aider 通过 `read: AGENTS.md` 接入 |
|
||||
|
||||
## 迁移指南
|
||||
|
||||
如果项目已有工具专属配置文件，可以这样迁移：
|
||||
|
||||
```bash
|
||||
# 将旧配置重命名为 AGENTS.md
|
||||
mv CLAUDE.md AGENTS.md
|
||||
# 或
|
||||
mv .cursorrules AGENTS.md
|
||||
|
||||
# 为兼容旧工具，创建软链接
|
||||
ln -s AGENTS.md CLAUDE.md
|
||||
```
|
||||
|
||||
Aider 配置（`.aider.conf.yml`）：
|
||||
```yaml
|
||||
read: AGENTS.md
|
||||
```
|
||||
|
||||
Gemini CLI 配置（`.gemini/settings.json`）：
|
||||
```json
|
||||
{
|
||||
"context": {
|
||||
"fileName": "AGENTS.md"
|
||||
}
|
||||
}
|
||||
```
|
||||
322
agentskills/agents-md-writer/references/templates.md
Normal file
322
agentskills/agents-md-writer/references/templates.md
Normal file
@ -0,0 +1,322 @@
|
||||
# AGENTS.md 模板集
|
||||
|
||||
## 模板 1：通用项目模板（最常用）
|
||||
|
||||
适用于大多数单体项目。
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
## 项目概述
|
||||
<!-- 简要描述项目做什么、面向谁、技术栈概览 -->
|
||||
[项目名称] 是一个 [一句话描述]。技术栈：[列出主要技术]。
|
||||
|
||||
## 开发环境设置
|
||||
|
||||
### 前置要求
|
||||
- Node.js >= [版本]
|
||||
- [数据库/运行时/其他依赖]
|
||||
|
||||
### 安装依赖
|
||||
```bash
|
||||
[安装命令，如 pnpm install / npm install / pip install -r requirements.txt]
|
||||
```
|
||||
|
||||
### 常用命令
|
||||
```bash
|
||||
# 启动开发服务器
|
||||
[dev command]
|
||||
|
||||
# 运行测试
|
||||
[test command]
|
||||
|
||||
# 代码检查
|
||||
[lint command]
|
||||
|
||||
# 构建生产版本
|
||||
[build command]
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
```
|
||||
[简要目录树，标注关键目录用途]
|
||||
```
|
||||
|
||||
## 编码规范
|
||||
|
||||
### 命名约定
|
||||
- 组件：PascalCase
|
||||
- 函数/变量：camelCase
|
||||
- 常量：UPPER_SNAKE_CASE
|
||||
- 文件名：[规则]
|
||||
|
||||
### 代码风格
|
||||
- [规则1，如：使用 TypeScript 严格模式]
|
||||
- [规则2，如：单引号，无分号]
|
||||
- [规则3，如：优先使用函数式模式]
|
||||
|
||||
## 测试说明
|
||||
|
||||
### 测试结构
|
||||
- 单元测试：[说明位置和命名规范]
|
||||
- 集成测试：[说明位置]
|
||||
- E2E 测试：[说明位置]
|
||||
|
||||
### 运行测试
|
||||
```bash
|
||||
# 运行所有测试
|
||||
[command]
|
||||
|
||||
# 运行特定测试
|
||||
[command --filter "..."]
|
||||
```
|
||||
|
||||
## PR 规范
|
||||
- 标题格式：`[scope] 简短描述`
|
||||
- 提交前必须通过 lint 和 test
|
||||
- [其他规则]
|
||||
|
||||
## 注意事项
|
||||
- [已知陷阱/特殊约定]
|
||||
- [安全敏感的操作]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 2：Monorepo 根级模板
|
||||
|
||||
适用于 monorepo 根目录，给子包留有指导空间。
|
||||
|
||||
```markdown
|
||||
# AGENTS.md (Root)
|
||||
|
||||
## 仓库概述
|
||||
这是一个 [技术栈] monorepo，包含 [N] 个子包。
|
||||
|
||||
## Monorepo 管理工具
|
||||
- 包管理器：[pnpm workspaces / yarn workspaces / nx / turborepo]
|
||||
- 构建工具：[工具名]
|
||||
|
||||
## 子包概览
|
||||
| 包名 | 路径 | 用途 |
|
||||
|------|------|------|
|
||||
| [name] | packages/[name] | [说明] |
|
||||
| [name] | packages/[name] | [说明] |
|
||||
|
||||
## 全局命令
|
||||
```bash
|
||||
# 安装所有依赖
|
||||
[command]
|
||||
|
||||
# 运行所有测试
|
||||
[command]
|
||||
|
||||
# 全局 lint
|
||||
[command]
|
||||
```
|
||||
|
||||
## 子包操作
|
||||
AI 代理会自动使用离当前编辑文件最近的 AGENTS.md。
|
||||
各子包可在自己目录下放置独立的 AGENTS.md 覆盖本配置。
|
||||
|
||||
## 通用规范
|
||||
- [跨包通用规则]
|
||||
- [代码提交规范]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 3：前端项目模板
|
||||
|
||||
适用于 React/Vue/Next.js 等前端项目。
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
## 项目概述
|
||||
[项目名] 是一个基于 [框架] 的前端应用。
|
||||
|
||||
## 技术栈
|
||||
- 框架：[Next.js 14 / React 18 / Vue 3 / ...]
|
||||
- 语言：TypeScript (strict mode)
|
||||
- 样式：[TailwindCSS / CSS Modules / styled-components]
|
||||
- 状态管理：[Zustand / Redux / Pinia]
|
||||
- 包管理：[pnpm / npm / yarn]
|
||||
|
||||
## 常用命令
|
||||
```bash
|
||||
# 开发
|
||||
pnpm dev
|
||||
|
||||
# 构建
|
||||
pnpm build
|
||||
|
||||
# 测试
|
||||
pnpm test
|
||||
|
||||
# 检查
|
||||
pnpm lint
|
||||
pnpm type-check
|
||||
```
|
||||
|
||||
## 目录结构
|
||||
```
|
||||
src/
|
||||
├── components/ # 可复用 UI 组件
|
||||
├── pages/ # 页面 / 路由组件
|
||||
├── hooks/ # 自定义 React Hooks
|
||||
├── utils/ # 工具函数
|
||||
├── types/ # TypeScript 类型定义
|
||||
├── stores/ # 状态管理
|
||||
└── styles/ # 全局样式
|
||||
```
|
||||
|
||||
## 组件规范
|
||||
|
||||
### 文件结构
|
||||
```
|
||||
ComponentName/
|
||||
├── index.ts # 导出
|
||||
├── ComponentName.tsx # 组件实现
|
||||
├── ComponentName.test.tsx # 测试
|
||||
└── types.ts # Props 类型
|
||||
```
|
||||
|
||||
### 编码约定
|
||||
- 组件用 PascalCase，文件同名
|
||||
- 一个文件一个组件（除非紧密关联的小组件）
|
||||
- Props 使用 TypeScript interface 定义
|
||||
- 优先使用函数组件 + Hooks
|
||||
- 使用 TailwindCSS 工具类（如已采用）
|
||||
|
||||
## 状态管理
|
||||
- 服务端状态：[React Query / SWR / ...]
|
||||
- 客户端状态：[Zustand / Redux / ...]
|
||||
- 表单状态：[React Hook Form / Formik / ...]
|
||||
|
||||
## 测试
|
||||
```bash
|
||||
# 单元测试（Vitest）
|
||||
pnpm test
|
||||
|
||||
# 组件测试（Testing Library）
|
||||
pnpm test:component
|
||||
|
||||
# E2E（Playwright / Cypress）
|
||||
pnpm test:e2e
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 4：后端项目模板
|
||||
|
||||
适用于 Node.js/Python/Go 等后端项目。
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
## 项目概述
|
||||
[项目名] 是一个 [语言/框架] 后端服务。
|
||||
|
||||
## 技术栈
|
||||
- 运行时/语言：[Node.js 20 / Python 3.12 / Go 1.22]
|
||||
- 框架：[Express / FastAPI / Gin / ...]
|
||||
- 数据库：[PostgreSQL / MongoDB / Redis]
|
||||
- ORM：[Prisma / SQLAlchemy / GORM]
|
||||
|
||||
## 常用命令
|
||||
```bash
|
||||
# 安装依赖
|
||||
[command]
|
||||
|
||||
# 启动开发服务器
|
||||
[command]
|
||||
|
||||
# 运行测试
|
||||
[command]
|
||||
|
||||
# 数据库迁移
|
||||
[command]
|
||||
|
||||
# 代码检查
|
||||
[command]
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
```
|
||||
src/
|
||||
├── controllers/ # 请求处理
|
||||
├── services/ # 业务逻辑
|
||||
├── models/ # 数据模型
|
||||
├── middleware/ # 中间件
|
||||
├── routes/ # 路由定义
|
||||
├── utils/ # 工具函数
|
||||
└── config/ # 配置
|
||||
tests/
|
||||
├── unit/
|
||||
├── integration/
|
||||
└── e2e/
|
||||
```
|
||||
|
||||
## API 规范
|
||||
- RESTful 风格
|
||||
- 响应格式：`{ success: boolean, data: any, error?: string }`
|
||||
- 错误处理：统一错误中间件
|
||||
- 请求验证：[Joi / Zod / Pydantic]
|
||||
|
||||
## 数据库
|
||||
|
||||
### 迁移
|
||||
[说明数据库迁移的流程和命令]
|
||||
|
||||
### 查询规范
|
||||
- 使用 ORM 而非原生 SQL（除非必要）
|
||||
- 避免 N+1 查询
|
||||
- 大查询加分页
|
||||
|
||||
## 测试
|
||||
```bash
|
||||
# 所有测试
|
||||
[command]
|
||||
|
||||
# 特定测试
|
||||
[command --filter="auth"]
|
||||
```
|
||||
|
||||
## 安全
|
||||
- [认证方式说明]
|
||||
- [授权模型说明]
|
||||
- 敏感配置使用环境变量
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 模板 5：轻量级模板（小项目/库）
|
||||
|
||||
适用于小型项目或库，极简风格。
|
||||
|
||||
```markdown
|
||||
# AGENTS.md
|
||||
|
||||
## Setup
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Commands
|
||||
- `pnpm dev` - Start dev server
|
||||
- `pnpm test` - Run tests
|
||||
- `pnpm build` - Build for production
|
||||
- `pnpm lint` - Lint and format
|
||||
|
||||
## Code Style
|
||||
- TypeScript strict mode
|
||||
- Single quotes, no semicolons
|
||||
- Functional patterns preferred
|
||||
- Export named, not default
|
||||
|
||||
## Testing
|
||||
- Unit tests alongside source files (`*.test.ts`)
|
||||
- Run `pnpm test -- --coverage` for coverage report
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user