docs: add maps-usage AI skill

AGENTS.md

@@ -24,10 +24,25 @@ ios/                 # iOS native (Objective-C)
 android/             # Android native (Kotlin)
 plugin/              # Expo config plugin
 example/bare/        # Bare React Native example app
+example/expo/        # Expo example app
+example/shared/      # Screens and components shared by both example apps
+skills/maps-usage/   # Consumer-facing AI skill (npx skills add lugg/maps)
 docs/                # Documentation site (Next.js + Fumadocs), deployed to maps.lodev09.com
 docs/content/docs/   # MDX documentation pages
 ```
 
+### Updating the AI skill
+
+`skills/maps-usage/` is the consumer-facing skill installed via `npx skills add lugg/maps`. Whenever `docs/content/docs/` changes (new prop, event, method, platform limitation, or pattern), update the skill to match in the same PR:
+
+- `SKILL.md` - quick start, recipes, "Rules That Save Debugging Time", platform table
+- `references/configuration.md` - setup snippets and props (mirror `installation.mdx`, `components/*.mdx`, `types.mdx`)
+- `references/api.md` - ref methods, events, payload types
+- `references/advanced-patterns.md` - patterns from `example/shared/`
+- `references/troubleshooting.md` - symptom → cause → fix entries
+
+The skill summarizes the docs and the source, it does not copy them. Keep entries terse and code-first. When docs and `src/` disagree, follow `src/` and fix the docs.
+
 ### Creating a Pull Request
 
 When creating a PR, use the template from `.github/PULL_REQUEST_TEMPLATE.md`:

README.md

@@ -40,6 +40,16 @@ import { MapView, Marker } from '@lugg/maps';
 
 Google Maps needs an API key on every platform. See [Installation](https://maps.lodev09.com/installation) for Expo, iOS, Android, and web setup.
 
+## AI Skills
+
+Skills give your AI coding agent working knowledge of `@lugg/maps` - setup, camera control, markers and callouts, static maps, advanced patterns, and platform limitations - so it generates correct code without you explaining the library each time.
+
+```sh
+npx skills add lugg/maps
+```
+
+This installs the **Maps Usage** skill into your project. The source lives in [`skills/maps-usage`](skills/maps-usage).
+
 ## Contributing
 
 - [Development workflow](CONTRIBUTING.md#development-workflow)

docs/app/(home)/page.tsx

@@ -2,6 +2,8 @@ import type { CSSProperties } from 'react';
 import Link from 'next/link';
 import {
   ArrowRight,
+  BookOpen,
+  Bot,
   Camera,
   Globe,
   Image as ImageIcon,
@@ -10,6 +12,8 @@ import {
   MapPin,
   Rows3,
   Route,
+  ShieldAlert,
+  Sparkles,
   Zap,
 } from 'lucide-react';
 import { CodeSample } from '@/components/code-sample';
@@ -184,6 +188,30 @@ const PLATFORMS = [
   { name: 'Web', providers: 'Google Maps' },
 ];
 
+const SKILL_COMMAND = 'npx skills add lugg/maps';
+const SKILL_URL = `${GITHUB_URL}/tree/main/skills/maps-usage`;
+
+const SKILL_TOPICS = [
+  {
+    icon: BookOpen,
+    title: 'Setup and API',
+    description:
+      'Expo plugin, bare iOS and Android, web provider. Every prop, event, and ref method with platform support.',
+  },
+  {
+    icon: Sparkles,
+    title: 'Recipes and patterns',
+    description:
+      'Camera control, custom markers and callouts, routes, GeoJSON, static lists, bottom sheet insets, Reanimated markers.',
+  },
+  {
+    icon: ShieldAlert,
+    title: 'Limitations and fixes',
+    description:
+      'What differs between Apple, Google, Android, and web, plus a symptom-to-fix troubleshooting guide.',
+  },
+];
+
 export default function HomePage() {
   return (
     <main className="flex flex-1 flex-col">
@@ -381,7 +409,73 @@ export default function HomePage() {
         </div>
       </section>
 
-      <section className="border-t border-fd-border">
+      <section className="border-y border-fd-border bg-fd-card/40">
+        <div className="mx-auto grid w-full max-w-6xl gap-12 px-6 py-20 md:py-28 lg:grid-cols-[1fr_1.1fr] lg:items-center">
+          <div className="max-w-2xl">
+            <p className="text-sm font-semibold uppercase tracking-wider text-fd-primary">
+              Built for agents
+            </p>
+            <h2 className="mt-3 text-3xl font-bold tracking-tight text-fd-foreground md:text-4xl">
+              Teach your coding agent the library.
+            </h2>
+            <p className="mt-4 text-fd-muted-foreground">
+              One command installs the <strong>Maps Usage</strong> skill into
+              your project. Claude Code, Cursor, Codex, and other agents then
+              pick the right patterns, respect platform limits, and generate
+              correct{' '}
+              <code className="font-mono text-fd-foreground">MapView</code> code
+              without you explaining the API every time.
+            </p>
+            <div className="mt-8">
+              <InstallCommand command={SKILL_COMMAND} />
+            </div>
+            <div className="mt-6 flex flex-wrap items-center gap-5 text-sm">
+              <Link
+                href={SKILL_URL}
+                className="inline-flex items-center gap-1.5 font-medium text-fd-primary hover:underline"
+              >
+                Read the skill source
+                <ArrowRight className="size-4" />
+              </Link>
+              <Link
+                href="/usage#ai-skills"
+                className="inline-flex items-center gap-1.5 font-medium text-fd-muted-foreground hover:text-fd-foreground"
+              >
+                Usage guide
+              </Link>
+            </div>
+          </div>
+          <div className="grid gap-3">
+            {SKILL_TOPICS.map((topic) => (
+              <div
+                key={topic.title}
+                className="flex gap-4 rounded-2xl border border-fd-border bg-fd-background p-5 transition-colors hover:border-fd-primary/40"
+              >
+                <div className="inline-flex size-10 shrink-0 items-center justify-center rounded-xl bg-fd-primary/10 text-fd-primary">
+                  <topic.icon className="size-5" />
+                </div>
+                <div>
+                  <h3 className="font-semibold text-fd-foreground">
+                    {topic.title}
+                  </h3>
+                  <p className="mt-1.5 text-sm leading-relaxed text-fd-muted-foreground">
+                    {topic.description}
+                  </p>
+                </div>
+              </div>
+            ))}
+            <div className="flex items-center gap-3 rounded-2xl border border-dashed border-fd-border px-5 py-4 text-sm text-fd-muted-foreground">
+              <Bot className="size-4 shrink-0 text-fd-primary" />
+              <span>
+                Ships as a standard <code className="font-mono">SKILL.md</code>{' '}
+                with reference files, so any agent that reads skills can use it.
+              </span>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <section>
         <div className="mx-auto flex w-full max-w-6xl flex-col items-center gap-6 px-6 py-20 text-center md:py-24">
           <div className="inline-flex size-12 items-center justify-center rounded-2xl bg-fd-primary/10 text-fd-primary">
             <LayoutGrid className="size-6" />

docs/content/docs/usage.mdx

@@ -110,6 +110,16 @@ On iOS, both screens include a button to switch between Apple Maps and Google Ma
 
 Read more in [Static Maps](./components/map-view.mdx#static-maps).
 
+## AI skills
+
+Give your AI coding agent working knowledge of `@lugg/maps` (setup, camera control, markers, static maps, advanced patterns, and platform limitations):
+
+```sh
+npx skills add lugg/maps
+```
+
+This installs the **Maps Usage** skill into your project.
+
 ## Next steps
 
 <Cards>

docs/lib/source.ts

@@ -1,11 +1,32 @@
-import { loader } from 'fumadocs-core/source';
+import { createElement } from 'react';
+import { loader, type LoaderPlugin } from 'fumadocs-core/source';
 import { defineDocs } from 'fumadocs-mdx/macro';
 
 const docs = defineDocs({
   dir: 'content/docs',
 });
 
+// Render component pages in the page tree as `<Name />` code
+const componentNamesPlugin: LoaderPlugin = {
+  name: 'lugg:component-names',
+  transformPageTree: {
+    file(node, filePath) {
+      if (!filePath?.startsWith('components/')) return node;
+      const file = this.storage.read(filePath);
+      if (file?.format !== 'page') return node;
+
+      node.name = createElement(
+        'code',
+        { className: 'font-mono text-[0.8125rem]' },
+        `<${file.data.title} />`
+      );
+      return node;
+    },
+  },
+};
+
 export const source = loader({
   baseUrl: '/',
   source: docs.toFumadocsSource(),
+  plugins: [componentNamesPlugin],
 });