|
1 | 1 | --- |
2 | 2 | name: ccc |
3 | | -description: "This skill should be used when code search, file/directory summary lookup, or concept-guide lookup is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'describe this file', 'read the concept guide', 'update the index', 'ccc', 'cocoindex-code'." |
| 3 | +description: "This skill should be used when code search is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'update the index', 'ccc', 'cocoindex-code'." |
4 | 4 | --- |
5 | 5 |
|
6 | 6 | # ccc - Semantic Code Search & Indexing |
@@ -62,71 +62,6 @@ Search results include file paths and line ranges. To explore a result in more d |
62 | 62 | - 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. |
63 | 63 | - When working in a terminal without a file-reading tool, use `sed -n '<start>,<end>p' <file>` to extract a specific line range. |
64 | 64 |
|
65 | | -### Following Hints in Search Output |
66 | | - |
67 | | -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: |
68 | | - |
69 | | -- `[summary]` — a file or directory summary. Read with `ccc describe <path>`. |
70 | | -- `[guide]` — a curated concept guide. Read with `ccc guide <slug>`. |
71 | | - |
72 | | -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. |
73 | | - |
74 | | -## Describing Files and Directories |
75 | | - |
76 | | -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. |
77 | | - |
78 | | -```bash |
79 | | -ccc describe src/auth/session.py # one file |
80 | | -ccc describe src/auth/ # directory: summary + children tree |
81 | | -ccc describe . # project root overview |
82 | | -``` |
83 | | - |
84 | | -Use `describe` when you already know the path you want; let `ccc search` find paths for you when you don't. |
85 | | - |
86 | | -## Concept Guides |
87 | | - |
88 | | -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. |
89 | | - |
90 | | -```bash |
91 | | -ccc guide # list available guides + descriptions |
92 | | -ccc guide <slug> # print one guide |
93 | | -``` |
94 | | - |
95 | | -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. |
96 | | - |
97 | | -### Authoring `guides.yml` Interactively |
98 | | - |
99 | | -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. |
100 | | - |
101 | | -Recommended flow: |
102 | | - |
103 | | -1. **Survey the codebase.** Use `ccc describe .` and a few likely subdirectory summaries to enumerate the project's subsystems and inter-edge boundaries. |
104 | | -2. **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. |
105 | | -3. **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. |
106 | | -4. **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. |
107 | | -5. **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. |
108 | | - |
109 | | -Schema: |
110 | | - |
111 | | -```yaml |
112 | | -defaults: |
113 | | - enabled: true # disables all guides when false |
114 | | - model: openai/gpt-5.4-nano # falls back to summary.model when omitted |
115 | | - session_budget: 200 |
116 | | - max_logical_depth: 3 |
117 | | - max_turns_per_session: 18 |
118 | | - |
119 | | -guides: |
120 | | - - slug: memoization # [a-z0-9][a-z0-9-]* |
121 | | - description: | |
122 | | - What this guide covers, framed for the reader. |
123 | | - Name the canonical starting files (e.g. "start with src/cache.py"). |
124 | | - deps: [other-slug] # optional; must not cycle |
125 | | - max_turns_per_session: 28 # optional per-entry overrides |
126 | | -``` |
127 | | -
|
128 | | -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. |
129 | | -
|
130 | 65 | ## Settings |
131 | 66 |
|
132 | 67 | To view or edit embedding model configuration, include/exclude patterns, or language overrides, see [settings.md](references/settings.md). |
|
0 commit comments