diff --git a/SKILLS.md b/.agents/skills/vortex-integration/SKILL.md
similarity index 96%
rename from SKILLS.md
rename to .agents/skills/vortex-integration/SKILL.md
index c4aac6cae..17df141d8 100644
--- a/SKILLS.md
+++ b/.agents/skills/vortex-integration/SKILL.md
@@ -1,8 +1,13 @@
-# Vortex SKILLS.md
+---
+name: vortex-integration
+description: Use when integrating Vortex or @vortexfi/sdk, including quotes, BRL PIX onramps/offramps, ramp register/update/start/status flows, webhook verification, ephemeral key custody, supported corridors, sandbox/production auth, and recovery from ramp errors.
+---
+
+# Vortex Integration Skill
 
-A machine-loadable capability catalog for AI coding agents integrating Vortex into third-party applications. Each skill below is a self-contained unit with YAML frontmatter (`name`, `description`, `triggers`) plus a minimal recipe in both SDK and REST form.
+A machine-loadable capability catalog for AI coding agents integrating Vortex into third-party applications. Start by reading **Global Context**, then match the user's task to the closest recipe below before implementing. Each recipe includes trigger phrases plus a minimal SDK and/or REST form.
 
-> **Companion document**: [`docs/api/pages/12-ai-agent-integration.md`](https://api-docs.vortexfinance.co/ai-agent-integration) covers the raw-API contract, mandatory client responsibilities, and language-agnostic guidance. SKILLS.md focuses on **task-shaped recipes** an agent can match against user intent.
+> **Companion document**: [AI Agent Integration](https://api-docs.vortexfinance.co/ai-agent-integration) covers the raw-API contract, mandatory client responsibilities, and language-agnostic guidance. This skill focuses on **task-shaped recipes** an agent can match against user intent.
 
 ---
 
diff --git a/README.md b/README.md
index 69a730693..303ba342e 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,20 @@
 
 Vortex is a gateway for cross-border payments. It is built on top of the Pendulum blockchain.
 
+## AI Agent Skill
+
+This repository includes a repo-scoped Codex/Agent Skills skill for Vortex integrations:
+
+- [`.agents/skills/vortex-integration/SKILL.md`](.agents/skills/vortex-integration/SKILL.md)
+
+When this repository is open in Codex, the skill is discovered automatically from `.agents/skills`. If you are integrating Vortex from another repository, install the public skill directory URL instead:
+
+```text
+https://github.com/pendulum-chain/vortex/tree/main/.agents/skills/vortex-integration
+```
+
+Use the skill for task-shaped guidance around quotes, BRL PIX onramps/offramps, ramp polling, webhook verification, supported corridors, auth setup, and error recovery. The hosted AI-agent integration guide is available at <https://api-docs.vortexfinance.co/ai-agent-integration>.
+
 ## Repository Structure
 
 This is a **Bun monorepo** containing multiple sub-projects organized into apps, packages, and contracts:
diff --git a/docs/api/pages/12-ai-agent-integration.md b/docs/api/pages/12-ai-agent-integration.md
index 3228d07d9..c7c583d31 100644
--- a/docs/api/pages/12-ai-agent-integration.md
+++ b/docs/api/pages/12-ai-agent-integration.md
@@ -7,6 +7,7 @@ This page is written so that an AI coding agent (or a human engineer using one)
 When you point an AI coding agent at Vortex:
 
 - **Anchor the agent on this section first.** Pages 1–11 describe the protocol and contracts; this page describes what a correct client must do.
+- **Load the Vortex integration skill if available.** This repository ships a Codex/Agent Skills skill at [`vortex-integration`](https://github.com/pendulum-chain/vortex/tree/main/.agents/skills/vortex-integration). If this repository is open in Codex, the skill is discovered automatically from `$REPO_ROOT/.agents/skills/vortex-integration/SKILL.md`; if you are integrating Vortex from another repository, install the public skill directory URL (`https://github.com/pendulum-chain/vortex/tree/main/.agents/skills/vortex-integration`) first, then match the user's task to the relevant recipe before implementing.
 - **Treat the OpenAPI file as the source of truth for shapes**, and these Markdown pages as the source of truth for *behavior, ordering, custody, signing, and timing*. Both are required; neither is sufficient alone.
 - **Pin versions.** Record the commit hash of these docs and the version of `@vortexfi/sdk` you are mirroring. The SDK's behavior is the reference implementation; if your integration disagrees with it, the SDK wins.
 - **Never let the agent invent endpoints, fields, status values, or fee categories.** If something is not in the OpenAPI file or these pages, the agent should stop and ask.