Concept·Patterns & Practices·Added today

.agents directory

Also known as: .agents folder, agents dir, agent skills directory, dot-agents

A folder convention, typically named .agents/, for storing reusable skills, prompts, and task definitions that AI coding agents can reference across a project or team. Skills checked into this directory travel with the codebase and can be shared, versioned, and contributed back to community collections.

The .agents directory pattern emerged in 2026 alongside the rapid growth of AI coding agents. The idea is simple: rather than re-explaining how to do a recurring task in every prompt, you write the skill once as a markdown or structured file, drop it in a .agents/ folder at the root of your repo, and agents know where to look. A skill file might describe how to write tests for this codebase, how to handle database migrations, or what the deploy process looks like.

The convention gained visibility through Matt Pocock's skills repository, which reached more than 283,000 GitHub stars, and Addy Osmani's agent-skills repository, which grew to more than 100,000 stars, both distributing production-ready skill files for community use. Google also shipped a global skills library for its Gemini agent using the same modular prompt concept, signaling that the pattern is becoming infrastructure rather than convention.

The .agents directory sits alongside related conventions like AGENTS.md (a top-level instruction file for agent behavior) and CLAUDE.md (Claude Code's project instruction file). The distinction is scope: AGENTS.md and CLAUDE.md describe how an agent should behave in a project; .agents/ stores the reusable units of work the agent can draw on. In practice many teams use both, with the instruction files pointing agents toward the skills directory for task-specific guidance.

This definition is AI-generated and refreshed weekly. It may contain inaccuracies. Use your own judgment, especially for production decisions.

Related terms