Skip to content

AGENTS.md

Latest commit

 

History

History
380 lines (303 loc) · 29.3 KB

AGENTS.md

File metadata and controls

380 lines (303 loc) · 29.3 KB

AGENTS.md

This file provides guidance to AI coding agents (Claude, Cursor, Copilot, etc.) when working in this repository.

For the complete Agent Skills specification, see: https://agentskills.dev

What This Repository Contains

A collection of Couchbase agent skills for use in agentic workflows. Each skill teaches an AI agent how to work with a specific area of Couchbase technology.

Skill Index

Entry Point

Skill Description
couchbase Router skill — entry point for all Couchbase questions, reads discovery.yaml and routes to the right skill

Getting Started

Skill Description
getting-started Mental model, bucket/scope/collection/document hierarchy, service map, Couchbase vs SQL/MongoDB/Redis
local-dev-setup Docker Compose setup, cluster init, travel-sample, first query
capella-quickstart Capella free tier, allowlist IP, database credentials, connection string, first query
vscode-extension VS Code extension install, cluster connections, SQL++ workbench, notebooks, data import/export, MCP server
sqlpp-language SQL++ syntax — MISSING vs NULL, META().id, UNNEST, ANY/SATISFIES, ARRAY, JOIN, MERGE, window functions
error-handling AmbiguousTimeout vs UnambiguousTimeout, common exceptions, retry patterns, sdk-doctor, debug logging
caching-patterns TTL, cache-aside, write-through, getAndTouch, session storage, rate limiting, ephemeral buckets
testing-patterns Testing strategy, test data management, scope/collection isolation — concepts only (no language code)
testing-patterns-python Unit testing with unittest.mock, integration testing with testcontainers, scope isolation — Python
testing-patterns-java Unit testing with Mockito, integration testing with testcontainers, scope isolation — Java
testing-patterns-go Unit testing with testify/mock, integration testing with testcontainers, scope isolation — Go
testing-patterns-dotnet Unit testing with Moq, integration testing with Testcontainers.Couchbase, scope isolation — .NET
testing-patterns-nodejs Unit testing with Jest, integration testing with testcontainers, scope isolation — Node.js
testing-patterns-rust Unit testing with mockall, integration testing with testcontainers-rs, scope isolation — Rust
testing-patterns-scala Unit testing with ScalaMock, integration testing with testcontainers-scala, scope isolation — Scala
testing-patterns-php Unit testing with PHPUnit, integration testing with testcontainers, scope isolation — PHP
testing-patterns-ruby Unit testing with RSpec doubles, integration testing with testcontainers-ruby, scope isolation — Ruby

Couchbase Capella (DBaaS)

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

Couchbase Server

Skill Description
server-data-modeling Bucket/scope/collection hierarchy design, embed vs reference, TTL, time series patterns
server-query-optimizer Diagnose slow queries, recommend GSI indexes, analyze EXPLAIN output, aggregate pushdown
eventing Document-triggered functions — enrichment, cascade delete, timers, curl(), webhooks
security RBAC users, roles, least-privilege patterns, LDAP, SAML/SSO, TLS
fle Field-Level Encryption — client-side field encryption, CryptoManager, supported SDKs, key management
fle-python FLE with Python SDK — CryptoManager setup, encrypt/decrypt fields
fle-java FLE with Java SDK — CryptoManager, @Encrypted annotation
fle-go FLE with Go SDK — CryptoManager, EncryptingTranscoder
fle-dotnet FLE with .NET SDK — CryptoManager, [EncryptedField] attribute
fle-nodejs FLE with Node.js SDK — CryptoManager, encryptFields option
fle-php FLE with PHP SDK — CryptoManager, encryptFields option
fle-rust FLE not supported in Rust SDK 1.0 — application-code alternatives
fle-scala FLE not supported in Scala SDK — application-code alternatives
fle-ruby FLE not supported in Ruby SDK 3.x — application-code alternatives
xdcr Cross-datacenter replication — setup, topologies, filtering, conflict resolution
cluster-ops Replicas, failover, rebalance, MDS service topology, server groups
kafka Kafka Connect source/sink, DCP streaming, transactional outbox pattern
migration Migrate from PostgreSQL, MongoDB, DynamoDB — cbimport, schema translation, code migration
backup cbbackupmgr backup/restore, incremental strategy, merge, cloud object storage (S3/GCS/Azure), encryption
disaster-recovery RTO/RPO planning, XDCR active-passive/active-active failover, backup-based recovery, DR runbooks, recovery testing
monitoring cbstats, Prometheus metrics, Grafana dashboards, slow query log, alert thresholds, cbcollect_info

