Agent Skills. Every theme ships with the context files AI coding tools read

What are agent skills?

Every Lexington theme includes a set of plain Markdown files written for AI coding assistants: Cursor, Claude Code, Codex, Copilot, and any other tool that reads project context. They describe how the theme is built, so when you ask your AI to add a page or change a component, the result follows the theme’s patterns instead of fighting them.

You don’t install anything. The files live in the repository you fork or download, and the tools pick them up automatically.

This applies to the entire catalog. Every theme and every port — plain Astro, Sanity, and EmDash — ships these files. If a theme page doesn’t mention them, they are still there: this is the default for every Lexington theme, not an add-on for some of them.

What ships in every theme

AGENTS.md

The project brief, in the file most coding agents read first. Each theme’s AGENTS.md covers:

• Tech stack: exact Astro, Tailwind, and integration versions, and where each is configured.
• Folder map: what lives where, including theme-specific details agents would otherwise guess wrong.
• Content collections: every collection with its required frontmatter, image field conventions, and which file to copy as a starting template.
• Routing conventions: how pages, dynamic routes, and layouts connect.
• Gotchas: the things that trip tools up, called out explicitly.

The design system skill

Each theme ships a design skill at .cursor/skills/<theme>-design/SKILL.md, extracted from that theme’s actual code — not a generic checklist. It captures what makes the theme look the way it does:

• Design personality: the theme’s visual character in a few rules an agent can follow.
• Typography: the exact fonts, which Text variants real pages use, and the weight and tracking conventions.
• Color system: the theme’s tokens, how each scale is used, and what is off-limits (no stock Tailwind palettes, no invented hues).
• Layout and spacing: section anatomy and the spacing rhythm real sections follow.
• Components: the exact Button, Text, and Wrapper variants, with per-use decisions like button widths spelled out.
• Corners, borders, shadows: the real policy, taken from counting the classes in the codebase.
• Do / don’t list and a quality checklist the agent runs before finishing.

This is the file that keeps AI-generated pages on-brand. Ask your agent for a new page and it builds with the theme’s own patterns: same tokens, same spacing, same component conventions.

Cursor rules

Each theme also ships .cursor/rules/ with four scoped rules:

• Global: conventions that always apply, such as using the @/ import alias, preferring existing patterns over new abstractions, and keeping diffs minimal with no drive-by refactors or invented dependencies.
• Config: how astro.config.mjs, tsconfig.json, and the Tailwind setup fit together.
• Content: collection schemas and frontmatter rules, applied when you work in src/content/.
• Pages: routing and layout conventions, applied when you work in src/pages/.

CMS variants are covered too: Sanity and EmDash versions of a theme have their own AGENTS.md and rules adapted to that stack, including the adapter layer and admin workflow.

How each tool uses them

• Cursor reads .cursor/rules/ and .cursor/skills/ automatically. The global rule always applies, the others activate when you touch matching files, and the design skill loads when you ask for UI work. AGENTS.md is also read as project context. Nothing to configure.
• Claude Code reads AGENTS.md automatically from the project root, and supports the same skill format via its skills directory.
• Codex reads AGENTS.md automatically.
• Copilot and other tools: point them at AGENTS.md and the design skill, or copy their contents into your tool’s custom instructions. They are plain Markdown; any tool can read them.

Free stack skills

The theme files above teach your AI the design of the theme you bought. Lexington also publishes free, open-source skills that teach the stack: Astro + Tailwind conventions grounded in the official docs, usable in any project.

• astro-tailwind-best-practices: project structure, components-first workflow, fonts via Astro’s Fonts API, image handling that never crops by accident.
• astro-seo: canonical URLs, sitemaps, Open Graph, JSON-LD structured data.
• astro-content-collections: Zod schemas, image() fields, draft workflows, safe schema changes.

Install them into any project with the skills CLI:

npx skills add lexington-themes/astro-skills

They pair with the theme files: the free skills handle the stack, the theme’s design skill handles the way it looks.

Working with your AI on a theme

A real, unedited run: the Cursor CLI gets one short prompt, reads the design skill, and changes the brand color across the whole scale — then git diff shows the edit is real:

The files do the heavy lifting, so your prompts can stay short. Some examples that work well:

• “Add a new blog post about X” — the agent knows the collection folder, the required frontmatter, and which existing post to use as a template.
• “Create a careers page that matches the rest of the site” — the agent knows the layout to use, the component conventions, and the import alias.
• “Change the brand color” — the agent knows the tokens live in src/styles/colors.css (brand-light, brand-dark), not scattered through components.

Two tips for best results:

1. Keep AGENTS.md updated as you customize. If you rename a collection or restructure pages, tell your agent to update AGENTS.md in the same change. Future sessions inherit the corrected brief.
2. Lean on the rules for review. If generated code ignores a convention, ask the agent to check it against the theme rules; the constraint is already written down.

Why this matters

AI tools produce generic-looking output when they have to guess. With the brief and the rules in the repository, your agent builds on the design system you paid for: same spacing, same tokens, same component patterns. The theme stays on-brand no matter who, or what, writes the next page.