Knowledge Catalog for AI Agents: Make Your Business Discoverable

If you have asked ChatGPT or Gemini to find a local plumber lately, you have seen the problem: the assistant confidently recommends three companies, and yours is not one of them. That is not a ranking problem you fix with another blog post. AI agents discover businesses the way software does — by reading machine-readable files published at predictable addresses on your domain. The name for that layer is a knowledge catalog for AI agents: a small set of files (agent-card.json, llms.txt, and ai-catalog.json) that tells an agent who you are, what you sell, where you serve, what things roughly cost, and how to book you.

This guide explains what a knowledge catalog is, what each of the three files does and where each one lives, and how to build yours in five steps — with a worked example for a plumbing and HVAC business and a link to HiVergent's own live catalog files. If you want to skip straight to the tool, the free Agent Stack Builder generates all three files in about two minutes.

What a Knowledge Catalog for AI Agents Is (and Why You Need One)

Traditional SEO optimizes pages for humans scrolling a list of blue links. A knowledge catalog optimizes files for software that never sees your homepage at all. When an AI assistant is asked to "find an HVAC company that services McKinney, TX and quotes a compressor replacement," it increasingly does three things: it searches its own knowledge, it crawls the web for structured signals, and — when it acts as a true agent rather than a chatbot — it looks up machine-readable declarations of what businesses can do.

The behavioral shift behind this is measurable. Industry tracking throughout 2025 and 2026 has put zero-click search — queries that end without a click to any website — at roughly 58–69% of Google searches since AI Overviews rolled out, and Gartner has projected a 25% decline in traditional search volume by 2026. The discovery conversation is moving inside AI interfaces. We covered the ranking side of that shift in our AI search optimization blueprint; a knowledge catalog is the next layer down, aimed not at answers but at agents that take action — checking availability, comparing prices, and booking appointments on a customer's behalf.

For a home-service business, the practical difference is stark. Schema markup and FAQ content help an AI mention you. A knowledge catalog helps an agent understand and transact with you: what services you actually offer, which questions you answer from real jobs, whether you handle after-hours calls, and where a booking agent should go. If you would rather have a specialist build and maintain this layer for you, our Knowledge Catalog Building service covers it end to end.

The Three Files: agent-card.json, llms.txt, and ai-catalog.json

A complete knowledge catalog for AI agents is three files, each with a specific job and a specific home on your server:

1. agent-card.json — your agent skills declaration

This is the file the Agent2Agent (A2A) protocol — originally developed by Google, now under the Linux Foundation — defines as an agent's digital business card. The specification requires A2A servers to publish it at a permanent, IANA-registered well-known URI: /.well-known/agent-card.json. Each entry in its skills array describes one service with a machine-readable id, a human description, tags, and — critically — examples: real questions customers ask. Those examples are what help an agent match "why is my furnace short cycling?" to your furnace-repair skill instead of a competitor's page.

2. llms.txt — your curated content map

llms.txt is a plain-text file at your site root (not inside .well-known) that gives AI tools a curated, markdown-formatted map of your best content: services, pricing guide, service area, real customer questions, and policies. A 2026 honesty note that most guides skip: measured adoption sits around 42% of B2B SaaS sites and roughly 9% of the web's top domains, and controlled studies have not yet proven it increases AI citations — Google has even said it ignores the file for Search. We still recommend it for three reasons: it costs about fifteen minutes, coding agents and agentic-browsing tooling (Chrome now audits it under its agentic-browsing checks) do read these files, and a well-maintained llms.txt doubles as a genuinely useful sitemap for humans. Set expectations accordingly: it is a cheap hedge, not a magic ranking lever.

3. ai-catalog.json — your capability and content catalog

ai-catalog.json lives at /.well-known/ai-catalog.json and is the connective tissue between the other two. Where agent-card.json declares skills, ai-catalog.json catalogs capabilities and content endpoints: an agent-type entry pointing at your agent card, a content-type entry pointing at your llms.txt or knowledge base, and — most useful — representativeQueries: the actual questions you want to be the answer to, like "Who repairs heat pumps in Collin County?" It is a newer convention than agent-card.json, which is exactly why early adopters stand out.

How to Build Your Knowledge Catalog in 5 Steps

You can assemble all three files by hand, but the sequence below is the fastest reliable path — and it is exactly what the Agent Stack Builder automates for home-service trades:

