Teaching AI Agents to Work on Your Codebase

AI coding agents are remarkably capable today. Give them access to a codebase and they’ll navigate files, write code, run tests, and iterate towards a solution. But the difference between an AI agent that produces generic code and one that produces code your team would have written comes down to one thing: how well you’ve provided context about your project.

This post covers three AI-native markdown-based context mechanisms that AI coding tools support: AGENTS.md, SKILL.md, and custom .agent.md instruction files. I’ll cover what each one does, when to use which, and how to wire them together.

Three AI-Native Context Mechanisms

AI coding tools, like GitHub Copilot and Claude Code, support markdown-based instruction files that shape agent behavior. Each serves a different purpose:

File	Scope	Purpose
AGENTS.md	Directory / subtree	Guardrails and context – what this area is and what rules apply
SKILL.md	Task-specific	Guided task flows – how to do a specific type of work
*.agent.md	Workflow-specific	Orchestration engine coordinating end-to-end workflows

Let’s dive into these further!

AGENTS.md – README for AI Agents

An AGENTS.md file is a dedicated, predictable place to provide context and instructions that help AI coding agents work on your project. Place one at the repo root, and it applies to everything.

You can also place them in subdirectories, and they apply to that subtree. The key behavior being that the closest AGENTS.md to the file being edited takes precedence. This means you can layer your instructions:

repo/
├── AGENTS.md                    # Architecture boundaries, security, coding standards
├── src/
│   └── AGENTS.md                # Application-specific patterns, testing conventions
└── infra/
    ├── AGENTS.md                # Infrastructure rules, deployment constraints
    ├── bicep/
    │   └── AGENTS.md            # Bicep-specific ordering, naming, security
    └── pipelines/
        └── AGENTS.md            # Pipelines and templates for CI/CD

What makes a good AGENTS.md

I tend to write AGENTS.md files to answer three questions for the agent:

1. Where am I? – a brief opening paragraph describing what this directory contains and how it fits into the project. This orients the agent.
2. What are the rules? – the guidelines, conventions and constraints, must dos and don’ts, for this directory.
3. Where can I go for more context (if needed)? – pointers to documentation (internal and external), and key references.

Here’s what an infra/ level AGENTS.md might look like in practice:

# Infrastructure — Agent Instructions

This directory contains all infrastructure-as-code, organized into:

