If you have been paying attention to the AI coding space, you know we have moved past the era of stateless chatbots. We are now orchestrating stateful, autonomous coding agents capable of executing complex, multi-step workflows. But this rapid evolution brought a massive headache: standard proliferation.
Three months into using AI agents on a production codebase, you might find yourself correcting the same mistakes every session. Every tool wanted its own configuration file. Cursor wanted .cursorrules, Claude Code wanted CLAUDE.md, and GitHub Copilot wanted .github/copilot-instructions.md. Our repositories quickly turned into fragmented markdown museums for confused bots.
Fortunately, the industry woke up. Enter the .agents standard—a unified, cross-platform architecture backed by the Agentic AI Foundation and the Linux Foundation. Here is how it fundamentally changes how we build software with AI.
The Machine's README: AGENTS.md
At the core of this new paradigm is a single file: AGENTS.md. You can think of it as a "README for machines". While your traditional README.md is optimized for human developers (quick starts, project descriptions), AGENTS.md is strictly optimized for your AI agent.
Located at the root of your repository, it acts as a high-level router. Instead of dumping your entire project's history into the LLM's context window—which obliterates its attention budget—AGENTS.md provides explicit, shallow instructions. It defines the agent's identity (e.g., "You are a Senior TypeScript Engineer"), outlines basic setup commands, and tells the agent exactly where to look for deeper context.
Progressive Disclosure: The .agents Directory
If AGENTS.md is the router, the .agents hidden folder is the database. Injecting massive product requirement documents and architecture guidelines into every prompt is a guaranteed way to pollute the context and induce AI hallucinations.
The .agents directory solves this using a psychological and computational principle called Progressive Disclosure. The agent is given a map of available knowledge, but it only loads specific files when the task demands it. A standard implementation looks like this:
.agents/rules/: Invariant behavioral guidelines, like strict coding standards..agents/wiki/: High-level domain and architecture guides..agents/personas/: Specialized profiles, allowing the agent to wear different "hats," like a QA or Security Engineer..agents/skills/: Reusable procedural workflows and capabilities.
Skills vs. MCP: The Ultimate Syngery
As you dive deeper into agentic architecture, you will inevitably hit a crossroads: should you build an Agent Skill or a Model Context Protocol (MCP) server? The best software creators know how to use both.
MCP (Model Context Protocol) is the "USB-C port for AI". It provides raw, structured technical capabilities, connecting your agent to external databases, Slack, Jira, or Google Drive via strict, OS-level process boundaries. MCP gives your agent the ability to do something, but it does not teach it why or how to do it according to your company's business logic.
Agent Skills (.agents/skills/) provide the missing reusable procedural knowledge. While an MCP server grants your agent the raw technical ability to query a database or access an API, it does not understand your specific business logic. An Agent Skill acts as a semantic training manual, teaching the agent the exact sequence of steps to perform a workflow—such as fetching data and formatting it into a standardized status update.
A skill is packaged as a folder containing optional helper scripts, reference documents, and a required SKILL.md file. This core file uses YAML frontmatter to establish its identity and define strict permission gates (like the allowed-tools parameter), followed by plain-text Markdown instructions.
Here is an example of what a SKILL.md file looks like for an automated standup generator:
---
name: weekly-standup
description: Analyzes git commit history to generate a formatted weekly standup report.
version: 1.2.0
allowed-tools: Bash(git:*) Read
---
# Instructions
1. Execute `scripts/fetch-commits.sh` to retrieve the user's git log for the past 7 days.
2. Read `references/standup-template.md` to understand the required markdown output format.
3. Categorize the raw commits into "Features," "Bug Fixes," and "Chores."
4. Output the final markdown report directly to the user.
By combining structured MCPs for technical reach and Agent Skills for step-by-step reasoning, you give your AI both the power to act and the wisdom to execute tasks correctly according to your team's conventions.
Getting Started
The barrier to entry for setting up this architecture is incredibly low today. You no longer have to build these folders manually. Using the dotagents CLI tool, you can instantly scaffold a compliant architecture in any repository.
Just run npx @sentry/dotagents init to create your agents.toml manifest and .agents/skills/ directory, and you can start adding capabilities directly from open-source repositories. Because different IDEs still look in different namespaces (like .claude/ or .github/), the CLI automatically handles symlinking, ensuring your .agents folder remains the single source of truth across all platforms.
The gap between developers who copy-paste prompts and those who engineer robust agentic systems is widening rapidly. Stop treating your AI like a stateless chatbot. Give it a memory, give it skills, and let it work.