SQL++ Querying (per language)

Skill Description
server-querying-python SQL++ queries with Python SDK — SELECT, DML, transactions, window functions, MERGE
server-querying-java SQL++ queries with Java SDK — SELECT, DML, transactions, window functions, MERGE
server-querying-go SQL++ queries with Go SDK — SELECT, DML, transactions, window functions, MERGE
server-querying-dotnet SQL++ queries with .NET SDK — SELECT, DML, transactions, window functions, MERGE
server-querying-nodejs SQL++ queries with Node.js SDK — SELECT, DML, transactions, window functions, MERGE
server-querying-rust SQL++ queries with Rust SDK — SELECT, DML, named/positional params, scan consistency
server-querying-scala SQL++ queries with Scala SDK — SELECT, DML, case class deserialization, scan consistency
server-querying-php SQL++ queries with PHP SDK — SELECT, DML, named/positional params, scan consistency
server-querying-ruby SQL++ queries with Ruby SDK — SELECT, DML, named/positional params, scan consistency

SDK Connection (per language)

Each skill includes references/deployment-scenarios.md with language-specific Serverless, OLTP, OLAP, High-Traffic, and Multi-Node connection examples.

Skill Description
server-connection-python Python SDK connection pools, timeouts, singleton, sub-document, durability
server-connection-java Java SDK connection pools, timeouts, singleton, sub-document, durability
server-connection-go Go SDK connection pools, timeouts, singleton, sub-document, durability
server-connection-dotnet .NET SDK connection pools, timeouts, singleton, sub-document, durability
server-connection-nodejs Node.js SDK connection pools, timeouts, singleton, sub-document, durability
server-connection-rust Rust SDK (tokio) connection, KV CRUD, sub-document, durability, expiry
server-connection-scala Scala SDK connection, Try-based error handling, KV CRUD, sub-document, durability
server-connection-php PHP SDK connection, KV CRUD, sub-document, durability, expiry
server-connection-ruby Ruby SDK connection, KV CRUD, sub-document, durability, expiry

Transactions (per language)

Rust SDK 1.0 and Ruby SDK 3.x do not support distributed ACID transactions.

Skill Description
transactions-python ACID multi-document transactions with Python SDK — error handling, durability
transactions-java ACID multi-document transactions with Java SDK — error handling, durability
transactions-go ACID multi-document transactions with Go SDK — error handling, durability
transactions-dotnet ACID multi-document transactions with .NET SDK — error handling, durability
transactions-nodejs ACID multi-document transactions with Node.js SDK — error handling, durability
transactions-scala ACID multi-document transactions with Scala SDK — sync/async/reactive, error handling
transactions-php ACID multi-document transactions with PHP SDK — error handling, durability
transactions-ruby Transactions not supported in Ruby SDK 3.x — CAS, sub-document atomics, saga pattern alternatives
transactions-rust Transactions not supported in Rust SDK 1.0 — CAS, sub-document atomics, saga pattern alternatives

Full-Text & Vector Search (concept)

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

Full-Text & Vector Search (per language)

Skill Description
search-python FTS, vector search, hybrid search, Flex Index, RAG with Python SDK
search-java FTS, vector search, hybrid search, Flex Index, RAG with Java SDK
search-go FTS, vector search, hybrid search, Flex Index, RAG with Go SDK
search-dotnet FTS, vector search, hybrid search, Flex Index, RAG with .NET SDK
search-nodejs FTS, vector search, hybrid search, Flex Index, RAG with Node.js SDK
search-rust FTS, vector search, hybrid search with Rust SDK
search-scala FTS, vector search, hybrid search with Scala SDK
search-php FTS, vector search, hybrid search with PHP SDK
search-ruby FTS, vector search, hybrid search with Ruby SDK

Analytics (per language)

Rust SDK 1.0 does not support the Analytics service.