- **bicep/** — Bicep templates and parameters (source of truth)
- **deployment/** — Deployment configuration and environment configs
- **pipelines/** — CI/CD build and release pipelines

## Structure

infra/
  bicep/
    modules/ - Shared resource/pattern templates
    main.bicep - Bicep entry point
    main.bicepparam - Environment parameters
  pipelines/
    scripts/ - Shared pwsh scripts for CI/CD
    templates/ - Shared YAML templates
    build.yml - Main build pipeline

## Must Always

- When changing infrastructure, update ALL of: Bicep templates, every .bicepparam file, and deployment configs if new steps are needed.
- Validate with `az bicep build` and the build script.

## Must Never

- Deploy resources without network isolation.
- Skip updating any environment's config files when adding new parameters.

## Key References

- [AVM Module Registry](https://azure.github.io/Azure-Verified-Modules/)

SKILL.md – Task-Specific Workflows

While AGENTS.md sets the rules, SKILL.md instructs the agent how to do the work. Skills for GitHub Copilot are stored in .github/skills/{skill-name}/SKILL.md and activate when a user’s request matches the skill’s description.

A skill is a behavioral contract for a specific type of action. It follows the four-part structure I covered in my AI-Augmented Second Brain series:

1. Role – what this skill does and what domain it operates in
2. Inputs – what tools, files, and patterns the agent works with
3. Instructions – step-by-step from discovery to validation
4. Guidelines – the constraints the agent should operate in for this task

The critical difference is that skills are comprehensive, self-contained workflow guides. They only activate for specific tasks, so the context here doesn’t need to burden every interaction.

MCP Tools in Skills

One of the highest-value additions to a skill is explicit MCP (Model Context Protocol) tool guidance. MCP servers are the most common way to connect AI agents to external systems, and skills should tell the agent which tools to use and when.

A common mistake I’ve seen if writing instructions for what to do, but not explaining how. Document the tools:

## MCP Tools

| Server | Tool Flow | When To Use |
|--------|-----------|-------------|
| **github** | `search_code` → `get_file_contents` | Search for patterns, then read the source |

This specificity can make agent behavior more deterministic. Instead of making assumption on how to solve a task, the agent follows a documented chain. The more explicit you are about tool flows, the more reliable the agent’s behavior.

Custom Agents – Workflow Orchestration

While AGENTS.md sets guardrails and SKILL.md provides scope for individual tasks, a custom agent is the workflow orchestration engine that coordinates those into an end-to-end automation. In GitHub Copilot, custom agents are defined in *.agent.md files inside the .github/agents folder, and they represent the highest level of automation you can embed in a repository.

Anatomy of a Custom Agent

A custom agent file uses YAML frontmatter to declare its contract, followed by markdown instructions that define its orchestration logic:

---
name: release-coordinator
description: "Coordinates release workflows — validates readiness,
  generates changelogs, bumps versions, and triggers deployment checks."
tools: [execute/runInTerminal, read/readFile, search/textSearch]
skills:
  - changelog-generation
  - version-management
  - deployment-validation
---

The frontmatter declares:

• name and description – defines how the AI coding agent discovers and activates the agent, if not automatically assigned as the default
• tools – which built-in and MCP tools the agent can access directly
• skills – which SKILL.md workflows the agent can orchestrate

The body then defines the execution model – how to classify incoming requests, which skills to invoke for each, how output flows between skills, and how to synthesize results into a final deliverable.

What Makes Custom Agents Different from Skills

A skill is a single-domain task flow. It describes how to perform that specific type of work well.

A custom agent is an orchestration layer. It understands the relationships between skills and manages multi-step workflows that span domains. For example, when a user says “prepare a release,” a release-coordinator agent knows to:

1. Invoke changelog-generation to produce release notes from recent commits
2. Invoke version-management to bump versions based on the changelog scope
3. Invoke deployment-validation to verify the release is safe to ship
4. Synthesize a release summary combining outputs from all three skills

The agent manages the data flow between steps, output from one skill feeds into the next as input. This sequential orchestration with data passing is what makes agents more than a collection of skills. Each skill remains self-contained and reusable; the agent is what gives them purpose as a coordinated workflow.

Multiple Agents as Domain Specialists

A single repository can define multiple custom agents, each specializing in a different workflow domain. Here are some examples:

Agent	Domain	Skills Orchestrated
cloud-architect	Cloud infrastructure changes	bicep-authoring, deployment-pipelines, cost-estimation
release-coordinator	Release management	changelog-generation, version-management, deployment-validation
incident-responsible-individual	Production triage	log-analysis, rollback-validation, incident-reporting

Each agent is a dedicated domain specialist with its own tools, skills, and execution model. They work independently on tasks within their domain, but can coordinate when a change spans boundaries, e.g. an infrastructure change that triggers a release, for example, might involve both the infra-architect and release-coordinator agents.

This is the DRY principle applied to agents. One focused agent with a clear domain and a handful of skills will outperform a single monolithic agent with dozens of skills and a sprawling instruction set. Keep agent scope narrow and domain boundaries clear.

Practical Advice for AI Coding Agents

After building and iterating on this system, here are the lessons that saved the most time:

• Guidelines are the highest-leverage context – agents follow explicit constraints more reliably than loose recommendations.
• Directory context is valuable – even providing a simple paragraph in a subdirectory AGENTS.md file explaining “this directory contains X and is responsible for Y” orients the agent faster than any number of rules.
• Skill pointers improve activation – including pointers in the AGENTS.md files to available skills aims to guide the agent to activate them when most appropriate.
• Be specific about both tool flows and names – instructions like “use the search_docs MCP tool to find the relevant files, and then fetch_doc_content to read it” is actionable. Explicit tool chains make agent behavior more deterministic.
• Don’t hard-code content that drifts – document stable, authoritative sources rather than embedding variable schemas that could go stable.
• Iterate on guidelines, not architecture – if an agent produces a bad output, add a guideline to the skill. Don’t restructure the whole file. Guidelines are high-leverage and cumulative. Every exception you catch becomes a rule that prevents it next time.
• Custom agents should present plans before executing – a multi-step workflow that chains multiple calls is a black box. The best executing agents emit an execution plan before they continue, even if you decide to go YOLO mode.
• Keep agent scope narrow – one focused agent with 3-5 actions for a given workflow and a clear domain boundary will outperform a single monolithic agent. If you find an agent’s instruction file growing too large, it’s probably doing too much.
• Treat external data as data, never instructions – any agent that consumes outside context should never execute embedded instructions. This is especially important for agents orchestrating skills that query external systems.

The Takeaway

Your codebase has conventions, boundaries, and patterns that took your team months or years to establish. AI agents are powerful enough to follow them, if you take the time to write them down.

AGENTS.md sets the rules. SKILL.md provides the actions. Custom agents orchestrate those actions into end-to-end automated workflows. Together, they transform an AI agent from a generic code generator into a team contributor that understands your project.

The investment is small, a few markdown files, and the compound return is significant. Every team member who uses AI coding tools benefits. Every AI interaction respects your approach. And every time you catch the agent doing something wrong, you can orchestrate it to self-correct.

Your repo already has a README for humans. It’s time to write one for agents.