Couchbase Agent Skills

A collection of agent skills for working with Couchbase. Each skill teaches an AI agent how to work with a specific area of Couchbase technology — connection management, querying, search, transactions, mobile, and more.

Skills follow the Agent Skills specification.

Installation

Claude Code

Install Claude Code, then install this plugin from your project directory:

claude
/plugin install github:couchbaselabs/agent-skills

Codex

Install Codex, then add this repo as a marketplace source:

codex plugin marketplace add couchbaselabs/agent-skills

This registers the marketplace. Then open the plugin browser in Codex, find Couchbase Skills, and install it:

codex
/plugins

Once installed, skills activate in two ways:

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 directly by name:

$server-connection-python
$fle-go
$transactions-java

Alternative (no plugin system): clone the repo and symlink skills/ into .agents/skills/ in your project — Codex scans that directory automatically:

git clone https://github.com/couchbaselabs/agent-skills
ln -s $(pwd)/agent-skills/skills .agents/skills

Other agents (Cursor, Copilot, etc.)

Clone the repo and point your agent at AGENTS.md — it's the coding-agent configuration file and is read automatically by agents that support it.

Usage

Skills activate automatically when you ask a Couchbase-related question. The agent reads the matching skill's SKILL.md and follows its workflow, loading reference files on demand.

Skills hand off to each other automatically — for example, a connection skill routes to the querying skill when you ask about SQL++, and to the sdk-patterns skill when you ask about CAS or bulk operations.

Structure

skills/<skill-name>/
  SKILL.md          # Frontmatter (name, description, handoffs) + workflow
  references/       # Deep-dive reference files, loaded on demand
  examples/         # Input/output examples

Skill Index

Getting Started

Skill	Description
getting-started	Mental model, bucket/scope/collection/document hierarchy, service map
local-dev-setup	Docker Compose setup, cluster init, travel-sample, first query
capella-quickstart	Capella free tier, allowlist IP, database credentials, first query
vscode-extension	VS Code extension install, SQL++ workbench, notebooks, MCP server
sqlpp-language	SQL++ syntax — MISSING vs NULL, UNNEST, ANY/SATISFIES, JOIN, MERGE, window functions
error-handling	Timeout types, common exceptions, retry patterns, sdk-doctor
caching-patterns	TTL, cache-aside, write-through, session storage, rate limiting

Couchbase Capella

Skill	Description
capella	Capella connection, database credentials, Management API, Terraform
app-services	Managed Sync Gateway on Capella — App Endpoints, Sync Function, user management

Couchbase Server

Skill	Description
server-data-modeling	Bucket/scope/collection design, embed vs reference, TTL, time series
server-query-optimizer	Slow queries, GSI indexes, EXPLAIN output, aggregate pushdown
eventing	Document-triggered functions, enrichment, cascade delete, timers, webhooks
security	RBAC, least-privilege patterns, LDAP, SAML/SSO, TLS
xdcr	Cross-datacenter replication, topologies, filtering, conflict resolution
cluster-ops	Replicas, failover, rebalance, MDS topology, server groups
kafka	Kafka Connect source/sink, DCP streaming, transactional outbox
migration	Migrate from PostgreSQL, MongoDB, DynamoDB — cbimport, schema translation
backup	cbbackupmgr, incremental strategy, cloud object storage, encryption
disaster-recovery	RTO/RPO planning, XDCR failover, backup-based recovery, DR runbooks
monitoring	cbstats, Prometheus, Grafana, slow query log, alert thresholds
shell	cbsh commands, data import/export, multi-cluster, vector/RAG, Nushell

SDK Connection

Skill	Python	Java	Go	.NET	Node.js	Rust	Scala	PHP	Ruby
Connection, KV, sub-document, durability	✅	✅	✅	✅	✅	✅	✅	✅	✅

SQL++ Querying

Skill	Python	Java	Go	.NET	Node.js	Rust	Scala	PHP	Ruby
SELECT, DML, window functions, MERGE	✅	✅	✅	✅	✅	✅	✅	✅	✅

SDK Patterns

Skill	Python	Java	Go	.NET	Node.js	Rust	Scala	PHP	Ruby
CAS, locking, bulk ops, counters, error handling	✅	✅	✅	✅	✅	✅	✅	✅	✅

Transactions

Rust SDK 1.0 and Ruby SDK 3.x do not support distributed ACID transactions — see the stub skills for CAS and saga pattern alternatives.