Skill Description
columnar-analytics Couchbase Server 8.x columnar analytics — direct collection queries, window functions, OLAP, migration from legacy CBAS
analytics-python OLAP queries, window functions, Analytics datasets with Python SDK
analytics-java OLAP queries, window functions, Analytics datasets with Java SDK
analytics-go OLAP queries, window functions, Analytics datasets with Go SDK
analytics-dotnet OLAP queries, window functions, Analytics datasets with .NET SDK
analytics-nodejs OLAP queries, window functions, Analytics datasets with Node.js SDK
analytics-scala OLAP queries, window functions, Analytics datasets with Scala SDK
analytics-php OLAP queries, window functions, Analytics datasets with PHP SDK
analytics-ruby OLAP queries, window functions, Analytics datasets with Ruby SDK
analytics-rust Analytics Service not supported in Rust SDK 1.0 — REST API and SQL++ query alternatives

SDK Patterns (per language)

Skill Description
sdk-patterns-python CAS, pessimistic locking, bulk ops, atomic counters, KV range scan, error handling — Python
sdk-patterns-java CAS, pessimistic locking, bulk ops, atomic counters, KV range scan, error handling — Java
sdk-patterns-go CAS, pessimistic locking, bulk ops, atomic counters, KV range scan, error handling — Go
sdk-patterns-dotnet CAS, pessimistic locking, bulk ops, atomic counters, KV range scan, error handling — .NET
sdk-patterns-nodejs CAS, pessimistic locking, bulk ops, atomic counters, KV range scan, error handling — Node.js
sdk-patterns-rust CAS, bulk ops with tokio, atomic counters, sub-document, error handling — Rust
sdk-patterns-scala CAS, pessimistic locking, bulk ops, atomic counters, sub-document, error handling — Scala
sdk-patterns-php CAS, pessimistic locking, bulk ops, atomic counters, sub-document, error handling — PHP
sdk-patterns-ruby CAS, pessimistic locking, bulk ops, atomic counters, sub-document, error handling — Ruby

Couchbase Mobile

Skill Description
mobile-android Couchbase Lite for Android — Kotlin/Java, CRUD, QueryBuilder, SQL++, live queries, blobs, replication
mobile-ios Couchbase Lite for iOS/macOS — Swift, CRUD, QueryBuilder, SQL++, live queries, Combine, replication
mobile-data-modeling Document design for Sync Gateway — channel strategy, ownership fields, embed vs reference, tombstones, multi-tenant, schema versioning
mobile-sync-android Couchbase Lite replication for Android — Sync Gateway, Sync Function, offline-first, channels, Kotlin
mobile-sync-ios Couchbase Lite replication for iOS/macOS — Sync Gateway, Sync Function, offline-first, channels, 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, lazy indexes, hybrid FTS+vector, Kotlin
mobile-vector-search-ios On-device vector search for iOS/macOS (CBL EE) — VectorIndexConfiguration, lazy indexes, hybrid FTS+vector, Swift
mobile-p2p-sync-android Device-to-device sync for Android — URLEndpointListener, TLS, cert pinning, delta sync, Kotlin
mobile-p2p-sync-ios Device-to-device sync for iOS/macOS — URLEndpointListener, TLS, cert pinning, delta sync, 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, mocking the replicator, Kotlin
mobile-testing-ios Unit and integration testing for iOS/macOS — in-memory databases, XCTest, live query testing, mocking the replicator, Swift

Couchbase Shell

Skill Description
shell cbsh commands, data import/export, multi-cluster management, vector/RAG, Nushell basics

Skill Structure

Each skill follows this layout:

skills/<skill-name>/
  SKILL.md          # Primary skill file — frontmatter + workflow instructions
  references/       # Supporting reference files linked from SKILL.md
    *.md
  examples/         # Input/output examples for testing and illustration
    examples.md

SKILL.md frontmatter fields

---
name: skill-name              # must match the directory name
summary: One sentence — what this skill covers
allowed-tools: Bash           # optional — only when the skill runs bash commands
compatibility: ...            # optional — scalar string: SDK version, platform requirements
metadata:
  last_verified: "2026-05"   # update to current YYYY-MM when you materially edit skill content
  min_server_version: "7.0"  # optional — minimum Couchbase Server version
  deprecated_by: other-skill # optional — set when this skill is superseded
  deprecated_since: "8.0"    # optional — version from which deprecated_by applies
  max_server_version: "7.6"  # optional — last version this skill applies to
  handoff:                    # generated from routing.yaml — do not edit manually
    - condition: "user asks about slow queries"
      skill: server-query-optimizer
