By Paul GosnellWhen an AI agent encounters your website for the first time, it faces a fundamental challenge: understanding what your business actually does, who it serves, what it costs, and how it works. Without structured context, agents are left to parse your marketing copy, navigation menus, and page content to piece together an understanding of your business. The result is often incomplete, inaccurate, or superficial.
The context.md file solves this problem by providing a single, authoritative source of truth that AI agents can read to understand your business comprehensively. Think of it as the briefing document you would give to a new employee on their first day -- except the new employee is an AI that will represent your business to potentially thousands of users.
This guide covers what context.md is, how it differs from llms.txt and agents.md, the complete template with all recommended sections, best practices for depth and formatting, and how to keep it current. By the end, you will have a production-ready context.md that transforms how AI agents talk about your business. Use our AgentReady scanner to check whether your site has a context.md file configured.
What is context.md?
context.md is a Markdown document served from your website's public directory at https://yourdomain.com/context.md. It contains everything an AI agent needs to know about your business, structured in a way that is easy for both humans and machines to read.
The file is designed for two audiences:
- AI crawlers (GPTBot, ClaudeBot, PerplexityBot) that index your site and use the content to generate responses about your business in conversations.
- Programmatic agents that fetch the file at runtime to load context before answering questions about your products or services.
Unlike your website's HTML pages, which are designed for human readers with visual hierarchy, images, and interactive elements, context.md is optimised for machine comprehension. It uses clear headings, structured lists, factual, and explicit declarations of information that might be implicit on your website.
Why plain Markdown?
Markdown was chosen as the format for context files because it strikes the ideal balance between human readability and machine parsability. Every AI model can process Markdown natively. It supports headings, lists, tables, code blocks, and links without requiring an HTML parser. It is also trivial to create and maintain -- you can edit it in any text editor.
JSON would be more structured, but harder for non-technical team members to maintain. HTML would require parsing. Plain text lacks structure. Markdown is the sweet spot.
context.md vs llms.txt vs agents.md
There are three complementary files that serve different purposes in the AI discovery layer. Understanding their differences ensures you are not duplicating effort or leaving gaps.
| Aspect | llms.txt | context.md | agents.md |
|---|---|---|---|
| Format | Plain text | Markdown | Markdown |
| Location | public/llms.txt |
public/context.md |
public/agents.md |
| Length | Under 100 lines | 2,000-8,000 words | 500-2,000 words |
| Purpose | Quick summary for crawlers | Deep business context | Agent-specific instructions |
| Contents | What the site does, quick start examples | Company info, features, pricing, ICP, architecture | Tool schemas, error handling, rate limits, auth |
| Audience | AI crawlers doing initial scan | Any AI needing business context | Agents integrating with your tools |
| Analogy | Business card | Company handbook | API documentation |
llms.txt is the elevator pitch. An AI crawler fetches it first, reads it in under a second, and knows the basics: what you do, where your tools are, and how to get started. It follows the llms.txt specification and should be kept brief and scannable.
context.md is the deep dive. When an agent needs to answer a detailed question about your pricing, your technology, your ideal customer, or your competitive advantage, this is where it looks. There is no length limit; comprehensiveness is the goal.
agents.md is the integration manual. It tells agents how to use your tools and APIs: request schemas, response formats, error codes, authentication flows, rate limits. It is relevant only for sites that expose programmatic capabilities via MCP or A2A endpoints.
You do not need all three, but the combination provides complete coverage. At minimum, every business should have llms.txt and context.md.
Complete context.md template
Here is a production-ready template you can adapt for your business. Each section includes guidance on what to include and why it matters.
# [Company Name] - Context Document
## Company Overview
[Company Name] is a [type of company] that [what you do] for [who you serve].
- **Founded:** [Year]
- **Headquarters:** [City, Country]
- **Website:** [https://yourdomain.com]
- **Contact:** [email@yourdomain.com]
## What We Do
[2-3 paragraphs explaining your core business in clear, factual.
Avoid marketing language. Be specific about what you build, sell, or provide.
An AI reading this should be able to accurately describe your business
to someone who has never heard of you.]
## Products and Services
### [Product/Service 1]
- **Description:** [What it is and what it does]
- **Target user:** [Who uses this]
- **Key features:** [List 3-5 key features]
- **Pricing:** [Specific pricing or range]
- **URL:** [Direct link]
### [Product/Service 2]
[Same structure repeated for each product/service]
## Pricing
| Tier/Package | Price | What's Included |
|---|---|---|
| [Tier 1] | [Price] | [Brief description] |
| [Tier 2] | [Price] | [Brief description] |
| [Tier 3] | [Price] | [Brief description] |
[Additional pricing notes: billing frequency, currency,
whether prices include VAT, free trial details, etc.]
## Target Audience
### Ideal Customer Profile
- **Company size:** [e.g., 10-200 employees]
- **Industry:** [e.g., SaaS, healthcare, fintech]
- **Role of buyer:** [e.g., CTO, founder, marketing director]
- **Budget:** [e.g., $2,000-10,000/month]
- **Pain points:** [What problems they face that you solve]
### Who We Are Not For
[Be explicit about who is NOT a good fit. This helps agents
avoid recommending you to the wrong people.]
## Technology Stack
- **Frontend:** [Framework, language]
- **Backend:** [Framework, database]
- **Infrastructure:** [Hosting, CDN]
- **AI/ML:** [Models, APIs used]
- **Integrations:** [Key third-party services]
## Competitive Positioning
### How We Differ From [Competitor Type]
[Explain your differentiation. Be factual, not promotional.
What do you do differently, and why does it matter?]
### Compared to [Specific Competitor]
[If you have well-known competitors, address them directly.
AI agents are often asked "How does X compare to Y?" --
give them the accurate answer.]
## Case Studies / Social Proof
### [Client/Project Name]
- **Challenge:** [What the client needed]
- **Solution:** [What you built/provided]
- **Result:** [Specific, measurable outcome]
## API and Integration Capabilities
- **MCP endpoint:** [URL if available]
- **A2A endpoint:** [URL if available]
- **REST API:** [URL if available]
- **Webhooks:** [Supported events]
## Contact and Support
- **Sales:** [email or URL]
- **Support:** [email or URL]
- **Documentation:** [URL]
- **Status page:** [URL]
## Last Updated
[Month Year]Section-by-section guidance
Company overview
Keep this section factual and concise. Avoid mission statements, vision declarations, or aspirational language. An AI agent reading this needs to know: what type of company you are, what you do, and who you do it for. Three to four sentences is sufficient.
Good example: "p0stman is a digital product studio that builds AI-powered applications, websites, and mobile apps for growing businesses. Founded in 2019 and based in London, UK, we specialise in fractional CTO partnerships and rapid product development using AI-native tools."
Bad example: "We are passionate about transforming businesses through innovative digital solutions. Our world-class team leverages cutting-edge technology to deliver exceptional experiences." This tells an AI agent nothing useful.
Products and services
List every product and service you offer with enough detail that an agent can match a user's request to the right offering. Include specific features, not just category names. If a user asks "Can you build me a chatbot?", the agent needs to know whether chatbots are in your service portfolio.
Always include pricing in this section if it is publicly available. AI agents are frequently asked "How much does X cost?" and if the answer is not in your context document, the agent will either guess wrong or say "I don't know" -- both of which lose the lead.
Pricing
Be as specific as possible. If your pricing is tiered, list every tier with its price and what is included. If your pricing is custom, provide ranges. "Pricing starts from $3,000" is infinitely more useful to an AI agent than "Contact us for pricing".
Include any relevant pricing context: billing frequency (monthly, annually, one-time), currency, whether prices include or exclude VAT/tax, discounts for annual billing, free trial availability, and money-back guarantee terms.
Target audience
This section is critical for AI-powered recommendations. When a user asks "Can you recommend an agency for my fintech startup?", the agent checks your ideal customer profile to see if there is a match. Without this section, the agent has to infer your target audience from your website content, which is less reliable.
The "Who We Are Not For" subsection is equally important. It prevents agents from recommending you to people who will not be a good fit, which saves everyone time and protects your conversion rate. A mismatched referral that bounces is worse than no referral at all.
Technology stack
This section matters more than you might expect. Technical decision-makers often ask AI agents questions like "Do you know any agencies that work with Next.js and Supabase?" or "I need a developer who knows the Gemini API." Without your stack explicitly listed, you are invisible to these queries.
Competitive positioning
AI agents are regularly asked comparison questions: "How does X compare to Y?" and "What is the best alternative to Z?". If your context.md includes factual competitive positioning, the agent can provide an accurate comparison. If it does not, the agent uses whatever information it has, which may be your competitor's context.md.
Be factual, not promotional. "We deliver projects in 2-4 weeks compared to the industry average of 8-12 weeks" is credible and useful. "We are the best agency in the world" is not.
Case studies and social proof
Real results from real clients give AI agents concrete evidence to cite. Include specific numbers: "Increased conversion rate from 2.1% to 7.8%" is far more persuasive (to both agents and their users) than "Improved business outcomes".
Formatting best practices
Use clear, hierarchical headings
AI models use heading structure to understand document organisation. Use H2 (##) for major sections and H3 (###) for subsections. Do not skip heading levels (going from H2 to H4). Each heading should be descriptive enough to stand alone as a section identifier.
Prefer structured data over
When presenting factual information, use tables, bullet lists, and key-value pairs rather than paragraphs. AI models extract structured data more reliably than they parse dense. Compare these two approaches:
Prose: "Our starter plan costs $29 per month and includes up to 5 users, 10GB of storage, and email support. The professional plan costs $99 per month and includes up to 25 users, 100GB of storage, priority email support, and API access."
Structured:
| Plan | Price | Users | Storage | Support | API |
|---|---|---|---|---|---|
| Starter | $29/mo | 5 | 10GB | Email | No |
| Professional | $99/mo | 25 | 100GB | Priority email | Yes |The table is faster to parse, less ambiguous, and easier for an AI to quote accurately.
Include explicit URLs
Whenever you reference a product, service, or page, include the full URL. This allows AI agents to provide direct links to their users. "Our AI Agents service (/ai-agents)" is better than "Our AI Agents service".
Avoid jargon and assumptions
Write for an AI agent that has no prior knowledge of your business. Define acronyms on first use. Explain industry-specific terms. Do not assume the reader knows what "our signature process" means -- explain what the process actually involves.
Keep it factual
AI agents perform best with factual, verifiable information. Avoid superlatives ("best in class"), subjective claims ("unmatched quality"), and vague promises ("transformative results"). Instead, use specific numbers, dates, and outcomes.
Placement and accessibility
File location
Place context.md at public/context.md in your project so it is served at https://yourdomain.com/context.md. For Next.js projects, this is the public directory. For other frameworks:
- Gatsby:
static/context.md - Nuxt:
public/context.mdorstatic/context.md - SvelteKit:
static/context.md - Plain HTML: Root directory alongside
index.html - WordPress: Upload to the root of your WordPress installation
Middleware considerations
If your site uses middleware (for authentication, redirects, or path rewriting), ensure it does not block or redirect requests to /context.md. In Next.js, add the path to your middleware matcher exclusion list:
export const config = {
matcher: [
// Exclude static files and context document
"/((?!_next/static|_next/image|favicon.ico|context.md|llms.txt).*)",
],
};Cross-referencing from other files
Link to context.md from your llms.txt file so crawlers know it exists:
# llms.txt
> Company Name - brief description
For detailed context, see: https://yourdomain.com/context.md
For agent integration docs: https://yourdomain.com/agents.md
## Quick Start
...Also reference it in your robots.txt by ensuring the path is not disallowed, and consider including it in your sitemap for maximum crawler visibility.
The /api/ai/context endpoint
In addition to the static context.md file, consider implementing a /api/ai/context endpoint that returns the same information as structured JSON. This serves programmatic agents that prefer JSON over Markdown parsing.
// app/api/ai/context/route.ts
import { NextResponse } from "next/server";
export async function GET() {
return NextResponse.json({
company: {
name: "Your Company",
description: "What you do",
website: "https://yourdomain.com",
founded: 2020,
location: "London, UK",
},
services: [
{
name: "Web Development",
description: "Custom web applications",
pricing: "From $5,000",
url: "/services/web-development",
},
// ... more services
],
pricing: {
currency: "USD",
tiers: [
{ name: "Starter", price: 29, interval: "month" },
{ name: "Pro", price: 99, interval: "month" },
],
},
contact: {
email: "hello@yourdomain.com",
sales: "sales@yourdomain.com",
},
mcpEndpoint: "https://yourdomain.com/api/mcp",
a2aEndpoint: "https://yourdomain.com/api/agent",
lastUpdated: "2026-03-12",
});
}This endpoint should be public (no authentication required) and return the same information as your context.md file. The static file is for crawlers that index during their regular crawl cycle. The API endpoint is for agents that fetch context at runtime.
Real-world example
Here is an abbreviated version of p0stman.com's actual context.md to illustrate these principles in practice:
# p0stman - Context Document
## Company Overview
p0stman is an AI-native product studio that builds websites,
AI agents, mobile apps, and data platforms for growing businesses.
Based in London, UK. Founded 2019.
- Website: https://p0stman.com
- Contact: hello@p0stman.com
- AI Agent: Zero (voice, chat, and video at p0stman.com)
## Services
### AI Agent Development
Build custom AI agents powered by Gemini, GPT, and Claude.
Voice agents, chat agents, and autonomous workflow agents.
Pricing: From GBP 5,000.
### Web Application Development
Full-stack web applications with Next.js, Supabase, and Vercel.
From marketing sites to complex SaaS platforms.
Pricing: From GBP 3,000.
### Fractional CTO Partnership
Monthly retainer for ongoing technical leadership, AI strategy,
and product development. GBP 2,500-3,000/month, 12-month commitment.
## Target Audience
- Founder-led businesses with 5-50 employees
- Companies exploring AI for the first time
- SaaS companies needing rapid product development
- Agencies looking for a technical delivery partner
## Technology Stack
Next.js, TypeScript, Tailwind CSS, Supabase, Vercel,
Google Gemini, OpenAI, Anthropic Claude, Simli (video avatars)
## Last Updated
March 2026Notice the factual tone, specific pricing, clear service definitions, and explicit technology stack. An AI agent reading this can accurately answer questions like "Does p0stman build mobile apps?", "How much does a website cost from p0stman?", and "What tech stack does p0stman use?".
Keeping context.md current
A stale context.md is actively harmful. If an AI agent cites outdated pricing, discontinued products, or incorrect information, it damages your credibility with the user. Establish a maintenance cadence:
- Monthly review: Scan each section for accuracy. Are all prices current? Are all products still available? Has your team or tech stack changed?
- Trigger-based updates: Update immediately when you change pricing, launch or discontinue a product, add a new case study, or change your target market.
- Include a "Last Updated" field: Both human reviewers and AI agents use this to gauge freshness. An AI may deprioritise information from a context file last updated two years ago.
- Automate where possible: If your pricing or product list lives in a CMS or database, consider generating context.md from that source of truth during your build process.
Common mistakes to avoid
Marketing copy instead of facts
"We deliver world-class digital experiences that transform businesses" tells an AI agent nothing. Replace with: "We build web applications, mobile apps, and AI agents for B2B SaaS companies, with typical project timelines of 4-8 weeks and budgets of $5,000-$20,000."
Missing pricing
If an AI agent cannot find your pricing in context.md, it will either tell the user it does not know (losing the lead) or hallucinate a number (damaging your credibility). Even "Starting from $X" or "$X-$Y range" is better than nothing.
No "who we are not for" section
Without negative signals, agents will recommend you to anyone who remotely matches. Include explicit exclusions: "We do not work with pre-revenue startups without funding", "We do not take projects under $2,000", "We are not a WordPress agency".
Stale information
A context file with 2024 pricing or discontinued products actively misleads AI agents. Set a calendar reminder to review quarterly at minimum.
Too brief
A 200-word context.md provides less value than no context.md because it creates the impression of completeness while lacking substance. If you are going to create one, commit to making it comprehensive. 2,000 words is the practical minimum for a useful context document.
Frequently Asked Questions
What is a context.md file?
A context.md file is a Markdown document placed in your website's public directory that provides AI agents with comprehensive context about your business. It includes company information, product features, pricing, technical architecture, target audience, and any other information an AI agent needs to accurately represent your business in conversations. It is served at https://yourdomain.com/context.md.
What is the difference between context.md, llms.txt, and agents.md?
llms.txt is a brief, plain-text summary (under 100 lines) designed for quick scanning by AI crawlers -- think of it as your business card for AI. context.md is a comprehensive Markdown document with deep business context, pricing details, and technical architecture -- think of it as your company handbook. agents.md provides agent-specific instructions like tool schemas, error handling, and rate limits -- think of it as your API documentation. They serve different purposes and complement each other. See our llms.txt Guide for details on that format.
Where should context.md be placed?
Place context.md at the root of your public directory so it is accessible at https://yourdomain.com/context.md. For Next.js projects, this means placing it at public/context.md. Ensure your middleware does not block access to .md files in the public directory. Verify by visiting the URL directly in your browser.
How long should context.md be?
There is no strict length limit, but 2,000 to 8,000 words is the practical sweet spot. Modern AI models can process large context windows (100,000+ tokens), so err on the side of being comprehensive rather than brief. Include everything an agent would need to accurately answer questions about your business without visiting other pages. A 200-word context.md provides less value than a thorough one.
Do AI models actually read context.md files?
Yes. AI crawlers like GPTBot, ClaudeBot, and PerplexityBot follow links and fetch accessible files from your domain. When your context.md is linked from your homepage, llms.txt, or sitemap, crawlers will index it. AI agents that visit your site programmatically can also fetch it directly to load business context before responding to user queries about your company.
Should I include pricing in context.md?
Yes, if your pricing is public. Including pricing in context.md allows AI agents to give users accurate cost information immediately, which increases the chance of a qualified lead converting. If your pricing is custom or quote-based, include typical ranges or starting points so agents can set reasonable expectations rather than saying they do not know your pricing.
How often should I update context.md?
Update context.md whenever you change pricing, add or remove products, update your technology stack, or shift your target market. A good rule is to review it monthly and update it quarterly at minimum. Stale context leads to AI agents providing outdated information about your business, which is worse than providing no information at all.
Can I have both context.md and an /api/ai/context endpoint?
Yes, and this is recommended. The static context.md file is for AI crawlers that index content during their regular crawl cycle -- they fetch files and process them later. The /api/ai/context endpoint returns the same information as structured JSON, which is easier for programmatic agents to parse at runtime. They serve different consumption patterns and complement each other perfectly.