agentmarkup

Build-time llms.txt, optional llms-full.txt, optional A2A Agent Cards, JSON-LD, markdown mirrors, AI crawler controls, and validation for Vite, Astro, Next.js, and Nuxt websites, plus a framework-agnostic CLI for any static output.

What This Repo Contains

• packages/core — the framework-agnostic engine used by adapters and manual pipelines
• packages/vite — the publishable @agentmarkup/vite adapter
• packages/astro — the publishable @agentmarkup/astro adapter
• packages/next — the publishable @agentmarkup/next adapter
• packages/cli — the publishable @agentmarkup/cli, a framework-agnostic command that runs agentmarkup over any built static output directory (with a CI-friendly check command)
• packages/nuxt — the publishable @agentmarkup/nuxt module for prerendered / nuxt generate output
• packages/audit — the publishable @agentmarkup/audit, a runtime CLI that fetches a live URL as each major AI crawler, diffs against a browser, and reports machine-readability findings (CI-friendly)
• website — the dogfooding landing page built against the workspace package boundary
• examples/vite-react — a minimal example app for local verification and onboarding

Quick Start

Choose the adapter that owns your final output:

• @agentmarkup/vite for Vite
• @agentmarkup/astro for Astro
• @agentmarkup/next for Next.js
• @agentmarkup/nuxt for Nuxt (prerendered / nuxt generate output)
• @agentmarkup/cli for any other built static site, or as a CI check

pnpm add -D @agentmarkup/vite
# or: pnpm add -D @agentmarkup/astro
# or: pnpm add -D @agentmarkup/next
# or: pnpm add -D @agentmarkup/nuxt
# or: pnpm add -D @agentmarkup/cli

Vite example:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { agentmarkup } from '@agentmarkup/vite';

export default defineConfig({
  plugins: [
    react(),
    agentmarkup({
      site: 'https://example.com',
      name: 'Example',
      description: 'Structured, machine-readable metadata for your site.',
      llmsTxt: {
        sections: [
          {
            title: 'Pages',
            entries: [
              {
                title: 'Docs',
                url: '/docs',
                description: 'Documentation and guides',
              },
            ],
          },
        ],
      },
      markdownPages: {
        enabled: true,
      },
      contentSignalHeaders: {
        enabled: true,
      },
      globalSchemas: [
        {
          preset: 'webSite',
          name: 'Example',
          url: 'https://example.com',
        },
      ],
      aiCrawlers: {
        GPTBot: 'allow',
        ClaudeBot: 'allow',
      },
    }),
  ],
});

On build, the adapters can:

• emit optional /.well-known/agent-card.json for existing A2A services
• emit llms.txt
• emit optional llms-full.txt with inlined same-site markdown context
• inject the homepage llms.txt discovery link automatically
• inject JSON-LD into generated HTML
• validate JSON-LD already present in page HTML
• emit page-level .md mirrors from final HTML output when a cleaner agent-facing fetch path is useful
• patch or create robots.txt with AI crawler directives, including the canonical Content-Signal policy alongside the crawler rules
• patch or create _headers, or merge server header rules, with the Content-Signal header and canonical Link headers for markdown mirrors
• report deterministic validation warnings and errors in the terminal, including markdown alternate-link and mirror-coverage issues

By default, agentmarkup coexists with existing machine-readable assets. If a site already has a curated llms.txt, matching crawler rules, or hand-authored JSON-LD for a schema type, those are preserved unless you explicitly opt into replacement.

Optional A2A Agent Card support is intentionally narrow. If you already run a real A2A-compatible agent service, agentmarkup can emit a static /.well-known/agent-card.json discovery file for that service from the same build pipeline. It does not implement the A2A runtime protocol or agent server itself. When you enable agentCard, provide a version, at least one supportedInterfaces entry, and a non-empty description through either the top-level description or agentCard.description.

Markdown mirrors are optional. They are usually most useful for thin, noisy, or client-rendered HTML where the raw page is a poor fetch target for agents. When enabled, same-site page entries in llms.txt default to the generated .md URLs so cold agents discover the cleaner fetch path first. Set llmsTxt.preferMarkdownMirrors: false if you want llms.txt to keep pointing at HTML routes instead.