---

triggers:, priority:, and use_when: are not in SKILL.md. They live in discovery.yaml — the canonical source for first-turn routing.

Shared Content

shared/ — platform-agnostic reference content shared across skill pairs. Skills link to these files rather than duplicating content.

File Shared by
shared/server/sdk-connection-concepts.md all server-connection-* skills (9 languages)
shared/server/durability.md all server-connection-* skills (9 languages) — guidance on when to use each durability level
shared/server/subdocument.md all server-connection-* and sdk-patterns-* skills — lookup_in, mutate_in, array ops, counters
shared/server/sql-syntax.md all server-querying-* skills (9 languages) — SELECT, JOINs, MERGE, window functions
shared/server/analytics-vs-query.md all analytics-* skills (8 languages) — when to use Analytics vs Query Service
shared/server/search-concepts.md all search-* skills (9 languages) — index prerequisites, hybrid search, RYOW, pagination, query types
shared/server/testing-mock-examples.md all testing-patterns-* skills (9 languages) — mock pattern reference
shared/mobile/cbl-core.md mobile-android, mobile-ios
shared/mobile/sync-architecture.md mobile-sync-android, mobile-sync-ios
shared/mobile/conflict-resolution-concepts.md mobile-conflict-resolution-android, mobile-conflict-resolution-ios
shared/mobile/p2p-sync-concepts.md mobile-p2p-sync-android, mobile-p2p-sync-ios
shared/mobile/logging-concepts.md mobile-logging-android, mobile-logging-ios
shared/mobile/testing-concepts.md mobile-testing-android, mobile-testing-ios
shared/mobile/vector-search-concepts.md mobile-vector-search-android, mobile-vector-search-ios

references/ vs shared/ policy

  • shared/ — content that is language-agnostic and applies to multiple skill families. Add here when the same concepts or multi-language examples would otherwise be duplicated across 3+ skills. Link from SKILL.md with ../../shared/....
  • references/ inside a skill — content that is specific to that skill's language or narrow topic (e.g., language-specific bulk-ops patterns, reactive API details). Do not put multi-language content here; promote it to shared/ instead.
  • Rule: if a references/ file is identical or near-identical across two or more language skills, it belongs in shared/.

Discovery Manifest

discovery.yaml — canonical source for first-turn routing. Each entry defines skill, priority (primary/secondary), use_when, and triggers. The validator enforces no duplicate triggers across skills and a minimum of 3 triggers per skill. Do not add these fields to individual SKILL.md files.

priority: primary wins over priority: secondary when multiple skills match the same trigger phrase. Concept skills and narrow feature skills with unique triggers should be primary; language-specific skills should be secondary so general questions route to the concept skill first.

Routing Graph

routing.yaml — the canonical skill handoff graph. Each edge has from, to, condition, and type (topic, platform, variant). Use this for tooling, visualization, and validating that all handoff targets exist. Individual SKILL.md handoff: blocks are kept for inline agent reference and must stay consistent with this file. Run scripts/sync-handoffs.sh --apply after editing routing.yaml.

SDK Feature Matrix

references/sdk-feature-matrix.md — which features (transactions, analytics, KV range scan, FLE, async) are supported per SDK language. Use this when routing to a language-specific skill or advising on SDK selection.

Scripts

Runnable helper scripts in scripts/:

Script Purpose
validate-skills.sh Validate all skills for structural correctness (no cluster needed)
sync-handoffs.sh Sync SKILL.md handoff: blocks from routing.yaml (dry-run by default; --apply to write)
eval.sh List eval cases (--dry-run) or run them against an LLM (--execute, not yet implemented)
test-validator.sh Self-test for validate-skills.sh — runs assertions against a minimal fixture tree
check-cluster.sh Verify cluster connectivity and run SQL++ smoke tests against travel-sample
explain-query.sh Run EXPLAIN and highlight plan warnings
create-gsi-index.sh Create a GSI index via REST API
update-statistics.sh Update statistics for all indexes on a collection
create-fts-index.sh Create a full-text search index from a JSON definition
create-rbac-user.sh Create a least-privilege application user

