work on skill routing

Co-authored-by: Ona <no-reply@ona.com>

Author: ldoguin

AGENTS.md

@@ -10,6 +10,12 @@ A collection of Couchbase agent skills for use in agentic workflows. Each skill
 
 ## Skill Index
 
+### Entry Point
+
+| Skill | Description |
+|---|---|
+| [`couchbase`](skills/couchbase/) | Router skill — entry point for all Couchbase questions, reads `discovery.yaml` and routes to the right skill |
+
 ### Getting Started
 
 | Skill | Description |

README.md

@@ -32,11 +32,11 @@ codex
 
 Once installed, skills activate in two ways:
 
-**Implicit** — just describe what you need and Codex picks the right skill:
-> "How do I connect to Couchbase from Go?"  
-> "How do I encrypt a field before storing it?"
+**Implicit** — any mention of "Couchbase" loads the `$couchbase` router skill first. It reads `discovery.yaml` and routes to the right skill based on your question:
+> "How do I connect to Couchbase from Go?" → routes to `server-connection-go`  
+> "How do I encrypt a field before storing it?" → routes to `fle` → `fle-<lang>`
 
-**Explicit** — type `$` in the Codex composer to invoke a skill by name:
+**Explicit** — type `$` in the Codex composer to invoke a skill directly by name:
 ```
 $server-connection-python
 $fle-go

discovery.yaml

@@ -23,6 +23,18 @@
 
 skills:
 
+  # ── Router (Codex / implicit invocation entry point) ─────────────
+
+  - skill: couchbase
+    priority: primary
+    use_when: the user asks any Couchbase question and no more specific skill has been loaded yet
+    triggers:
+      - "Couchbase"
+      - "Couchbase SDK"
+      - "Couchbase question"
+      - "help with Couchbase"
+      - "Couchbase help"
+
   # ── Getting Started ───────────────────────────────────────────────
 
   - skill: getting-started

routing.yaml

@@ -121,6 +121,16 @@ routes:
 
   # ── Getting Started ───────────────────────────────────────────────
 
+  - from: couchbase
+    to: getting-started
+    condition: user is new to Couchbase or asks a general question
+    type: topic
+
+  - from: getting-started
+    to: couchbase
+    condition: user asks a general Couchbase question and needs skill routing
+    type: topic
+
   - from: getting-started
     to: local-dev-setup
     condition: user wants to run Couchbase locally with Docker

scripts/validate-skills.sh

@@ -435,6 +435,7 @@ server-querying-php|transactions-php
 server-querying-python|transactions-python
 server-querying-scala|transactions-scala
 analytics-rust|server-connection-rust
+couchbase|getting-started
 fle|fle-python
 fle|security
 fle-dotnet|server-connection-dotnet

skills/couchbase/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: couchbase
+summary: Entry point for all Couchbase questions — routes to the right skill based on topic and language
+description: Entry point for all Couchbase questions — routes to the right skill based on topic and language. Use for any question about Couchbase SDK connection, querying, search, transactions, analytics, field-level encryption, testing, mobile, caching, eventing, Kafka, XDCR, backup, security, or data modeling.
+metadata:
+  last_verified: "2026-05"
+  handoff:  # generated from routing.yaml — do not edit manually
+    - condition: "user is new to Couchbase or asks a general question"
+      skill: getting-started
+---
+
+# Couchbase — Skill Router
+
+This skill is the entry point for all Couchbase questions. Read `discovery.yaml` to find the right skill for the user's question, then load and follow that skill.
+
+## Routing instructions
+
+1. Read `discovery.yaml` from the root of this skills collection.
+2. Match the user's question against the `triggers` and `use_when` fields.
+3. Load the matching skill's `SKILL.md` and follow its instructions.
+4. If the user specifies a programming language, prefer the language-specific skill (e.g. `server-connection-go` over `server-connection-python`).
+5. If no skill matches, load `getting-started`.
+
+## Quick reference
+
+| Topic | Skill |
+|---|---|
+| New to Couchbase | `getting-started` |
+| Local Docker setup | `local-dev-setup` |
+| Capella (cloud) | `capella-quickstart` |
+| Connect from code | `server-connection-<lang>` |
+| SQL++ queries | `server-querying-<lang>` |
+| KV ops, CAS, bulk | `sdk-patterns-<lang>` |
+| Full-text / vector search | `search-<lang>` |
+| Transactions | `transactions-<lang>` |
+| Analytics / OLAP | `analytics-<lang>` |
+| Field-level encryption | `fle` → `fle-<lang>` |
+| Testing | `testing-patterns-<lang>` |
+| Caching / TTL | `caching-patterns` |
+| Data modeling | `server-data-modeling` |
+| Security / RBAC | `security` |
+| Eventing | `eventing` |
+| Kafka / DCP | `kafka` |
+| XDCR | `xdcr` |
+| Backup / restore | `backup` |
+| Disaster recovery | `disaster-recovery` |
+| Monitoring | `monitoring` |
+| Mobile (Android) | `mobile-android` |
+| Mobile (iOS) | `mobile-ios` |
+
+Replace `<lang>` with: `python`, `java`, `go`, `dotnet`, `nodejs`, `php`, `ruby`, `rust`, or `scala`.

skills/couchbase/examples/examples.md

@@ -0,0 +1,15 @@
+---
+skill: couchbase
+cases:
+
+  - id: couchbase-router-connection
+    input: "How do I connect to Couchbase from Python?"
+    expect:
+      - server-connection-python
+    code_block: python
+
+  - id: couchbase-router-transactions
+    input: "How do I run transactions in Go?"
+    expect:
+      - transactions-go
+    code_block: go

skills/getting-started/SKILL.md

@@ -5,6 +5,8 @@ description: Introduction to Couchbase for new developers — mental model, core
 metadata:
   last_verified: "2026-05"
   handoff:  # generated from routing.yaml — do not edit manually
+    - condition: "user asks a general Couchbase question and needs skill routing"
+      skill: couchbase
     - condition: "user wants to run Couchbase locally with Docker"
       skill: local-dev-setup
     - condition: "user wants to use Couchbase Capella (cloud)"