Document: SKILL.md Role: AGENTS.md Manager Priority: Medium - Project setup automation Applies To: AGENTS.md creation and maintenance in any project Optimized For: Claude 4.5 (Sonnet/Opus) Last Updated: 2026-01-04 This skill is auto-discovered by Claude when users request AGENTS.md-related tasks. AGENTS.md is a project-specific guide for AI agents (Copilot, Cursor, Aider, etc.), complementing AGENTS.md which contains Claude-specific global standards.

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
• Guidelines: `documentation.md`, `project-integration.md`

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 AGENTS.md: Reference Claude-specific standards via link

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:

   • Check for dotrc indicators: zshrc, zshenv, starship.toml, claude/ directory
   • For dotrc: Use dotrc-specific template (shell configs, tool settings, symlinks)
   • For other projects: Read README.md, package.json, or similar to identify type
   • Check for claude/AGENTS.md to determine if Claude-specific section should be included

3. Generate template content:

   • Create comprehensive template with essential sections:
     • Project Overview (type, languages, platform, purpose)
     • Repository Structure (directory tree, key files)
     • Build & Test Commands (setup, validation)
     • Development Environment (required tools, installation)
     • Code Style & Conventions (language-specific guidelines)
     • Git Workflow (commit format, types, examples)
     • Testing Changes (pre-commit checks, safe testing)
     • Common Tasks (frequent operations, examples)
     • Security Considerations (secrets, sensitive files)
     • Troubleshooting (common issues, diagnostics)
   • If claude/AGENTS.md exists: Add section with link:

     > **For Claude Code users**: See [AGENTS.md](./claude/AGENTS.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. 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. Generate report:

   • List found sections with status (✅ complete, ⚠️ needs improvement, ❌ missing)
   • Identify missing recommended sections
   • 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>개 섹션 발견

### 📋 발견된 섹션
- ✅ Project Overview
- ✅ Build & Test Commands
- ⚠️ Security Guidelines (내용 부족)
- ...

### 💡 개선 제안
<Specific recommendations>

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

---

Template Sections Reference

When creating AGENTS.md, include these essential sections:

1. Project Overview: Type, languages, platform, purpose
2. Repository Structure: Directory layout, key files
3. Build & Test Commands: Setup, validation, testing
4. Development Environment: Required/optional tools, installation
5. Code Style & Conventions: Language-specific guidelines, formatting
6. Git Workflow: Commit format (reference AGENTS.md if exists), types, examples
7. Testing Changes: Pre-commit checks, safe testing procedures
8. Common Tasks: Frequent operations with examples
9. Security Considerations: Secrets handling, sensitive file locations
10. Troubleshooting: Common issues, diagnostic commands
11. Related Resources: External documentation links

For dotrc projects, add specific sections:

• File Linking Strategy (symlink approach, environment variables)
• Aliases & Functions (standard aliases, modification guidelines)
• Environment Variables (core variables, adding new ones)

Response Language

• User communication: Korean (한국어)
• File content (AGENTS.md): English (for universal AI agent compatibility)
• Section headers in AGENTS.md: English
• Code examples: English (comments, variable names)

See Also

• documentation.md - Documentation standards
• project-integration.md - Codebase learning guidelines
• version-control.md - For Git workflow section in AGENTS.md