From 7b91dd71418ecf3a08813bc6410aed64c4ed25ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Sat, 7 Nov 2026 17:39:46 +0100
Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20Add=20AI=20development=20gui?=
 =?UTF-8?q?dance=20and=20coding=20agent=20notices?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/ai-development.md   | 29 ++++++++++++++++++++++++++
 docs/index.md            |  2 ++
 includes/agent-banner.md | 11 ++++++++++
 mkdocs.yml               |  6 ++++++
 scripts/agent_banner.py  | 45 ++++++++++++++++++++++++++++++++++++++++
 scripts/docs.py          |  1 +
 6 files changed, 94 insertions(+)
 create mode 100644 docs/ai-development.md
 create mode 100644 includes/agent-banner.md
 create mode 100644 scripts/agent_banner.py

diff --git a/docs/ai-development.md b/docs/ai-development.md
new file mode 100644
index 0000000000..6f2d114aad
--- /dev/null
+++ b/docs/ai-development.md
@@ -0,0 +1,29 @@
+# Develop with AI
+
+SQLModel includes an official **agent skill**, bundled with the Python package, with guidance for the version installed in your project.
+
+## Install the skill
+
+After [installing SQLModel](install.md), run [Library Skills](https://library-skills.io/use/) from your project directory:
+
+```bash
+uvx library-skills
+```
+
+Select the SQLModel skill and `.agents/skills` for Codex and most agents, or `.claude/skills` for Claude Code. You can select both.
+
+Your agent can then use the skill automatically when working on SQLModel code.
+
+### Install without prompts
+
+For agents and scripts, select the SQLModel skill without interactive prompts:
+
+```bash
+uvx library-skills install --skill sqlmodel --yes
+```
+
+For Claude Code, add `--claude` to also install it in `.claude/skills`:
+
+```bash
+uvx library-skills install --skill sqlmodel --yes --claude
+```
diff --git a/docs/index.md b/docs/index.md
index 3114f5bc2f..eb869b0c7a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -41,6 +41,8 @@ SQLModel is a library for interacting with <abbr title='Also called "Relational
 
 **SQLModel** is based on Python type annotations, and powered by [Pydantic](https://pydantic-docs.helpmanual.io/) and [SQLAlchemy](https://sqlalchemy.org/).
 
+<!-- agent-banner -->
+
 The key features are:
 
 * **Intuitive to write**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.
diff --git a/includes/agent-banner.md b/includes/agent-banner.md
new file mode 100644
index 0000000000..344c665e18
--- /dev/null
+++ b/includes/agent-banner.md
@@ -0,0 +1,11 @@
+/// details | AI coding agents
+
+Use the official SQLModel skill for your installed version. Install it from your project directory:
+
+```bash
+uvx library-skills
+```
+
+See [Develop with AI](https://sqlmodel.tiangolo.com/ai-development/).
+
+///
diff --git a/mkdocs.yml b/mkdocs.yml
index f693107a89..9410b4c056 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -120,6 +120,7 @@ nav:
       - advanced/decimal.md
       - advanced/uuid.md
   - "":
+    - ai-development.md
     - resources/index.md
     - help.md
     - contributing.md
@@ -129,7 +130,12 @@ nav:
     - management.md
   - release-notes.md
 
+watch:
+  - scripts/agent_banner.py
+  - includes/agent-banner.md
+
 markdown_extensions:
+  scripts.agent_banner:
   # Material for MkDocs
   material.extensions.preview:
     targets:
diff --git a/scripts/agent_banner.py b/scripts/agent_banner.py
new file mode 100644
index 0000000000..f92991f43a
--- /dev/null
+++ b/scripts/agent_banner.py
@@ -0,0 +1,45 @@
+from pathlib import Path
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+from mkdocstrings import MkdocstringsInnerExtension
+from zensical.extensions.context import ContextPreprocessor
+
+
+class AgentBannerPreprocessor(Preprocessor):
+    def run(self, lines: list[str]) -> list[str]:
+        # Docstrings render their own Markdown inside an API reference page.
+        if any(
+            isinstance(extension, MkdocstringsInnerExtension)
+            for extension in self.md.registeredExtensions
+        ):
+            return lines
+
+        context = ContextPreprocessor.from_markdown(self.md)
+        if context is None or context.page.path == "ai-development.md":
+            return lines
+
+        banner_path = (
+            Path(__file__).resolve().parent.parent / "includes/agent-banner.md"
+        )
+        banner = banner_path.read_text(encoding="utf-8").strip()
+        content = "\n".join(lines)
+        marker = "<!-- agent-banner -->"
+        if marker in content:
+            return content.replace(marker, banner).splitlines()
+
+        header, _, body = content.lstrip().partition("\n")
+        if header == "#" or header.startswith("# "):
+            return f"{header}\n\n{banner}\n\n{body.lstrip()}".splitlines()
+        return f"{banner}\n\n{content}".splitlines()
+
+
+class AgentBannerExtension(Extension):
+    def extendMarkdown(self, md: Markdown) -> None:
+        # Insert the notice before macros and fenced code blocks are processed.
+        md.preprocessors.register(AgentBannerPreprocessor(md), "agent_banner", 36)
+
+
+def makeExtension() -> AgentBannerExtension:
+    return AgentBannerExtension()
diff --git a/scripts/docs.py b/scripts/docs.py
index ec98067307..07e2745f57 100644
--- a/scripts/docs.py
+++ b/scripts/docs.py
@@ -65,6 +65,7 @@ def generate_readme_content() -> str:
         new_content,
         flags=re.DOTALL,
     )
+    new_content = new_content.replace("<!-- agent-banner -->\n\n", "")
     return new_content
 
 

From 499fea7d2d859ab758c2bc55bd3185a8a8aa0f65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Sat, 7 Nov 2026 17:52:30 +0100
Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=90=9B=20Fix=20AI=20coding=20agent=20?=
 =?UTF-8?q?notice=20links=20in=20previews?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 includes/agent-banner.md | 2 +-
 scripts/agent_banner.py  | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/includes/agent-banner.md b/includes/agent-banner.md
index 344c665e18..35171f9b1c 100644
--- a/includes/agent-banner.md
+++ b/includes/agent-banner.md
@@ -6,6 +6,6 @@ Use the official SQLModel skill for your installed version. Install it from your
 uvx library-skills
 ```
 
-See [Develop with AI](https://sqlmodel.tiangolo.com/ai-development/).
+See [Develop with AI](ai-development.md).
 
 ///
diff --git a/scripts/agent_banner.py b/scripts/agent_banner.py
index f92991f43a..78838a8d2e 100644
--- a/scripts/agent_banner.py
+++ b/scripts/agent_banner.py
@@ -1,4 +1,5 @@
 from pathlib import Path
+from posixpath import relpath
 
 from markdown import Markdown
 from markdown.extensions import Extension
@@ -24,6 +25,10 @@ def run(self, lines: list[str]) -> list[str]:
             Path(__file__).resolve().parent.parent / "includes/agent-banner.md"
         )
         banner = banner_path.read_text(encoding="utf-8").strip()
+        guide_path = relpath(
+            "ai-development.md", Path(context.page.path).parent.as_posix()
+        )
+        banner = banner.replace("(ai-development.md)", f"({guide_path})")
         content = "\n".join(lines)
         marker = "<!-- agent-banner -->"
         if marker in content:

From 2c87ccde6484529cbb1d8cae3852b9042ab406b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= <tiangolo@gmail.com>
Date: Sat, 7 Nov 2026 17:54:32 +0100
Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20Move=20AI=20development=20gu?=
 =?UTF-8?q?idance=20into=20the=20main=20tutorial?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 mkdocs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 9410b4c056..9eba8358b4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -66,6 +66,7 @@ nav:
     - install.md
     - "":
       - tutorial/index.md
+      - ai-development.md
       - tutorial/create-db-and-table-with-db-browser.md
       - tutorial/create-db-and-table.md
       - tutorial/insert.md
@@ -120,7 +121,6 @@ nav:
       - advanced/decimal.md
       - advanced/uuid.md
   - "":
-    - ai-development.md
     - resources/index.md
     - help.md
     - contributing.md