Templates

Reusable boilerplate in templates/:

Template Purpose
fts-index-basic.json Full-text search index definition
vector-index.json Vector search index definition
eventing-function.js Eventing Function skeleton
sync-function.js Sync Gateway Sync Function skeleton
docker-compose.yml Local Couchbase dev environment
scripts/init-cluster.sh One-shot cluster init script (run inside the container after docker compose up)
sdk-connection.py Python SDK connection singleton
sdk-connection-java.java Java SDK connection singleton
sdk-connection-go.go Go SDK connection singleton
sdk-connection-dotnet.cs .NET SDK connection singleton
sdk-connection-nodejs.js Node.js SDK connection singleton
sdk-connection-php.php PHP SDK connection singleton
sdk-connection-ruby.rb Ruby SDK connection singleton
sdk-connection-rust.rs Rust SDK connection singleton (tokio)
sdk-connection-scala.scala Scala SDK connection singleton

Examples Format

Each examples/examples.md must begin with a YAML frontmatter block defining eval cases:

---
skill: skill-name
cases:
  - id: unique-case-id
    input: "User message to send to the agent with this skill loaded"
    expect:
      - keyword or phrase that must appear in the response
      - another expected term
    reject:                  # optional — terms that must NOT appear
      - wrong-language-import
    code_block: python       # optional — response must contain a fenced code block of this language
    threshold: 2             # optional — minimum expect terms that must match (default: all)
---

Matching semantics (all matching is case-insensitive substring):

  • expect — each term must appear somewhere in the response text. All terms must match unless threshold: is set.
  • reject — each term must NOT appear anywhere in the response. Use for wrong-language imports, deprecated APIs, or known hallucinations. Fails if any reject term is found.
  • code_block — the response must contain at least one fenced code block tagged with this language (e.g. ```python). Omit for conceptual/prose questions.
  • threshold — integer: at least this many expect terms must match. Use when a response may legitimately use synonyms (e.g. OVER or PARTITION BY for window functions).

Keep input realistic — use actual user phrasings, not test descriptions. Keep expect terms specific enough to distinguish correct from incorrect responses.

Markdown body (after the closing ---): the body is human-readable documentation of the same cases. Each example follows this structure:

## Example N

**Input:** <same text as the frontmatter input field>

**Output:**
<representative ideal response, including code blocks where relevant>

The body is not parsed by tooling — it exists for human review and as a reference when writing or updating eval cases. Keep it in sync with the frontmatter cases (same order, same inputs).

Eval execution status: The examples.md frontmatter is a specification for LLM-based evaluation — it defines what a correct agent response must contain. validate-skills.sh checks structural validity (required fields, recognised language identifiers) but does not execute the cases against an LLM. check-cluster.sh tests cluster connectivity via SQL++ smoke tests only and does not read examples.md. Use scripts/eval.sh --dry-run to list all cases; --execute (not yet implemented) will run them against an LLM.

Skill Layout

All skills — shared and language-specific — live on main under skills/. The previous branch-per-language model (skills/python, skills/go, etc.) has been retired; those branches are stale and should not be used. All changes go directly to main.

Contributing a New Skill

  1. Create a directory under skills/ named after the skill (kebab-case, matches name in frontmatter).
  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. Check for duplicate triggers across all skills.
  4. Add routing edges to routing.yaml, then run scripts/sync-handoffs.sh --apply to regenerate handoff blocks.
  5. Add reference files under references/ for content too large for the main skill file.
  6. Add examples/examples.md with eval frontmatter and representative input/output pairs.
  7. Add the skill to the index table in this file.
  8. Run ./scripts/validate-skills.sh — must pass with 0 failures.

Guidelines for Skill Content

  • SKILL.md should be self-contained for the most common use cases. Reference files handle depth.
  • Keep SKILL.md under ~300 lines. Move large reference tables to references/.
  • Use concrete code examples in the language(s) most relevant to the skill.
  • triggers phrases should be specific enough to avoid false positives.
  • Add handoff entries in frontmatter for natural skill boundaries.
  • Only set allowed-tools: Bash when the skill's workflow requires the agent to run shell commands — not for illustrative bash snippets.
  • Do not add arbitrary documentation files — update existing files or add reference files.