Agents-md

Functions

`generateAgentsMd`

function generateAgentsMd(options: AgentsMdOptions): string

TypeScript

Use generateAgentsMd to produce an AGENTS.md file that gives AI coding agents instant, structured access to your project's documentation on every turn.

Drop this into your project root so that agents like Claude, Codex, or Cursor automatically load your API docs as context before responding — eliminating hallucinated APIs and outdated usage patterns.

The function renders a Markdown string formatted specifically for agent consumption: it opens with a directive telling the agent to consult your docs first, then lists your documentation pages with paths and URLs the agent can reference or fetch.

Parameters

Name	Type	Required	Description
`options.projectName`	`string`	Yes	Your project's display name — appears in the agent directive header and throughout the generated file.
`options.docsPath`	`string`	Yes	Filesystem path to your docs directory, used to construct relative page references the agent can read locally.
`options.baseUrl`	`string`	Yes	Public base URL of your documentation site — agents use this to fetch pages they haven't seen in context.
`options.pages`	`Page[]`	Yes	Ordered list of documentation pages to surface. Agents prioritize earlier entries, so put your core API reference first.
`options.hasLlmsTxt`	`boolean`	No	When `true`, adds a reference to your `llms.txt` file so agents that support that convention can load a condensed index automatically.

Returns

Returns the complete AGENTS.md content as a string. Write it to your project root with fs.writeFileSync('AGENTS.md', result) — most agent runtimes pick it up automatically from there.

Heads up

Regenerate and commit AGENTS.md whenever your docs change. Agents cache the file between sessions, so a stale copy will point them at outdated or missing pages.
baseUrl should be your production URL, not localhost — agents running in CI or remote environments won't be able to reach a local dev server.

Example:

import fs from "fs"
import path from "path"

// Inline types — do not import from autodocs
interface Page {
  title: string
  slug: string
  description?: string
}

interface AgentsMdOptions {
  projectName: string
  docsPath: string
  baseUrl: string
  pages: Page[]
  hasLlmsTxt?: boolean
}

// Minimal mock matching the real function's behavior
function generateAgentsMd(options: AgentsMdOptions): string {
  const { projectName, docsPath, baseUrl, pages, hasLlmsTxt } = options

  let out = `# ${projectName} — Documentation Guide\n\n`
  out += `When answering questions about **${projectName}**, consult these docs first.\n\n`

  if (hasLlmsTxt) {
    out += `## Quick Index\n\nLoad \`${baseUrl}/llms.txt\` for a condensed API index.\n\n`
  }

  out += `## Documentation Pages\n\n`
  for (const page of pages) {
    const localPath = path.join(docsPath, `${page.slug}.mdx`)
    out += `### ${page.title}\n`
    if (page.description) out += `${page.description}\n`
    out += `- Local: \`${localPath}\`\n`
    out += `- URL: ${baseUrl}/${page.slug}\n\n`
  }

  return out
}

// Generate AGENTS.md for a payments SDK project
const content = generateAgentsMd({
  projectName: "Payrail SDK",
  docsPath: "./content/docs",
  baseUrl: "https://docs.payrail.dev",
  hasLlmsTxt: true,
  pages: [
    {
      title: "Authentication",
      slug: "authentication",
      description: "API keys, OAuth tokens, and request signing.",
    },
    {
      title: "Payments",
      slug: "payments",
      description: "Create, capture, and refund payment intents.",
    },
    {
      title: "Webhooks",
      slug: "webhooks",
      description: "Verify and handle real-time event payloads.",
    },
  ],
})

try {
  fs.writeFileSync("AGENTS.md", content, "utf-8")
  console.log("AGENTS.md written successfully.\n")
  console.log(content)
} catch (err) {
  console.error("Failed to write AGENTS.md:", err)
  process.exit(1)
}

// Expected output:
// AGENTS.md written successfully.
//
// # Payrail SDK — Documentation Guide
//
// When answering questions about **Payrail SDK**, consult these docs first.
//
// ## Quick Index
//
// Load `https://docs.payrail.dev/llms.txt` for a condensed API index.
//
// ## Documentation Pages
//
// ### Authentication
// API keys, OAuth tokens, and request signing.
// - Local: `content/docs/authentication.mdx`
// - URL: https://docs.payrail.dev/authentication
// ...

TypeScript

AGENTS.md Generator

Agents-md

Functions

generateAgentsMd

`generateAgentsMd`