Use CocoIndex with AI coding agents

Make Claude Code, Cursor, and other AI coding agents write correct CocoIndex v1 code by installing the official CocoIndex skill — concepts, APIs, and patterns packaged for agent context.

Version: v 1.0.14
Last reviewed: Jul 4, 2026

CocoIndex ships an official agent skill that teaches AI coding agents how to build CocoIndex v1 pipelines correctly — core concepts, API surface, common patterns, connectors, and best practices, all in one place.

The skill lives in the skills/cocoindex/ directory of the main repo.

Why a skill?

CocoIndex v1 is a fundamental redesign from v0. Without context, an LLM trained on older snapshots tends to hallucinate the wrong API (the v0 flow-builder DSL, deprecated decorators, missing @coco.fn, unstable component paths). The skill gives the agent a single concise reference covering:

Mental model — target_state = transform(source_state), declarative pipelines, processing components.
Core APIs — @coco.fn, mount / use_mount / mount_each, ContextKey, @coco.lifespan, target state declarations.
Common patterns — file transformation, vector embedding, LLM extraction, knowledge graphs.
Connectors — PostgreSQL, SQLite, LanceDB, Qdrant, SurrealDB, Apache Doris, LocalFS, S3, Kafka, Google Drive.
Best practices — memoization, stable component paths, vector schema with Annotated[NDArray, KEY].

Use with agent clients

Client / workflow	Recommended setup
Codex / Agent Skills-compatible clients	Use `.agents/skills/cocoindex` for repo-local discovery. In this CocoIndex repo, checked-in `.agents/skills` symlinks expose the public skill and contributor playbooks automatically.
Claude Code	Use `.claude/skills/cocoindex` in a project, or `~/.claude/skills/cocoindex` globally.
Cursor	Copy `skills/cocoindex/SKILL.md` into `.cursor/rules/cocoindex.md`.
Generic AGENTS.md / CLAUDE.md	Link to, import, or summarize `skills/cocoindex/SKILL.md` from your top-level agent instructions.
Context7	This repo’s `context7.json` already indexes `skills/cocoindex`; custom stacks can index the same folder.
Custom RAG / agent stack	Index the `skills/cocoindex/` directory, including `references/`, as regular documentation.

Agent Skills-compatible clients load a skill directory that contains SKILL.md. If .agents/skills/cocoindex is checked into your project, no extra install step is needed for clients that scan that path.

Project-local install for Codex or other Agent Skills-compatible clients:

mkdir -p .agents/skills
git clone --depth=1 https://github.com/cocoindex-io/cocoindex.git /tmp/cocoindex-skill
cp -r /tmp/cocoindex-skill/skills/cocoindex .agents/skills/

Use with Claude Code

Claude Code auto-loads skills from .claude/skills/ in the current project, or from ~/.claude/skills/ globally.

Project-local install (recommended for repos that build with CocoIndex):

mkdir -p .claude/skills
git clone --depth=1 https://github.com/cocoindex-io/cocoindex.git /tmp/cocoindex-skill
cp -r /tmp/cocoindex-skill/skills/cocoindex .claude/skills/

Global install:

mkdir -p ~/.claude/skills
git clone --depth=1 https://github.com/cocoindex-io/cocoindex.git /tmp/cocoindex-skill
cp -r /tmp/cocoindex-skill/skills/cocoindex ~/.claude/skills/

Once installed, Claude Code picks up the skill automatically when you ask it to build or modify a CocoIndex pipeline.

Use with other agents

The skill is plain Markdown — SKILL.md plus a few reference files. Any agent that accepts file-based context will work:

Cursor — copy skills/cocoindex/SKILL.md into .cursor/rules/cocoindex.md.
Generic AGENTS.md / CLAUDE.md — concatenate or @import SKILL.md from your top-level agent instructions file.
Context7 — use this repo’s context7.json shape as a reference; it indexes skills/cocoindex alongside docs and examples.
Custom RAG / agent stack — index the skills/cocoindex/ directory like any other documentation source.

What’s inside

skills/cocoindex/
├── SKILL.md                       # main entry — concepts, APIs, patterns
└── references/
    ├── api_reference.md           # quick API reference
    ├── connectors.md              # full connector reference
    ├── patterns.md                # detailed pipeline patterns
    ├── setup_project.md           # project setup
    └── setup_database.md          # database setup

Contributing

The skill is versioned alongside the codebase — when the API changes, the skill changes with it. PRs that improve clarity, add examples, or cover new connectors are welcome. See the contributing guide for how to get started.