Activation Conditions
Activate when the user needs any of the following operations:
- Create or rewrite a project's AGENTS.md file
- Analyze the quality and issues of an existing AGENTS.md
- Learn how to write AGENTS.md for different types of projects
- Get templates or best practices for AGENTS.md
- Optimize or iterate an existing AGENTS.md
Intent Routing
| User Intent | Trigger Examples | Execute Sub-skill |
|---|---|---|
| 📊 Analyze Project Requirements | "What type of AGENTS.md is suitable for this project", "Help me analyze the project" | 1-analyze-project |
| 🏗️ Design File Structure | "Design the AGENTS.md structure", "What sections should be included" | 2-design-structure |
| ✍️ Write Core Content | "Help me write AGENTS.md", "Write the content" | 3-write-content |
| 📋 Use Quick Templates | "Give me a template", "Start from a template" | 4-select-template |
| ✅ Quality Check and Validation | "Check this AGENTS.md", "Does it comply with the specification" | 5-quality-check |
| 🔄 Optimize, Iterate, and Maintain | "Optimize my AGENTS.md", "Reduce Token usage" | 6-optimize-evolve |
General Workflow
用户请求
│
▼
① 意图识别 ← 匹配触发关键词，确定子技能
│
▼
② 信息收集 ← 读取项目上下文（README/package.json/技术栈）
│
▼
③ 执行指南 ← 调用对应子技能的标准流程
│
▼
④ 质量门禁 ← 对照规范清单验证输出
│
▼
⑤ 交付成果 ← 提供可用的 AGENTS.md + 改进建议
Quality Gates
Check Items That Must Pass
- Frontmatter Completeness: name/description/tags all exist and comply with the specification
- Clear Trigger Conditions: Clearly state when to use this AGENTS.md
- Clear Intent Routing: Include at least 3 trigger→execution mappings for common tasks
- No Anti-patterns: Does not contain 22 known anti-patterns
- Reasonable Token Efficiency: Core content ≤ 500 lines (see token-budget.md）
Recommended Execution Commands
# 检查现有 AGENTS.md 质量
cat AGENTS.md | head -50 # 查看前50行判断结构完整性
# 统计行数和 Token 估算
wc -l AGENTS.md && echo "估算Token: $(($(wc -l < AGENTS.md) * 3))"
Knowledge Base Index
| File | Content | Applicable Scenarios |
|---|---|---|
| best-practices.md | 28 best practices (structure/content/format) | Reference when writing |
| type-classification.md | Detailed explanation of 5 AGENTS.md types | Project analysis stage |
| anti-patterns.md | 22 anti-patterns and fix solutions | Quality check stage |
| templates.md | Minimal viable/standard/complete templates | Quick start scenarios |
| examples.md | Comparison of 4 real cases | Learning reference |
| token-budget.md | Token budget allocation strategy | Optimization stage |
Sub-skill Overview
| # | Sub-skill | Core Capability | Typical Output |
|---|---|---|---|
| 1 | 1-analyze-project | Project analysis + type determination | Type recommendation + complexity score |
| 2 | 2-design-structure | Structural blueprint design | Section planning + field definition |
| 3 | 3-write-content | Hands-on content writing | Complete AGENTS.md draft |
| 4 | 4-select-template | Template selection and customization | Ready-to-use templates |
| 5 | 5-quality-check | Quality check and validation | Issue list + fix suggestions |
| 6 | 6-optimize-evolve | Iterative Optimization Strategy | Optimization Plan + Maintenance Plan |
Data Sources
This skill is built on the following research results:
- Theoretical Sources: AGENTS.md official specification, Cursor/Windsurf/Claude Code best practices
- Practical Sources: Comparative analysis of AGENTS.md from 4 real projects: book-skills, moonbit-skills, flutter-skills, rust-skills
- Experience Summary: 28 best practices, 22 anti-patterns, Token efficiency optimization strategies
Notes
⚠️ Core Concept: AGENTS.md answers "HOW to work" (how to work), not "WHAT is this" (what this is). It is the Agent's operating manual, not the project's documentation.
⚠️ Difference from SKILL.md:
- AGENTS.md = project-level configuration (tells the Agent how to work in this project)
- SKILL.md = skill-level configuration (tells the Agent what this skill can do)
⚠️ Priority: In a multi-Agent collaboration environment, AGENTS.md > CLAUDE.md > .cursorrules > README.md
Version History
| Version | Date | Main Changes |
|---|---|---|
| v1.0.0 | 2026-05-17 | 🎉 Initial version: a complete AGENTS.md writing expert skill, including 6 sub-skills and 6 knowledge base files |