feat: add agentmarkup plugin for AI-readable website metadata

plugins/README.md

@@ -12,6 +12,7 @@ Learn more in the [official plugins documentation](https://docs.claude.com/en/do
 
 | Name | Description | Contents |
 |------|-------------|----------|
+| [agentmarkup](./agentmarkup/) | Make websites machine-readable for LLMs and AI agents with llms.txt, llms-full.txt, JSON-LD, markdown mirrors, and AI crawler directives | **Command:** `/agentmarkup` - Analyze project and set up machine-readable assets with the right adapter or manual approach<br>**Skill:** `agentmarkup` - Auto-invoked for site metadata, agent-readable assets, and structured data work |
 | [agent-sdk-dev](./agent-sdk-dev/) | Development kit for working with the Claude Agent SDK | **Command:** `/new-sdk-app` - Interactive setup for new Agent SDK projects<br>**Agents:** `agent-sdk-verifier-py`, `agent-sdk-verifier-ts` - Validate SDK applications against best practices |
 | [claude-opus-4-5-migration](./claude-opus-4-5-migration/) | Migrate code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5 | **Skill:** `claude-opus-4-5-migration` - Automated migration of model strings, beta headers, and prompt adjustments |
 | [code-review](./code-review/) | Automated PR code review using multiple specialized agents with confidence-based scoring to filter false positives | **Command:** `/code-review` - Automated PR review workflow<br>**Agents:** 5 parallel Sonnet agents for CLAUDE.md compliance, bug detection, historical context, PR history, and code comments |

plugins/agentmarkup/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "agentmarkup",
+  "version": "1.0.0",
+  "description": "Make websites machine-readable for LLMs and AI agents with llms.txt, llms-full.txt, JSON-LD, markdown mirrors, and AI crawler directives",
+  "author": {
+    "name": "Sebastian Cochinescu",
+    "url": "https://github.com/cochinescu"
+  }
+}

plugins/agentmarkup/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Cochinescu and Anima Felix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/agentmarkup/README.md

