AGENTS.md Guide for VS Code

This skill provides guidance on implementing and using the AGENTS.md standard to provide custom instructions for AI coding agents in VS Code.

Why AGENTS.md?

• Standardization: Reduces fragmentation from proprietary files like .cursorrules.
• Interoperability: Works across different AI tools (GitHub Copilot, Cursor, etc.).
• Efficiency: Saves time by providing structured context (build steps, coding conventions).
• Consistency: Ensures AI agents follow project-specific protocols.
• Open Standard: Governed by the Agentic AI Foundation (Linux Foundation).

Mental Model

AGENTS.md acts as a centralized instruction manual for AI coding agents at the repo root.

• Flow: Repo clone → agent scans for AGENTS.md → parses sections → applies rules during tasks → outputs aligned code.

VS Code Configuration

To enable AGENTS.md support in VS Code:

1. Enable Setting: Set chat.useAgentsMdFile to true.
2. Nested Files (Experimental): Set chat.useNestedAgentsMdFiles to true for subfolder instructions.

How to Implement AGENTS.md

1. Location: Place AGENTS.md at the root of your repository.
2. Structure: Use clear sections:
   • ## Environment: Setup and build instructions.
   • ## Coding Style: Linting, formatting, and architectural rules.
   • ## Testing: How to run and write tests.
3. Keep it Concise: Avoid overly verbose rules.

Real-World Scenarios

• Open-source Maintenance: AI agents auto-generate PRs following style guides.
• Enterprise Code Reviews: Teams use repo-level rules during Copilot-assisted edits.
• Indie Dev Prototyping: Automate build and test cycles with tools like Cursor or Codex.

Survival Kit

• Day 0: Clone a repo with AGENTS.md; ensure chat.useAgentsMdFile is enabled in VS Code.
• Week 1: Create a basic AGENTS.md in a test repo and iterate on sections.
• Week 2: Add nested files if needed using experimental settings.

Security & Risks

• No Secrets: Never include API keys or credentials.
• Goal Hijacking: Be aware that instruction files can steer agent behavior. Review instructions before running autonomous tasks in untrusted repos.

References

• AGENTS.md Homepage
• VS Code Custom Instructions Docs
• GitHub Copilot AGENTS.md Support
• Prompt Security: Risks of AGENTS.md