AGENTS.md Management Skill

This skill creates and manages AGENTS.md files for universal AI agent integration.

Source of Truth

• •AGENTS.md Spec: agents.md
• •Template: agents-template.md - Base template for new AGENTS.md files

When to Activate

This skill activates in these scenarios:

1. •Create request: "에이전트해줘", "create agents", "AGENTS.md 만들어줘"
2. •Update request: "agents.md 업데이트", "Build Commands 섹션 수정"
3. •Regenerate request: "AGENTS.md 다시 만들어줘", "reset agents.md"
4. •Validate request: "AGENTS.md 검증", "agents 파일 확인"
5. •Context-based: User asks about agent configuration for the project

AGENTS.md Principles

• •Universal format: Works for all AI agents (Copilot, Cursor, Aider, Claude, etc.)
• •Project-specific: Contains project context, not generic standards
• •Flexible structure: No required fields, adapt to project needs
• •Hierarchical support: Root file + subdirectory overrides (monorepo)
• •Complementary to CLAUDE.md: Reference Claude-specific standards via link
• •Template as starting point: Use agents-template.md as base, then customize per project

Instructions

Feature 1: Create New AGENTS.md

When: User requests new AGENTS.md file and none exists

Steps:

1. •

   Check for existing file:

   • •Use test -f <project_root>/AGENTS.md to check existence
   • •If exists: Ask user to choose update (Feature 2) or regenerate (Feature 3)
2. •

   Detect project characteristics:

   • •Read project files (README.md, package.json, setup.py, Cargo.toml, go.mod, etc.) to identify project type, primary language(s), and build system
   • •Check directory structure and key entry points
   • •Check if CLAUDE.md exists to determine if Claude-specific callout should be included
3. •

   Load and adapt template:

   • •Read agents-template.md from the skill directory
   • •Remove YAML frontmatter and comment blocks (template management only)
   • •Customize each section based on project analysis from Step 2:
     • •Replace placeholders ([Project Name], [language], etc.) with actual values
     • •Fill 6 Core Areas with project-specific content (see Template Sections Reference)
     • •Remove sections that don't apply (but keep all 6 Core Areas)
     • •Add project-specific sections as needed based on project type
   • •If CLAUDE.md exists in the project: Add Claude Code callout:
     markdown

     > **For Claude Code users**: See [CLAUDE.md](./CLAUDE.md) for Claude-specific guidelines.
     

   • •Include footer: Last Updated, Maintainer, AI Agent Compatibility
4. •

   Create file:

   • •Write to <project_root>/AGENTS.md using Write tool
   • •Confirm completion with file path and section summary

Output Format (Korean):

## AGENTS.md 생성 완료 ✅

**위치**: `<absolute-path>/AGENTS.md`

**포함된 섹션** (<N>개):

- Project Overview
- Repository Structure
- Build & Test Commands
- ...

**다음 단계**:

- 파일을 검토하고 프로젝트에 맞게 조정
- 커밋: "커밋해줘"

Feature 2: Update Specific Section

When: User requests update to a specific section in existing AGENTS.md

Steps:

1. •

   Read existing file:

   • •Use Read tool to load <project_root>/AGENTS.md
   • •If file doesn't exist: Suggest Feature 1 (Create)
2. •

   Identify target section:

   • •Parse user request for section name (e.g., "Build Commands", "Code Style")
   • •Find section using markdown heading pattern: ## {section_name}
   • •If section not found: Ask user if they want to add new section
