SKILL.md

$27

The query should describe the concept, functionality, or behavior to find, not exact code syntax. For example:

ccc search database connection pooling

ccc search user authentication flow

ccc search error handling retry logic

Filtering Results

By language (--lang, repeatable): restrict results to specific languages.

ccc search --lang python --lang markdown database schema

By path (--path): restrict results to a glob pattern relative to project root. If omitted, defaults to the current working directory (only results under that subdirectory are returned).

ccc search --path 'src/api/*' request validation

Pagination

Results default to the first page. To retrieve additional results:

ccc search --offset 5 --limit 5 database schema

If all returned results look relevant, use --offset to fetch the next page — there are likely more useful matches beyond the first page.

Working with Search Results

Search results include file paths and line ranges. To explore a result in more detail:

Use the editor's built-in file reading capabilities (e.g., the Read tool) to load the matched file and read lines around the returned range for full context.

When working in a terminal without a file-reading tool, use sed -n '<start>,<end>p' <file> to extract a specific line range.

Following Hints in Search Output

Search results are a mixed ranking of code chunks, per-file/dir summaries, and (when configured) curated concept guides — all scored against the same query. Two kinds of hit come with a follow-up command embedded in the output:

[summary] — a file or directory summary. Read with ccc describe <path>.

[guide] — a curated concept guide. Read with ccc guide <slug>.

When a hit carries one of these tags, follow the hint: the synthesised text is usually a faster read than chasing through individual files. Conversely, do not run ccc describe . or ccc guide proactively as a triage step — let search rank what's relevant and act on what it returns.

Describing Files and Directories

Per-file and per-directory summaries (when configured for the project) condense each file's public API, contracts, and role into a short markdown block. They are typically faster to consult than reading the source.

ccc describe src/auth/session.py        # one file

ccc describe src/auth/                  # directory: summary + children tree

ccc describe .                          # project root overview

Use describe when you already know the path you want; let ccc search find paths for you when you don't.

Concept Guides

Some projects configure cross-cutting concept guides in .cocoindex_code/guides.yml — synthesised markdown documents for architectural topics that span many files (e.g. memoization, plugin-SDK boundary, channel routing). Each guide names canonical files, end-to-end flow, and contracts/invariants.

ccc guide                               # list available guides + descriptions

ccc guide <slug>                        # print one guide

Discovery is search-driven: a relevant guide will surface in ccc search results tagged [guide] with a ccc guide <slug> hint. Run ccc guide (no args) only when first orienting in an unfamiliar codebase or when the user explicitly asks for the guide list — not as a routine first step.

Authoring guides.yml Interactively

When the user wants to add or improve concept guides, collaborate on the slug list rather than dumping a finished YAML. Good guide candidates are named subsystems the codebase obviously has — cross-cutting lifecycles, registration/dispatch protocols, end-to-end data paths. Single-file or symbol-specific topics do not warrant a guide; per-file summaries already cover those.

Recommended flow:

Survey the codebase. Use ccc describe . and a few likely subdirectory summaries to enumerate the project's subsystems and inter-edge boundaries.

Propose candidates. Suggest 5–10 slugs with one-line descriptions, framed to name the canonical starting file or directory for each topic. Show them to the user as a list.

Iterate. Ask which to keep, drop, rename, or merge. Surface non-obvious dependencies (deps:) so a higher-level guide can cite a lower-level one rather than restate it. Cycles are rejected at load time.

Write the YAML. Add the agreed entries to .cocoindex_code/guides.yml (creating the file if absent). Confirm defaults.enabled: true and that the project's summary feature is enabled — guides require summaries.

Generate. Run ccc index to drive the per-guide agent loop and produce <slug>.md files under .cocoindex_code/guides/. Re-run after editing descriptions to refresh.

Schema:

defaults:

  enabled: true                     # disables all guides when false

  model: openai/gpt-5.4-nano        # falls back to summary.model when omitted

  session_budget: 200

  max_logical_depth: 3

  max_turns_per_session: 18

guides:

  - slug: memoization                          # [a-z0-9][a-z0-9-]*

    description: |

      What this guide covers, framed for the reader.

      Name the canonical starting files (e.g. "start with src/cache.py").

    deps: [other-slug]                         # optional; must not cycle

    max_turns_per_session: 28                  # optional per-entry overrides

A multi-line description is fine and often clearer than one terse sentence — the description seeds the guide-generation agent's question, so concrete file/directory anchors pay off.

Settings

To view or edit embedding model configuration, include/exclude patterns, or language overrides, see settings.md.

Management & Troubleshooting

For installation, initialization, daemon management, troubleshooting, and cleanup commands, see management.md.

ccc