@@ -0,0 +1,76 @@
+# Agent Markup Plugin
+
+Make websites machine-readable for LLMs and AI agents using the current `agentmarkup` toolchain: `llms.txt`, optional `llms-full.txt`, JSON-LD, markdown mirrors, AI crawler directives, and agent-facing headers.
+
+## What It Does
+
+This plugin helps developers add machine-readable assets to their web projects so AI agents and LLMs can understand and interact with their sites.
+
+It covers five areas:
+- **`llms.txt`** — a standardized manifest that describes site content for LLMs
+- **`llms-full.txt`** — optional inlined same-site context for deeper agent fetches
+- **JSON-LD structured data** — schema.org markup that gives pages semantic meaning
+- **Markdown mirrors** — optional `.md` pages for cleaner agent-facing fetch targets
+- **AI crawler and header directives** — `robots.txt`, `_headers`, `Content-Signal`, and canonical `Link` headers where appropriate
+
+## Command: `/agentmarkup`
+
+Analyzes your project and guides you through setting up machine-readable assets with the right `agentmarkup` adapter or manual approach.
+
+**Usage:**
+```bash
+/agentmarkup
+```
+
+Or with context:
+```bash
+/agentmarkup Set up llms.txt for my documentation site
+```
+
+The command will:
+1. Detect your framework and who owns the final HTML output
+2. Check for existing assets (`llms.txt`, `llms-full.txt`, JSON-LD, `robots.txt`, `_headers`, markdown mirrors)
+3. Recommend the right setup approach
+4. Guide implementation step by step
+5. Validate the result and call out compatibility caveats
+
+## Skill: `agentmarkup`
+
+Automatically activates when you're working on site metadata, SEO, structured data, agent-readable assets, or AI crawler configuration. Provides contextual guidance on:
+
+- llms.txt format and best practices
+- llms-full.txt and markdown mirror tradeoffs
+- JSON-LD schema.org types and validation
+- AI crawler directives and headers (`GPTBot`, `ClaudeBot`, `PerplexityBot`, `Google-Extended`, `CCBot`)
+- `@agentmarkup/vite`, `@agentmarkup/astro`, and `@agentmarkup/core` compatibility
+- Common mistakes to avoid
+
+## When to Use
+
+- Setting up a new website and want it to be AI-discoverable
+- Adding structured data to an existing site
+- Configuring robots.txt for AI crawlers
+- Creating or editing an `llms.txt` or `llms-full.txt` manifest
+- Generating markdown mirrors for agent-friendly fetches
+- Making a documentation site agent-friendly
+- Choosing between the Vite adapter, Astro adapter, and core helpers for a meta-framework or custom build
+
+## Learn More
+
+- [llms.txt specification](https://llmstxt.org)
+- [schema.org](https://schema.org)
+- [agentmarkup repository](https://github.com/agentmarkup/agentmarkup)
+- [@agentmarkup/vite](https://github.com/agentmarkup/agentmarkup/tree/main/packages/vite)
+- [@agentmarkup/astro](https://github.com/agentmarkup/agentmarkup/tree/main/packages/astro)
+- [@agentmarkup/core](https://github.com/agentmarkup/agentmarkup/tree/main/packages/core)
+
+## Compatibility Notes
+
+- Use `@agentmarkup/vite` when plain Vite owns the final HTML output.
+- Use `@agentmarkup/astro` for Astro sites.
+- Use `@agentmarkup/core` in custom prerender or post-build pipelines, and for frameworks that do an additional final render step after Vite.
+- Current schema presets are `webSite`, `organization`, `article`, `faqPage`, `product`, and `offer`.
+
+## Author
+
+Sebastian Cochinescu ([@cochinescu](https://github.com/cochinescu))

plugins/agentmarkup/commands/agentmarkup.md

@@ -0,0 +1,169 @@
+---
+description: Analyze a web project and set up machine-readable assets for LLMs and AI agents
+argument-hint: Optional framework or setup question
+---
+
+# Agent Markup Setup
+
+You are helping a developer make their website machine-readable for LLMs and AI agents. Analyze the project and guide them through adding the right assets.
+
+## Core Principles
+
+- **Detect before suggesting**: Read the project's config files and dependencies before recommending anything
+- **Minimal, correct setup**: Only suggest what the project actually needs
+- **Compatibility-first**: Match the current `agentmarkup` package surface from `github.com/agentmarkup/agentmarkup`
+- **Standards-first**: Prioritize the `llms.txt` specification and schema.org JSON-LD
+- **Non-destructive**: Never overwrite existing metadata without asking
+- **Do not install or build without approval**: Ask before running package-manager installs or build commands
+
+---
+
+## Phase 1: Project Detection
+
+**Goal**: Understand the project's framework, who owns the final HTML output, and which machine-readable assets already exist
+
+**Actions**:
+1. Check for framework config files:
+   - `vite.config.ts` / `vite.config.js` → Vite project
+   - `astro.config.mjs` / `astro.config.ts` → Astro project
+   - `next.config.ts` / `next.config.js` → Next.js project
+   - `nuxt.config.ts` → Nuxt project
+   - `svelte.config.js` / `svelte.config.ts` → SvelteKit project
+   - `remix.config.js` / `remix.config.ts` → Remix project
+   - Static HTML → Plain site
+2. Check for existing metadata:
+   - `public/llms.txt` or `llms.txt` → Already has llms.txt
+   - `public/llms-full.txt` or `llms-full.txt` → Already has llms-full.txt
+   - JSON-LD `<script type="application/ld+json">` in HTML → Already has structured data
+   - `robots.txt` → Check for AI crawler directives
+   - `_headers` → Check for `Content-Signal` or markdown canonical `Link` headers
+   - Existing generated `.md` pages → Check whether the site already ships markdown mirrors
+   - `<link rel="alternate" type="text/plain" href="/llms.txt">` in page head or layout → Check llms discovery
+3. Check for existing packages:
+   - `@agentmarkup/vite`, `@agentmarkup/astro`, `@agentmarkup/core` in `package.json`
+4. Determine whether Vite or Astro owns the final HTML files, or whether another framework performs a final render after Vite
+5. Summarize findings, compatibility constraints, and what's missing
+
+---
+
+## Phase 2: Recommend Setup
+
+**Goal**: Suggest the right approach based on what was found
+
+Based on the detected framework, recommend one of:
+
+### For plain Vite projects
+- Install `@agentmarkup/vite` for automated build-time generation
+- Configure `agentmarkup()` in `vite.config.ts`
+- Use this only when Vite owns the final HTML output
+
+### For Astro projects
+- Install `@agentmarkup/astro` for automated build-time generation
+- Configure `agentmarkup()` in `astro.config.mjs` or `astro.config.ts`
+
+### For meta-frameworks or custom render pipelines
+- Use `@agentmarkup/core` in the final prerender or post-build step
+- This is usually the right fit for Next.js, Nuxt, SvelteKit, Remix, or any pipeline where Vite does not own the deployed HTML
+- Do not assume the Vite adapter will survive a later framework render pass
+
+### For any project (manual approach)
+Guide the developer to create:
+1. `llms.txt` — a manifest of site content for LLMs (see spec below)
+2. Optional `llms-full.txt` — richer inline context for agents that can consume more than the compact manifest
+3. JSON-LD structured data in page `<head>`
+4. Optional markdown mirrors if the raw HTML is a poor agent fetch target
+5. AI crawler directives in `robots.txt`
+6. Optional `_headers` entries when the host supports `Content-Signal` or markdown canonical `Link` headers
+
+**Present the recommendation and ask the user which approach they prefer.**
+
+---
+
+## Phase 3: Implementation
+
+**Goal**: Set up the chosen approach
+
+**DO NOT START WITHOUT USER APPROVAL**
+
+Before any install, build, or dependency change, ask for approval.
+
+### If using agentmarkup packages:
+1. Install the appropriate package
+2. Add `agentmarkup()` to the framework config with the current option names:
+   - Required basics: `site`, `name`, `description`
+   - Content manifests: `llmsTxt`, optional `llmsFullTxt`
+   - Optional cleaner fetch paths: `markdownPages`
+   - Optional agent-facing headers: `contentSignalHeaders`
+   - Schemas: `globalSchemas` and page-specific `pages[].schemas`
+   - AI crawlers: `aiCrawlers`
+3. Use the current schema presets:
+   - `webSite` — general site identity
+   - `organization` — company or organization identity
+   - `article` — content pages
+   - `faqPage` — FAQ pages
+   - `product` — ecommerce entities
+   - `offer` — commerce offers
+4. Explain that existing curated `llms.txt`, matching crawler rules, and existing JSON-LD are preserved by default unless the user explicitly opts into replacement
+5. Run a build to verify output only after approval
+6. Check generated `llms.txt`, optional `llms-full.txt`, JSON-LD injection, markdown mirrors, `robots.txt`, and `_headers` patches
+
+### If setting up manually:
+1. Create `public/llms.txt` following the specification:
+   ```
+   # [Site Name]
+
+   > [One-line site description]
+
+   [Longer description of what the site offers and who it's for]
+
+   ## Docs
+
+   - [Page Title](https://example.com/page): Short description
+
+   ## Optional: API Reference, Blog, etc.
+
+   - [Title](https://example.com/path): Description
+   ```
+2. Optionally create `public/llms-full.txt` if the user wants richer inlined context
+3. Add JSON-LD to the site's `<head>` using the appropriate schema.org type
+4. Add `<link rel="alternate" type="text/plain" href="/llms.txt">` to `<head>` for discovery
+5. Optionally create markdown mirrors when the HTML output is thin or noisy for agent fetches
+6. Optionally add AI crawler directives to `robots.txt`
+7. If markdown mirrors are added and the host supports it, add `_headers` entries for canonical `Link` headers and optionally `Content-Signal`
+
+---
+
+## Phase 4: Validation
+
+**Goal**: Verify everything works
+
+**Actions**:
+1. Check `llms.txt` is accessible and well-formed
+2. Check `llms-full.txt` if present
+3. Verify JSON-LD validates with correct `@context`, `@type`, and required fields
+4. Confirm the homepage exposes an `llms.txt` discovery link, unless the adapter handles this automatically
+5. Confirm `robots.txt` has the desired AI crawler directives if used
+6. Confirm `_headers` entries if markdown mirrors or `Content-Signal` are part of the setup
+7. Summarize what was preserved vs generated and any remaining compatibility caveats
+
+---
+
+## llms.txt Specification Reference
+
+The `llms.txt` file is a standardized way to provide information about a website to LLMs. It lives at the site root (`/llms.txt`) and uses markdown formatting:
+
+- **Title**: `# Site Name` (H1 heading)
+- **Summary**: `> Blockquote` with a brief description
+- **Body**: Optional longer description paragraph
+- **Sections**: `## Section Name` with lists of links
+- **Links**: `- [Title](URL): Optional description`
+
+Optional companion: `llms-full.txt` with inlined page content for deeper context.
+
+## Compatibility Notes
+
+- `@agentmarkup/vite` and `@agentmarkup/astro` can inject the homepage `llms.txt` discovery link automatically.
+- `@agentmarkup/vite` is best when Vite owns the final HTML files.
+- When another framework performs the final render, prefer `@agentmarkup/core` in that final step.
+
+---