If your site already has a custom prerender or post-build step, @agentmarkup/core exposes reusable llms.txt, JSON-LD, and robots.txt helpers so you can keep one final output pipeline instead of duplicating that logic.

@agentmarkup/vite is best when Vite owns the final HTML files. Meta-frameworks that render or prerender final HTML after Vite's build phases may still benefit from llms.txt and robots.txt, but they usually need either @agentmarkup/core in the final output step or a dedicated adapter to guarantee JSON-LD reaches the deployed HTML.

@agentmarkup/next is best when Next owns the final build output. Static export gets the full post-build file flow, prerendered and server deployments still get generated assets plus header integration, but fully dynamic SSR routes are still a per-route integration point: if Next does not emit build-time HTML for that route, use the re-exported @agentmarkup/core helpers directly inside app code.

@agentmarkup/nuxt is best when Nuxt prerenders your pages (nuxt generate or prerender: true). It hooks Nitro after prerendering and processes the emitted .output/public HTML. Fully dynamic SSR routes that never emit build-time HTML are not patched automatically; use the re-exported @agentmarkup/core helpers in app code for those.

@agentmarkup/cli is framework-agnostic: point it at any built static output directory (agentmarkup generate ./dist) to run the same pipeline without an adapter, or use agentmarkup check ./dist as a CI gate that fails on machine-readability errors. Useful for static site generators without a dedicated adapter and for validating already-deployed output.

Current Features

• Vite, Astro, Next.js, and Nuxt adapters, plus a framework-agnostic CLI
• optional A2A Agent Card generation plus config and output validation
• llms.txt generation
• optional llms-full.txt generation
• optional llmsTxt.whenToUse guidance so agents learn when to reach for the site
• automatic llms.txt discovery-link injection
• JSON-LD injection
• existing JSON-LD validation
• markdown page generation, with markdownPages.exclude for pages that should not be mirrored
• markdown alternate-link and mirror-coverage validation
• schema presets for website and ecommerce basics
• AI crawler robots.txt management
• Content-Signal policy generation in robots.txt and the _headers header
• deterministic validation checks
• reusable generation and validation helpers for custom prerender pipelines

Local Development

pnpm install
pnpm lint
pnpm test
pnpm typecheck
pnpm build

Package details live in packages/vite/README.md, packages/astro/README.md, packages/next/README.md, packages/cli/README.md, packages/nuxt/README.md, and packages/core/README.md. Contribution guidelines live in CONTRIBUTING.md.

Website deploys are manual via ./deploy/website-deploy.sh.

Claude Code plugin

This repo is also a Claude Code marketplace. Install the plugin from it:

/plugin marketplace add agentmarkup/agentmarkup
/plugin install agentmarkup@agentmarkup

Then, in the repo you want to set up, say what you want, for example "set up llms.txt and JSON-LD for this site". The skill is model-invoked, so there is no command to remember.

It works out which layer owns your final HTML, installs the matching package, patches the config, builds, and audits the result. Inspecting your repo is read-only; it asks for approval as a single plan before installing anything, writing config, running a build, or making an outbound audit request.

Plugin source lives in plugins/agentmarkup.

Public Agent Skill

This repo ships a public Agent Skills / skills.sh-compatible skill at skills/agentmarkup.

Use it to install AgentMarkup in another JavaScript web repo, configure it from user preferences, audit generated output, and implement fixes for llms.txt, llms-full.txt, JSON-LD, markdown mirrors, AI crawler rules, and headers.

Install with the skills CLI:

npx skills add agentmarkup/agentmarkup --skill agentmarkup

Preview with GitHub CLI:

gh skill preview agentmarkup/agentmarkup agentmarkup

Invoke it without installing:

npx skills use agentmarkup/agentmarkup --skill agentmarkup

After installing it, ask your coding agent to use $agentmarkup inside the target website repo.

Example prompts:

Use $agentmarkup to install AgentMarkup in this repo, configure it for my public site, run an audit, and implement the fixes.

Use $agentmarkup to add llms.txt, JSON-LD, markdown mirrors, AI crawler rules, and Content-Signal headers to this Vite/Astro/Next.js site.

Use $agentmarkup to inspect this custom post-build pipeline, choose @agentmarkup/core if appropriate, and wire the generated assets into the final deploy output.

Maintainer

Copyright (c) 2026 Sebastian Cochinescu. MIT License.

Used in production on Anima Felix.