# Use CocoIndex with AI coding agents

> **CocoIndex v1.** This page documents CocoIndex **v1** — a ground-up redesign from v0. When writing code, ignore any v0 flow-builder DSL or deprecated decorators.
>
> Source: https://cocoindex.io/docs/getting_started/ai_coding_agents/ · Docs index: https://cocoindex.io/docs/llms.txt · Agent skill: https://cocoindex.io/docs/skill.md
>
> v0→v1 quick map — if you reach for these v0 symbols, stop and use the v1 form: `@cocoindex.flow_def`/`FlowBuilder` → `coco.App` + a `@coco.fn` main function; `add_collector()`/`collect()`/`export()` → declare target states (`declare_row`, `declare_file`); `cocoindex.sources/functions/targets.*` → connector APIs (`localfs.walk_dir`, `coco.ops.*`, `postgres.declare_table_target`). Full mapping + API reference: https://cocoindex.io/docs/skill.md.

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/`](https://github.com/cocoindex-io/cocoindex/tree/main/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](/docs/programming_guide/processing_component).
- **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:

```sh
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):

```sh
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:

```sh
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](/docs/contributing/guide) for how to get started.