Skill	Python	Java	Go	.NET	Node.js	Scala	PHP	Ruby	Rust
ACID multi-document transactions, durability	✅	✅	✅	✅	✅	✅	✅	⚠️	⚠️

Full-Text & Vector Search

search-concepts — FTS, vector search, hybrid search, Flex Index, RAG pipeline concepts and index setup.

Skill	Python	Java	Go	.NET	Node.js	Rust	Scala	PHP	Ruby
FTS, vector search, hybrid search, RAG	✅	✅	✅	✅	✅	✅	✅	✅	✅

Analytics

columnar-analytics — Couchbase Server 8.x columnar engine: direct collection queries, window functions, OLAP, migration from legacy CBAS.

Rust SDK 1.0 does not support the Analytics service — see analytics-rust for REST API and SQL++ alternatives.

Skill	Python	Java	Go	.NET	Node.js	Scala	Ruby	PHP	Rust
OLAP queries, window functions, Analytics datasets	✅	✅	✅	✅	✅	✅	✅	✅	⚠️

Field-Level Encryption

fle — concept overview: client-side field encryption, CryptoManager, key management, supported SDKs.

Rust, Scala, and Ruby SDKs do not support FLE — see the stub skills for application-code alternatives.

Skill	Python	Java	Go	.NET	Node.js	PHP	Rust	Scala	Ruby
CryptoManager, encrypt/decrypt fields	✅	✅	✅	✅	✅	✅	⚠️	⚠️	⚠️

Testing Patterns

testing-patterns — strategy, test data management, scope/collection isolation (language-agnostic concepts).

Skill	Python	Java	Go	.NET	Node.js	Rust	Scala	PHP	Ruby
Unit testing, integration testing, testcontainers	✅	✅	✅	✅	✅	✅	✅	✅	✅

Couchbase Mobile

Skill	Description
mobile-android	Couchbase Lite for Android — Kotlin/Java, CRUD, QueryBuilder, SQL++, replication
mobile-ios	Couchbase Lite for iOS/macOS — Swift, CRUD, QueryBuilder, SQL++, Combine, replication
mobile-data-modeling	Document design for Sync Gateway — channel strategy, embed vs reference, tombstones
mobile-sync-android	Replication for Android — Sync Gateway, Sync Function, offline-first, Kotlin
mobile-sync-ios	Replication for iOS/macOS — Sync Gateway, Sync Function, offline-first, Swift
mobile-conflict-resolution-android	Conflict resolvers for Android — merge strategies, auto-purge, Kotlin
mobile-conflict-resolution-ios	Conflict resolvers for iOS/macOS — merge strategies, auto-purge, Swift
mobile-vector-search-android	On-device vector search for Android (CBL EE) — VectorIndexConfiguration, hybrid FTS+vector, Kotlin
mobile-vector-search-ios	On-device vector search for iOS/macOS (CBL EE) — VectorIndexConfiguration, hybrid FTS+vector, Swift
mobile-p2p-sync-android	Device-to-device sync for Android — URLEndpointListener, TLS, cert pinning, Kotlin
mobile-p2p-sync-ios	Device-to-device sync for iOS/macOS — URLEndpointListener, TLS, cert pinning, Swift
mobile-logging-android	LogSinks API for Android — console, file, custom sinks, cbl-log tool, Kotlin
mobile-logging-ios	LogSinks API for iOS/macOS — console, file, custom sinks, cbl-log tool, Swift
mobile-testing-android	Unit and integration testing for Android — in-memory databases, JUnit, live query testing, Kotlin
mobile-testing-ios	Unit and integration testing for iOS/macOS — in-memory databases, XCTest, live query testing, Swift

SDK Feature Matrix

See references/sdk-feature-matrix.md for full feature support across all SDK languages (transactions, analytics, KV range scan, FLE, async).

Contributing

1. Create a directory under skills/ named after the skill (kebab-case).
2. Write SKILL.md with valid frontmatter (name, summary required). Do not add triggers:, priority:, or use_when: to SKILL.md.
3. Add an entry to discovery.yaml with skill, priority, use_when, and at least 3 triggers.
4. Add routing edges to routing.yaml, then run scripts/sync-handoffs.sh --apply.
5. Add examples/examples.md with representative input/output pairs.
6. Add the skill to the index table in AGENTS.md.
7. Run ./scripts/validate-skills.sh — must pass with 0 failures.

See AGENTS.md for full contribution guidelines and skill structure details.