PROTOCOL: AGENTS-MAINTAINER (EXECUTION LEVEL 3)

<state_machine> CURRENT_STEP -> REQUIRED_TOOL -> REQUIRED_OUTPUT -> MANDATORY_HALT Step 1: Read Target -> read_file(AGENTS.md, templates/agents-sections.md) -> Current structure vs required 10 sections -> Continue to Step 2 Step 2: Execute Mode -> read_file(templates/validation-checklist.md) -> Audit / Update / Validate / Generate / Compare output -> 🛑 HALT TURN (Present result) </state_machine>

<execution_invariants>

1. WORKFLOW IMMUTABILITY: You may reason freely INSIDE each step to analyze repository conventions and agent failure modes, but you are strictly forbidden from skipping steps (workflow structure = immutable | step reasoning = flexible).
2. TEMPLATE LOCK: Before auditing, validating, or generating AGENTS.md sections, you MUST call read_file on templates/agents-sections.md and templates/validation-checklist.md (and references/best-practices.md when benchmarking).
3. SPECIFICITY RULE: Every rule written to AGENTS.md must be concrete, verifiable, and grounded in this repo's real commands and architecture.
4. ESCAPE HATCH: If the repository's structure does not fit the contract, do not silently improvise and do not force-fit: declare the deviation in one line and ask. </execution_invariants>

<output_contract>

• TARGET_FILE: AGENTS.md (when in Update or Generate mode) or structured Audit/Validation report
• SOURCE_TEMPLATES: templates/agents-sections.md and templates/validation-checklist.md (MUST call read_file before producing output)
• SCHEMA_INVARIANCE: Preserve all 10 required AGENTS.md sections (Commands, Boundaries, Project Structure, Code Style, Testing Guidelines, Definition of Done, Documentation, Architecture Principles, Karpathy Principles, Git Workflow).
• ESCAPE_HATCH: Never silently omit or invent required sections. If a section genuinely does not apply to the repository, preserve the heading and write "N/A — [1-line rationale]", or halt and ask the user before deviating. </output_contract>

A specialized skill for maintaining, updating, and optimizing the AGENTS.md file to ensure it stays aligned with industry best practices and project needs.

🎯 Purpose

This skill helps you:

• Review current AGENTS.md against best practices
• Update sections with new guidelines or changes
• Validate that rules are clear and actionable
• Optimize for agent performance and understanding
• Generate new sections based on project evolution

📋 Skill Capabilities

Audit Capability

Review the current AGENTS.md and identify gaps or improvements.

When to use:

• Periodic review of agent guidelines
• Before major project changes
• When agent performance issues arise

Expected output:

• Gap analysis against best practices
• Priority recommendations
• Specific improvement suggestions

Update Capability

Update specific sections of AGENTS.md.

When to use:

• New project requirements emerge
• Industry best practices evolve
• Lessons learned from agent mistakes
• Team feedback indicates improvements needed

Expected output:

• Updated AGENTS.md with changes
• Summary of what changed
• Change justification

Validate Capability

Check if AGENTS.md meets quality standards.

When to use:

• After making changes
• Before committing changes
• During code review

Expected output:

• Compliance score (0-100%)
• Missing required sections
• Formatting issues
• Clarity assessment

Generate Capability

Create new sections or files based on needs.

When to use:

• Setting up new project
• Adding new agent instruction files
• Creating coding standards documentation

Expected output:

• New content sections
• Agent-specific instruction files (CLAUDE.md, GEMINI.md, etc.)
• Integration suggestions

Compare Capability

Compare current AGENTS.md with best practices benchmarks.

When to use:

• Evaluating current state
• Planning improvements
• Benchmarking against industry standards

Expected output:

• Side-by-side comparison
• Missing practices
• Adoption recommendations

📊 Required Sections

A complete AGENTS.md should include:

🔧 Best Practices Checklist

Content Quality

• Rules are specific and actionable
• Examples provided for complex concepts
• No contradictory statements
• Language is clear and unambiguous
• Covers common edge cases

Structure

• Logical organization with clear headings
• Uses tables for quick scanning
• Includes code examples
• Proper markdown formatting
• Cross-references to other docs

Agent Optimization

• Karpathy principles included
• Think-before-coding workflow defined
• Search-first requirement explicit
• File size limits specified
• Domain knowledge embedded

Maintenance

• Last updated date present
• Version tracking if applicable
• Change log maintained
• Regular review schedule

🔍 Common Issues & Fixes

Issue: Vague Rules

Problem: "Write good code" Fix: "Follow TypeScript strict mode, no any types without justification"

Issue: Missing Context

Problem: No explanation why rules exist Fix: Add rationale: "DDD abstraction reduces migration cost by 85%"

Issue: Outdated Information

Problem: References to removed features Fix: Run audit, update or remove outdated sections

Issue: Too Long

Problem: Agents don't read entire file Fix:

• Use tables for quick scanning
• Add summary sections
• Keep examples concise

Issue: Contradictions

Problem: Conflicting rules in different sections Fix:

• Detect contradictions
• Consolidate overlapping rules
• Add cross-references

📈 Metrics to Track

🔄 Integration with Other Skills

📚 Related Resources

• Marmelab Agent Experience Guide
• AI-Agent-Standards Framework
• OWASP AI Agent Security

📝 Version History

Skill Owner: Technical Team
Last Updated: 2026-06-25

<self_validation_gate> Before ending your turn, verify every item below with concrete evidence (not just a checkmark). If any item cannot be cited with real evidence from this turn, DO NOT produce your final response — fix the violation first:

• Template Read Evidence: Exact paths passed to read_file (templates/agents-sections.md, templates/validation-checklist.md): <paths>
• Specificity Evidence: Concrete repo files (package.json, Makefile, ARCHITECTURE.md) read to ground commands and boundaries: <paths>
• Required Sections Evidence: Confirm all 10 required AGENTS.md sections are present (or list any "N/A — [rationale]" section): <10/10 status> </self_validation_gate>