docs: add llm-seo-readiness skill and sync CLAUDE.md

- Add project Cursor skill for LLM exports and SEO checklists\n- Align CLAUDE.md with agent guidelines (zh localization; no es maintenance)\n- Link skill from Resources

Made-with: Cursor

Author: gregnazario

.cursor/skills/llm-seo-readiness/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: llm-seo-readiness
+description: >-
+  Validates Aptos docs changes for LLM consumption (llms.txt, curated feeds, Markdown exports, HTML→Markdown)
+  and for SEO (metadata, sitemap, robots, structured data). Use when adding or restructuring docs, editing
+  llms routes or curation, changing Head/meta/OG, updating robots.txt or sitemap behavior, or when the user
+  mentions LLMs.txt, AI tool ingestion, crawlers, discoverability, or SEO.
+---
+
+# LLM and SEO readiness (Aptos docs)
+
+## LLM / machine-readable
+
+- **Frontmatter**: Every new or renamed doc needs accurate `title` and `description` in English; they surface in `/llms.txt` and `.md` exports. Mirror updates in `src/content/docs/zh/` per agent guidelines (Spanish `es/` is out of scope for agent-maintained docs).
+- **Curated lists**: If a page should appear in the LLM index or early in full corpus, update `src/lib/llms-curated-ids.ts` (`LLMS_INDEX_SECTIONS`, `LLMS_SMALL_DOC_IDS`, `FULL_PRIORITY_DOC_IDS` as appropriate). Build fails if an id is missing from English non-draft docs.
+- **Index copy**: User-facing explanations live in `src/content/docs/llms-txt.mdx`, `src/content/docs/build/ai.mdx`, and the Chinese `zh/` counterparts—keep URLs and feed names aligned with `src/pages/llms-index.ts`.
+- **HTML → Markdown**: Shared logic is `src/lib/llms-html-sanitize.ts`. When minifying for `llms-small.txt`, collapse **spaces/tabs only**—never all `\s` (newlines must survive for fenced code and Markdown structure).
+- **Route wiring**: Custom handlers are swapped in via `src/integrations/llms-txt-index.ts`; endpoint implementations live under `src/pages/llms-index.ts`, `src/endpoints/llms-small.txt.ts`, `src/endpoints/llms-full.txt.ts`.
+- **Robots**: `public/robots.txt` should stay consistent with sitemap URL and, when feeds change, the commented LLMs.txt pointers at the bottom.
+
+## SEO
+
+- **Per-page metadata**: Starlight frontmatter `title` / `description` feed OG, Twitter, and schema in `src/starlight-overrides/Head.astro`—avoid empty or placeholder descriptions on public pages.
+- **Sitemap**: Produced by `@astrojs/sitemap` in `astro.config.mjs`; ensure new top-level routes or major URL changes still make sense for indexing.
+- **Hreflang / alternates**: Head override builds language alternates from `SUPPORTED_LANGUAGES`—new locales need config updates, not only content folders.
+- **Draft / hidden content**: Do not rely on curated LLM ids or public sitemap for content that must stay off production; follow existing draft filtering in the `.md` pipeline and curation tests.
+
+## Verification
+
+After substantive changes:
+
+```bash
+pnpm test tests/llms-curated-ids.test.ts tests/llms-html-sanitize.test.ts
+pnpm lint && pnpm check
+```
+
+For full coverage: `pnpm test` and a production `pnpm build` when touching routes or integrations.
+
+## File map
+
+| Area | Primary locations |
+|------|-------------------|
+| Curation | `src/lib/llms-curated-ids.ts`, `src/lib/llms.ts` |
+| llms.txt body | `src/pages/llms-index.ts` |
+| Feed endpoints | `src/endpoints/llms-small.txt.ts`, `src/endpoints/llms-full.txt.ts` |
+| Plugin override | `src/integrations/llms-txt-index.ts` |
+| Markdown export / sanitize | `src/lib/llms-html-sanitize.ts`, `src/pages/[...slug].md.ts` |
+| User docs | `src/content/docs/llms-txt.mdx`, `build/ai.mdx`, `zh/` |
+| SEO head | `src/starlight-overrides/Head.astro` |
+| Crawlers / sitemap hint | `public/robots.txt` |

CLAUDE.md

@@ -4,7 +4,7 @@ This document provides essential guidelines for AI agents working on the Aptos D
 
 ## Project Overview
 
-This repository contains the official Aptos Developer Documentation, built using [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). The documentation is available in English and Chinese (zh).
+This repository contains the official Aptos Developer Documentation, built using [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). Published languages include English and Chinese (zh). Agent workflows here do **not** include creating or updating Spanish (`es`) documentation.
 
 ## Machine-readable documentation for agents
 
@@ -50,6 +50,8 @@ src/
 └── assets/             # Site assets
 ```
 
+A legacy `docs/es/` tree or URLs may still exist for redirects; do not add or maintain Spanish doc content under these agent guidelines.
+
 ## Critical Guidelines
 
 ### 1. Linting and Formatting
@@ -65,7 +67,7 @@ Run these commands after making changes to ensure code quality.
 
 ### 2. Translation Requirements
 
-**All documentation changes must be translated and verified in the Chinese version.**
+**Documentation changes that need localization must include the Chinese (`zh`) version.** Do not add or update Spanish (`es`) translations as part of agent work.
 
 - **English docs:** `src/content/docs/`
 - **Chinese docs:** `src/content/docs/zh/`
@@ -74,11 +76,7 @@ When modifying documentation:
 
 1. Make the change in the English version first
 2. Create or update the corresponding Chinese translation in `zh/`
-3. Ensure all internal links use the correct language prefix (e.g., `/zh/network/` for Chinese)
-
-**No Spanish documentation tree:** Do not add pages under `src/content/docs/es/`. The site does not ship Spanish MDX/Markdown docs.
-
-**Translated PDFs and external assets:** You may still link official non-English files when appropriate—for example the Spanish white paper PDF (`aptos-whitepaper_es.pdf`) from the [Aptos white paper](/network/blockchain/aptos-white-paper) page alongside other language PDFs.
+3. Ensure Chinese internal links use the `/zh/...` prefix (see Internal Links below)
 
 ### 3. Commit Message Requirements
 
@@ -206,6 +204,7 @@ module example::hello {
 
 ## Resources
 
+- [LLM and SEO readiness (Cursor skill)](.cursor/skills/llm-seo-readiness/SKILL.md) — checklists for `llms.txt`, curated feeds, `.md` exports, and metadata/crawlers
 - [Astro Documentation](https://docs.astro.build/)
 - [Starlight Documentation](https://starlight.astro.build/)
 - [MDX Documentation](https://mdxjs.com/)