Skip to content

skills.md

Latest commit

 

History

History
174 lines (128 loc) · 6.11 KB

skills.md

File metadata and controls

174 lines (128 loc) · 6.11 KB
Raw

codedb Skill Base & Context Files

This guide explains the hierarchy of context / instruction files that codedb-aware agents (Claude Code, Gemini CLI, Codex, Cursor, opencode, etc.) consult when working in a codedb-indexed project, and how each file's scope and precedence works.

There are three layers, from broadest to narrowest:

  1. Agent profile files — agents.md, CLAUDE.md, GEMINI.md, .cursorrules and friends. Per-agent project-wide instructions committed to the repo.
  2. Per-project codedb config — .codedbrc. Tunes index sizes, versioning, and tracing for the project.
  3. Per-developer memory — ~/.claude/projects/<id>/memory/ (Claude Code), ~/.gemini/memory/ (Gemini CLI). Personal, not committed, persists across sessions.

1. Agent profile files (committed, per-repo)

These files live at the repo root (or a subdirectory) and are loaded by the agent at session start. Each agent reads its own file:

Agent File name Notes
Claude Code CLAUDE.md also reads agents.md
Codex CLI agents.md reads CLAUDE.md as a fallback
Gemini CLI GEMINI.md
Cursor .cursorrules
opencode AGENTS.md

codedb itself ships docs/agents.md (the project's contributor instructions) — that is the canonical example of what an agent profile file looks like.

What to put in them

Agent profile files should describe things the LLM cannot derive from reading source — project conventions, the build/test commands, where tests live, the issue-filing protocol, code style preferences, language versions. Things that are derivable from source (file layout, function signatures, dependency graph) belong in the code, not here — agents discover those via codedb_tree, codedb_outline, codedb_deps, etc.

Example skeleton, drawn from docs/agents.md:

# <project> — Agent Instructions

## Project
<one paragraph: language, key dependencies, what to run for tests>

## Rules

### Filing Issues
<process the maintainer wants — required labels, failing-test convention>

### Test Style
<framework, allocator conventions, naming>

### Code Style
<comment policy, refactor scope, language version constraints>

Subdirectory overrides

Agents that support hierarchical instruction files (Gemini CLI, Codex) also read ./src/CLAUDE.md, ./tests/AGENTS.md, etc. — the agent merges the deepest-matching file's rules on top of the repo-root file.

Use subdirectory files when one part of the codebase has materially different conventions (e.g. frontend/ uses TypeScript with different formatting from a Zig backend/).

Activating specialised skills

Claude Code and Gemini CLI both support skills — named bundles of instructions that the agent can invoke explicitly (/skill <name>) or that fire on matching prompts. codedb provides /codedb-troubleshooting and /codedb-bench skills when installed via the official installer.

A skill lives under ~/.claude/skills/<name>/SKILL.md (Claude Code) or ~/.gemini/skills/<name>/SKILL.md (Gemini). Same shape as a profile file, plus front-matter declaring when it activates:

---
name: codedb-troubleshooting
description: Diagnose codedb MCP errors, missing files, stale indexes
when:
  - "codedb_*" tool calls return unexpected errors
  - "no project root" or "scan: loading_snapshot" appears
---

2. .codedbrc — per-project codedb tuning (committed)

Drop a .codedbrc at the project root to override codedb defaults for that project. Full keys + defaults:

# .codedbrc
max_cached   = 16384   # in-memory ContentCache size (files); v0.2.5815+
max_versions = 100     # versions kept per file in the change log
rerank_trace = false   # write per-search rerank-trace.jsonl (debug)

INI-style key = value, one per line, # for comments, unknown keys ignored. Pass --config-file <path> to the CLI to load an alternative.

Until v0.2.5815 (#460) max_cached was parsed-and-forgotten — the ContentCache was hardcoded to 16,384 files. v0.2.5815+ actually honors it.

3. Per-developer memory (not committed)

Personal memory persists across sessions for one developer on one machine, never committed. Different agents store it differently:

Agent Path
Claude Code ~/.claude/projects/<project-id>/memory/
Gemini CLI ~/.gemini/memory/<project-id>/

Memory is for things specific to you: your preferred review style, who the right reviewer is, past incidents you got burned by. Anything the team needs to know belongs in the committed agent profile file instead.

4. Where each file goes — quick reference

What Where Committed? Scope
Project conventions, build/test commands agents.md / CLAUDE.md / GEMINI.md at repo root yes every developer + agent
Subdirectory-specific rules <subdir>/CLAUDE.md etc. yes when working in that subdir
Index sizes, change-log depth .codedbrc yes every developer (per project)
Personal preferences, past incidents ~/.claude/...memory/ no one developer, all projects
Specialised skills ~/.claude/skills/<name>/SKILL.md no one developer, on demand

5. Linking it to MCP

When an agent uses codedb (via docs/mcp.md), the agent profile file teaches the agent how to use it — e.g.:

## How to navigate this repo
- Use `codedb_tree` first to orient.
- Use `codedb_context` with a natural-language task when starting work
  on an unfamiliar area — one call replaces 3–5 search/word/symbol calls.
- Use `codedb_symbol` for exact definition lookups, `codedb_search` for
  substring matches, `codedb_word` for single-identifier lookups.
- Use `codedb_callers` to find every usage of a symbol before refactoring.

The combination — codedb providing the engine, the agent profile file providing the playbook — is what makes the agent fast and opinionated on your codebase specifically.

See also