1. Inventory your services. List every service you sell in plain words a customer would use — "water heater replacement," not "HD-50 unit swap." For each one, write the question a customer actually asks before they call.
2. Write machine-readable descriptions. For each service, write a one-to-two sentence description that states what it covers and any honest constraints (response times, price factors). Include price ranges and what moves them — never invent exact prices.
3. Generate the three files. Feed your inventory into a generator (or write the JSON by hand) to produce agent-card.json, ai-catalog.json, and llms.txt with consistent naming, service area, and contact details across all three.
4. Upload them. Put the two .json files in /.well-known/ at your domain and llms.txt at your site root. WordPress, cPanel, and most static hosts support this through file manager or FTP. Shopify, Wix, and Squarespace do not allow custom files at /.well-known/ — host them on a subdomain (for example agents.yourdomain.com) on free static hosting instead.
5. Verify. Visit each URL in a browser and confirm the JSON renders, run the files through a JSON validator, and check that names, phone, and service area match your Google Business Profile exactly. Re-verify quarterly — stale files are worse than none.

Worked Example: A Knowledge Catalog for a Plumbing & HVAC Business

Here is what step 3 produces for a fictional Dallas-area company, Acme Plumbing & HVAC — this is the actual agent-card.json structure the Agent Stack Builder emits (abbreviated to two skills):

{
  "name": "Acme Plumbing & HVAC",
  "description": "plumbing and HVAC service serving McKinney & Collin County, TX. Services: Water heater repair, Furnace repair.",
  "url": "https://acmeplumbinghvac.com/a2a",
  "provider": { "organization": "Acme Plumbing & HVAC", "url": "https://acmeplumbinghvac.com" },
  "version": "1.0.0",
  "capabilities": { "streaming": false, "pushNotifications": false },
  "authentication": { "schemes": [] },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "water-heater-repair",
      "name": "Water heater repair",
      "description": "No-hot-water diagnoses — thermostat vs element vs tank failure, pilot and gas-valve safety, and honest repair-vs-replace math for tanks over 10 years old.",
      "tags": ["plumbing-hvac", "home-service", "local"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain", "application/json"],
      "examples": ["Why is my water heater making a rumbling noise?", "How long should a 10-year-old water heater last?"]
    },
    {
      "id": "furnace-repair",
      "name": "Furnace repair",
      "description": "Gas and electric furnace failures — ignition and flame-sensor issues, short cycling, and safety-first guidance on cracked heat exchangers.",
      "tags": ["plumbing-hvac", "home-service", "local"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain", "application/json"],
      "examples": ["My furnace won't kick on — is it the thermostat?", "Why does my furnace run for 30 seconds and shut off?"]
    }
  ]
}

Notice what makes this agent-readable rather than just another marketing page: every skill has a stable id an agent can reference, a description that explains the diagnostic path, and examples written as real customer questions. The companion llms.txt for Acme would list its services with links, its pricing guide, its service area, its FAQ questions, and a short "Rules for AI agents" section — for instance, instructing agents to quote only from the published pricing guide rather than guessing.

Live Example: HiVergent's Own Knowledge Catalog

We practice what this post preaches. HiVergent AI publishes its own catalog at the exact addresses described above — you can read both files right now, no login required:

• https://hivergentai.com/.well-known/agent-card.json — seven declared skills, one for every service line we sell (including Knowledge Catalog Building), each with its published pricing and example customer questions.
• https://hivergentai.com/.well-known/ai-catalog.json — a capability entry pointing at our agent card plus content entries for our service pages and llms.txt, each with representative queries like "Who builds knowledge catalogs for AI agents in Dallas?"

That is the whole pattern: declare skills, catalog capabilities, map content, and keep the three consistent. The deeper strategy — how this fits with schema markup, reviews, and zero-click reality — is in our home services SEO, GEO, and AEO guide.

Common Mistakes That Quietly Break an Agent Catalog

• Inventing exact prices. Agents quote what your files say. If your card claims a fixed price your technicians would never honor, the agent books you into an argument. Publish ranges and what moves them.
• Putting llms.txt inside /.well-known/. It belongs at the site root. The well-known directory is for files with a registered or conventional purpose; llms.txt is not one of them.
• Set-and-forget files. A catalog with a disconnected phone number, a closed service area, or last year's services actively misleads agents — and customers. Mark a last_verified date and refresh quarterly.
• Keyword stuffing the descriptions. Write for the customer's question, not for a keyword list. Agent models chunk and rank by clarity, exactly as answer engines do.
• Inconsistency across the web. Agents cross-reference your catalog against your Google Business Profile and directories. Conflicting hours, phones, or service areas get you excluded rather than quoted.

Agents are moving from answering questions to completing jobs, and the businesses they can read are the ones they recommend. For the workflow side of that shift — how roles change when agents do the booking — see our piece on the rise of the skills engineer.