diff --git a/README.md b/README.md
index 865c9d3..a6a2c46 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,9 @@
-# openapi
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NombaOSS/openapi/main/.github/assets/banner-dark.svg">
+  <img alt="Nomba OpenAPI Spec" src="https://raw.githubusercontent.com/NombaOSS/openapi/main/.github/assets/banner-light.svg" width="100%">
+</picture>
+
+# Nomba OpenAPI Spec
 
 [![CI](https://github.com/NombaOSS/openapi/actions/workflows/ci.yml/badge.svg)](https://github.com/NombaOSS/openapi/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -32,6 +37,16 @@ Render it as a single HTML page:
 npm ci && npm run docs   # writes dist/index.html
 ```
 
+## Building with an AI coding agent?
+
+Install the [Nomba agent skills](https://github.com/NombaOSS/skills) so Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and other agents write Nomba integrations the safe way: idempotency references, requery on timeouts, refunds only when final, and webhook verification.
+
+```bash
+npx skills add NombaOSS/skills
+```
+
+In Claude Code you can also use `/plugin marketplace add NombaOSS/skills` and then `/plugin install nomba@nomba`.
+
 ## Where it comes from
 
 The source of truth is the API reference at [developer.nomba.com](https://developer.nomba.com/nomba-api-reference/introduction). Each reference page embeds the OpenAPI definition for its endpoint; `npm run sync` fetches every page, merges them, and splits the result into `openapi/` (one file per path and per schema).