The open-source community has quietly solved a problem that most businesses haven't noticed yet. Developers are shipping AGENTS.md files alongside their code — structured documents that tell AI coding agents how a project works, what conventions to follow, and where to find what they need. The AGENTS.md GitHub repository has accumulated over 24,000 stars, and tools from GitHub Copilot to Google Jules now recognise the format. Businesses running AI agents against their own operations have the same problem and, so far, no equivalent solution.
Key takeaways
- AGENTS.md is an open format for giving AI coding agents structured project context — build steps, conventions, test commands — separate from the README that humans read.
- SKILL.md extends this idea to reusable, on-demand capabilities that agents load only when needed, avoiding the token waste of packing everything into every request.
- Businesses need their own version of this: a context manifest that tells AI agents how the company works, what data lives where, and what the agent is and isn't allowed to do.
- The hard part for businesses isn't writing the manifest — it's keeping the underlying knowledge current across Slack, Gmail, Notion, HubSpot, and every other system that holds real operational context.
- A managed business context layer for AI handles the indexing, permissioning, and freshness that a static markdown file cannot.
What is AGENTS.md, and why does it exist?
AGENTS.md is a plain-text markdown file that lives at the root of a software repository and gives AI coding agents the context they need to work effectively in that codebase. Think of it as a briefing document written for the agent rather than for a human onboarding to the project.
As agents.md describes it: README files are for humans — quick starts, project descriptions, contribution guidelines. AGENTS.md complements this by containing the extra context coding agents need: build steps, tests, and conventions that might clutter a README or simply aren't relevant to human contributors. The format gives agents a clear, predictable place for instructions, and it works across a growing ecosystem of tools including GitHub Copilot, UiPath, Google Jules, Gemini CLI, and OpenAI Codex.
The practical case for separating these files is straightforward. A human reading a README wants to understand what the project does. An AI agent working in the codebase needs to know how to run tests, which linting rules apply, what the branching convention is, and which directories to avoid touching. Mixing those two audiences into one document serves neither well.
How SKILL.md differs — and why the distinction matters
Once developers started using AGENTS.md, a second question emerged: what happens when an agent needs specialised knowledge for a task it doesn't always perform? Packing every possible instruction into AGENTS.md means the agent loads all of it into every request, whether it's relevant or not.
SKILL.md files address this through what the community calls progressive disclosure. Rather than front-loading everything, skills are discrete, reusable capability definitions that an agent retrieves only when the task calls for them. The agent reads the skill file when it needs to deploy to production or run a database migration — not on every single request.
As Red Hat Developer explains, the combination of AGENTS.md and Agent Skills creates a layered context architecture: persistent project-level context in AGENTS.md, and on-demand task-level context in skills. This keeps token usage manageable and the agent's working context relevant to what it's actually doing.
The debate about which approach is better misses the point. As Parth Vadhadiya notes on LinkedIn, AGENTS.md and skills aren't competing — they serve different purposes. AGENTS.md is always-on context; skills are retrieval-on-demand. Both are needed.
Why businesses need a context manifest too
Here is where the developer conversation has a direct parallel for operators and founders.
An AI coding agent working in a codebase without AGENTS.md will make reasonable-sounding guesses about project conventions, run the wrong test command, or modify files it should leave alone. The cost is a broken build or a bad pull request.
An AI business agent working without equivalent context will do the same thing at the operational level. Ask it about a customer commitment and it will hallucinate one. Ask it to draft a proposal and it will invent pricing. Ask it to summarise a deal and it will miss the three Slack threads where the actual negotiation happened.
The underlying problem is identical: the agent has no structured briefing about how this specific organisation works.
For a software project, that briefing is AGENTS.md. For a business, it needs to cover:
- What data exists and where — which systems hold customer records, which hold financial history, which hold internal decisions
- How the business operates — team structure, process conventions, terminology that means something specific here
- What the agent is permitted to do — which data it can read, which it can act on, who can see its outputs
- How to stay current — because the answer to "what did we promise Acme?" changes every week
A static markdown file can describe the first two. It cannot handle the last two at any useful scale.
The gap a markdown file cannot close
Developers writing AGENTS.md for a codebase are describing something that changes slowly. The build system, test conventions, and branching model of a mature project are relatively stable. A file written once stays accurate for months.
Business context changes daily. A deal closes. A pricing tier changes. A customer escalates. A new hire joins and starts making commitments in Slack. The AGENTS.md equivalent for a business would need to be rewritten constantly — or it becomes stale faster than anyone can maintain it.
This is the core limitation of any static context manifest for business use. The AI knowledge freshness problem isn't a documentation problem. It's an infrastructure problem. The context needs to be pulled from live systems, not written into a file.
There's also the permissions question. A codebase AGENTS.md is visible to anyone with repository access. Business context is more nuanced: some information is company-wide, some is team-specific, some is sensitive enough that only certain roles should see it. A markdown file has no way to enforce that.
What a business context manifest actually requires
Building the business equivalent of AGENTS.md means solving three things that the developer format takes for granted:
1. Live indexing from real systems
The context has to come from where work actually happens — Slack threads, Gmail, Notion pages, HubSpot deals, Salesforce records, QuickBooks transactions. Not from a document someone wrote about those systems. The document is already out of date.
This is what separates a genuine company brain from a knowledge base that someone maintains by hand. The indexing has to be continuous and automatic, or the manifest is stale by the time an agent reads it.
2. Permissioned access
Not every agent should see every piece of context. A sales agent working on a new prospect shouldn't surface confidential board communications. A customer support agent should see the customer's history but not internal cost discussions.
The context layer needs to enforce those boundaries at query time, not rely on the agent to self-police based on what's in a text file.
3. Source attribution
When an AI agent tells you what a customer was promised, you need to know where that answer came from. Was it a contract? A Slack message from six months ago? An email that was never formally agreed to? A context manifest that doesn't cite its sources produces answers that are impossible to verify — which means they can't be trusted for anything that matters.
This is why AI agents need source-cited context, not just retrieved text. The citation is part of the answer.
AGENTS.md vs a business context layer: what each handles
| Capability | AGENTS.md (developer) | Business context layer |
|---|---|---|
| Scope | Single codebase | Entire company, all systems |
| Update frequency | Manual, infrequent | Continuous, automatic |
| Permissions | Repository-level access | Role and team-based, enforced at query time |
| Source citation | Not applicable | Required — every answer cites its source |
| Skill/context loading | On-demand via SKILL.md | Permissioned MCP server per use case |
| Maintenance burden | Developer writes and updates | Managed indexing, no manual upkeep |
The developer pattern is the right instinct. The implementation for a business has to be different.
How Gyld approaches the business context manifest
Gyld is built around the same core insight as AGENTS.md: AI agents work better when they have structured, accurate context about the environment they're operating in. The difference is that the environment for a business is a collection of live systems, not a static codebase.
When you connect your company's apps to Gyld — Slack, Gmail, Notion, HubSpot, Salesforce, Google Drive, QuickBooks — it indexes that data into a per-company knowledge base. You choose what gets indexed. The knowledge is permissioned at the team and company level. Every answer an agent produces is source-cited back to the original document, message, or record.
That knowledge base is then exposed as MCP servers — the same Model Context Protocol that Claude Code, ChatGPT, Codex, and Cursor use to access external context. So the AI tools your team already uses can query your company's actual knowledge, with the same kind of structured briefing that AGENTS.md gives a coding agent, but built from live data rather than a file someone wrote once.
This is what connecting company data to AI agents looks like when the goal is operational accuracy rather than code generation.
The SKILL.md parallel for business agents
The progressive disclosure logic behind SKILL.md applies equally to business agents. A general-purpose agent doesn't need the full history of every customer relationship loaded into every request. It needs to retrieve the relevant customer context when a customer question comes up, and the relevant financial context when a financial question comes up.
Gyld's MCP server architecture handles this the same way SKILL.md handles it for developers: the agent queries for the context it needs at the moment it needs it, rather than receiving everything upfront. This keeps responses grounded in relevant information without overwhelming the agent's working context with data it isn't using.
For a deeper look at how this compares to building a RAG pipeline yourself, the build vs buy analysis covers the real maintenance costs that a static file or a hand-built retrieval system accumulates over time.
What to do with this today
If your team is running AI agents against business operations and hasn't thought about context manifests yet, start with the question the AGENTS.md community started with: what does an agent need to know to do useful work here, and where does that information actually live?
For most businesses, the answer spans at least five or six systems. That's the scope of the problem. A markdown file at the root of a repository won't cover it — but the instinct behind that file is exactly right.
The next step is deciding whether to build the indexing, permissioning, and freshness infrastructure yourself, or to use something that already handles it. The AI knowledge base tools comparison covers the main options available in 2026.
Frequently asked questions
What is AGENTS.md used for?
AGENTS.md is an open markdown format that gives AI coding agents structured context about a software project — build steps, test commands, conventions, and directory structure. It lives at the root of a repository and is read by agents like GitHub Copilot, OpenAI Codex, and Google Jules to understand how to work effectively in that codebase without guessing.
How is AGENTS.md different from SKILL.md?
AGENTS.md provides always-on project context that an agent loads at the start of every session. SKILL.md files are on-demand capability definitions that an agent retrieves only when it needs to perform a specific task. AGENTS.md is persistent background context; SKILL.md is targeted retrieval. Both are part of a layered context architecture, not competing approaches.
Do businesses need something like AGENTS.md?
Yes. AI agents working on business operations — answering questions about customers, drafting proposals, summarising deals — have the same need for structured context that coding agents have. Without it, they hallucinate or produce answers that can't be verified. The difference is that business context changes daily and spans multiple live systems, so a static markdown file isn't sufficient.
Why can't a business just write an AGENTS.md equivalent and maintain it manually?
Business context changes too fast. Customer commitments, pricing, team decisions, and deal status shift daily across Slack, email, CRM, and finance systems. A manually maintained file is stale within days. The context needs to be indexed continuously from live systems, not written once and forgotten.
What is a business context layer for AI?
A business context layer is the infrastructure that indexes a company's operational data from the apps it uses, enforces permissions on who can access what, and exposes that knowledge to AI agents in a form they can query. It plays the same role for a business that AGENTS.md plays for a codebase — giving agents accurate, structured context — but at company scale and with live data.
How does Model Context Protocol (MCP) relate to AGENTS.md?
MCP is the protocol that AI agents use to query external context at runtime. AGENTS.md is a static file that provides context at session start. A business context layer built on MCP servers combines both ideas: persistent company context that agents can query on demand, with permissions and source citations enforced at the protocol level.
What happens if AI agents operate without structured business context?
They produce confident-sounding answers based on training data and whatever is in their prompt — not on what your company has actually done or decided. That means wrong pricing, missed commitments, and outputs that can't be traced to a source. The problem isn't the model's capability; it's the absence of grounding in real company knowledge.
Related reading
- Best Tools to Connect Company Data to AI Agents in 2026 — a comparison of the main options for getting live business context into agents
- What a Context Layer Gives AI Agents That Bigger Models Cannot — why model size doesn't solve the grounding problem
- Why AI Answers About Your Business Go Stale: A Freshness Framework — the mechanics of knowledge decay and how to address it
- Build vs Buy Context Layer: The Real Cost of Keeping It Running — what it actually costs to maintain a hand-built retrieval system
If your AI agents are working without a structured view of how your business operates, start building your company brain at Gyld — connect the apps your team already uses and give every agent the context it needs to produce answers you can actually trust.