3. •

   Update section content:

   • •Extract section boundaries (from ## Section to next ## or EOF)
   • •Preserve all other sections unchanged
   • •Use Edit tool with precise string matching for the target section
4. •

   Validate against template principles (guardrail):

   • •Verify all 6 Core Areas are still covered after the update
   • •If a Core Area section was removed or emptied: Warn user before proceeding
   • •Check Boundaries section structure (Always Do / Ask First / Never Do) is maintained
   • •Ensure updated content is project-specific, not generic placeholder text
5. •

   Verify changes:

   • •Show before/after preview
   • •Suggest running git diff AGENTS.md for full review

Output Format (Korean):

## 섹션 업데이트 완료 ✅

**수정된 섹션**: <Section Name>

**전체 diff 확인**:
\```bash
git diff AGENTS.md
\```

Feature 3: Full Regenerate with Backup

When: User requests complete regeneration of AGENTS.md

Steps:

1. •

   Create backup:

   • •Generate timestamp: $(date +%Y%m%d-%H%M%S)
   • •Create backup: cp AGENTS.md AGENTS.md.backup.<timestamp>
   • •If file doesn't exist: Forward to Feature 1 (Create)
2. •

   Generate new template:

   • •Follow Feature 1 steps (detect project, create content)
   • •Optionally preserve user-added custom sections
3. •

   Confirm before replacing:

   • •Show backup location
   • •Ask user: "기존 파일을 백업했습니다. 새 템플릿으로 교체하시겠습니까?"
4. •

   Replace file:

   • •Write new content using Write tool
   • •Confirm completion with backup path

Output Format (Korean):

## AGENTS.md 재생성 완료 ✅

**백업 위치**: `<path>/AGENTS.md.backup.<timestamp>`

**새 파일 생성**: `<path>/AGENTS.md`

**변경사항**:

- ✅ 최신 템플릿 구조 적용
- ✅ 프로젝트 특성 재분석
- ⚠️ 이전 커스텀 내용은 백업 파일에서 확인 가능

**백업과 비교**:
\```bash
diff <backup-file> AGENTS.md
\```

Feature 4: Validate AGENTS.md

When: User requests validation of existing AGENTS.md

Steps:

1. •

   Check file existence:

   • •Use test -f <project_root>/AGENTS.md
   • •If not found: Suggest Feature 1 (Create)
2. •

   Read and analyze:

   • •Parse markdown structure (count headings, check hierarchy)
   • •Identify all sections (scan for ## patterns)
   • •Verify AGENTS.md link if present (check file exists at path)
3. •

   Quality checks:

   • •Structure: Valid markdown, proper H1 → H2 → H3 hierarchy
   • •Completeness: Has essential sections for project type (Overview, Build Commands, etc.)
   • •Clarity: Sections have meaningful content (not just placeholders or "TODO")
   • •Specificity: Contains project-specific information (not generic template text)
4. •

   Core Area coverage check:

   • •Verify each of the 6 Core Areas exists and has meaningful content:
     1. •Commands (Build & Test Commands) → ✅/⚠️/❌
     2. •Testing (Testing Changes) → ✅/⚠️/❌
     3. •Project Structure (Project Overview + Repository Structure) → ✅/⚠️/❌
     4. •Code Style (Code Style & Conventions) → ✅/⚠️/❌
     5. •Git Workflow (Git Workflow) → ✅/⚠️/❌
     6. •Boundaries (Boundaries: Always Do / Ask First / Never Do) → ✅/⚠️/❌
5. •

   Anti-pattern detection:

   • •Vague descriptions: Sections with only generic text like "Follow best practices"
   • •Missing code samples: Commands/Testing sections without executable examples
   • •Undefined boundaries: No Boundaries section or missing subsections
   • •Placeholder content: Unreplaced [brackets], TODO, TBD markers
   • •Stale information: Last Updated date older than 6 months
6. •

   Generate report:

   • •List found sections with status (✅ complete, ⚠️ needs improvement, ❌ missing)
   • •Show 6 Core Areas coverage summary
   • •List detected anti-patterns (if any)
   • •Suggest improvements
   • •Assign quality score: 10/10 (Excellent), 7-9/10 (Good), 4-6/10 (Needs work), 1-3/10 (Incomplete)

Output Format (Korean):

## AGENTS.md 검증 결과

**품질 점수**: <X>/10 (<Rating>)

### ✅ 구조

- 유효한 Markdown 형식
- 적절한 헤딩 계층 구조
- <N>개 섹션 발견

### 📋 6 Core Areas 커버리지

- ✅ Commands (Build & Test Commands)
- ✅ Testing (Testing Changes)
- ✅ Project Structure (Project Overview + Repository Structure)
- ⚠️ Code Style (Code Style & Conventions) - 예시 부족
- ✅ Git Workflow
- ❌ Boundaries - 섹션 누락

### 📋 기타 섹션

- ✅ Development Environment
- ⚠️ Security Considerations (내용 부족)
- ...

### ⚠️ 탐지된 Anti-patterns

- [해당 사항이 있으면 나열]

### 💡 개선 제안

<Specific recommendations>

**다음 단계**: 특정 섹션 업데이트는 "Security 섹션 업데이트" 요청

Template Sections Reference

Full template: agents-template.md

6 Core Areas (Required)

These 6 areas must be present in every AGENTS.md (based on analysis of 2,500+ repositories):

Additional Recommended Sections

• •Development Environment: Required/optional tools, installation
• •Common Tasks: Frequent operations with step-by-step examples
• •Security Considerations: Secrets handling, sensitive file locations
• •Troubleshooting: Common issues, diagnostic commands
• •Related Resources: External documentation links

Anti-Patterns to Avoid

• •Vague instructions: "Follow best practices" instead of specific rules with examples
• •Missing code samples: Commands section without executable bash blocks
• •No boundaries defined: Missing Boundaries section or incomplete subsections
• •Generic content: Unreplaced template placeholders ([brackets], TODO, TBD)
• •Stale documentation: Last Updated date more than 6 months old
• •Over-documentation: Documenting every file instead of key directories and entry points

Response Language

• •File content (AGENTS.md): English by default (for universal AI agent compatibility)
• •Section headers in AGENTS.md: English
• •Code examples: English (comments, variable names)
• •User communication: Follow the project's or user's language preference

See Also

• •agents-template.md - AGENTS.md base template (6 Core Areas)
• •AGENTS.md Spec - Universal AI agent file standard