home / skills / nickcrew / claude-cortex / codanna-codebase-intelligence

codanna-codebase-intelligence skill

safe

This skill indexes your codebase for semantic search, call graphs, and impact analysis, helping you understand dependencies before refactoring.

npx playbooks add skill nickcrew/claude-cortex --skill codanna-codebase-intelligence

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: codanna-codebase-intelligence
description: Use codanna MCP tools for semantic code search, call graphs, and impact analysis before grep/find.
---

# Codanna Codebase Intelligence

Codanna indexes your codebase and provides semantic search, call graphs, and dependency analysis via MCP tools. **Use codanna before grep/find** - it understands code structure, not just text patterns.

## When to Use

- **Finding code**: "Where do we handle authentication?" → `semantic_search_docs`
- **Understanding dependencies**: "What calls this function?" → `find_callers`
- **Impact analysis**: "What breaks if I change this?" → `analyze_impact`
- **Exploring symbols**: "Show me the Parser struct" → `find_symbol`

## Core Tools

### Discovery

```
# Natural language search - finds code by intent, not keywords
semantic_search_docs query:"error handling patterns" limit:5

# Search symbols by name/pattern
search_symbols query:"parse" kind:"function"

# Get full details on a specific symbol
find_symbol name:"process_file"
```

### Relationships

```
# Who calls this function? (upstream)
find_callers symbol:"validate_input"

# What does this function call? (downstream)
get_calls symbol:"process_request"

# Full dependency graph - what breaks if I change this?
analyze_impact symbol:"DatabaseConnection" depth:3
```

### Documentation (RAG)

```
# Search indexed markdown/docs
search_documents query:"API authentication" collection:"docs"
```

## Tool Selection Guide

| Task | Tool | Example |
|------|------|---------|
| Find code by concept | `semantic_search_docs` | "database migrations" |
| Find symbol by name | `search_symbols` | Pattern: "auth*" |
| Get symbol details | `find_symbol` | Exact: "UserService" |
| Trace callers | `find_callers` | "Who uses this?" |
| Trace dependencies | `get_calls` | "What does this call?" |
| Assess refactor risk | `analyze_impact` | "What breaks?" |

## Workflow Patterns

### Before Refactoring

1. `find_symbol` - understand current implementation
2. `find_callers` - identify all usage sites
3. `analyze_impact` - assess blast radius
4. Then proceed with changes

### Understanding Unfamiliar Code

1. `semantic_search_docs` - "how does X work"
2. `find_symbol` - get entry point details
3. `get_calls` - trace execution flow

### Finding Where to Add Code

1. `semantic_search_docs` - "similar patterns"
2. `find_callers` - how existing code integrates
3. Follow established patterns

## Why Codanna Over Grep

| Grep/Find | Codanna |
|-----------|---------|
| Text matching | Semantic understanding |
| String "parse" matches comments | `find_symbol` finds the actual function |
| Manual call tracing | `find_callers` shows full graph |
| Guessing impact | `analyze_impact` shows dependencies |

## Tips

- Start broad with `semantic_search_docs`, then drill down with `find_symbol`
- Use `analyze_impact` before any refactor touching shared code
- `find_callers` with depth > 1 shows transitive callers
- Results include file paths and line numbers - use for navigation

Overview

This skill integrates Codanna MCP tools to provide semantic code search, symbol discovery, call graphs, and impact analysis across a codebase. It helps engineers find intent-based code matches and trace dependencies before using grep/find. Use it to reduce guesswork when refactoring, onboarding, or searching for implementation sites.

How this skill works

The skill indexes source files and documentation, then exposes natural-language and symbol-level queries. It supports semantic searches (intent-driven), symbol lookups, caller/callee tracing, and multi-level impact analysis that reports files, line numbers, and transitive dependencies. Results are optimized for developer workflows: start broad, then drill into symbols and call graphs.

When to use it

Locating where a feature or concern is implemented without relying on exact keywords
Tracing who calls a function or which downstream functions a symbol invokes
Assessing blast radius before refactoring shared components
Exploring unknown code during onboarding or incident investigation
Finding documentation or design notes related to a code area

Best practices

Start with semantic_search_docs to capture intent and example sites, then use find_symbol for exact definitions
Run find_callers with depth > 1 when you need transitive caller context
Always run analyze_impact on shared types or services before large changes
Combine symbol results with file paths and line numbers to navigate directly in your editor
Limit search scope (by module or collection) for large codebases to reduce noise

Example use cases

Search for authentication handling using natural language to find all related modules and docs
Identify every caller of validate_input before changing its signature
Map the dependency graph for DatabaseConnection to understand which services break on change
Find the Parser struct or process_file implementation quickly without scanning files
Locate relevant markdown docs for API authentication using the indexed documentation search

FAQ

How is this different from grep or basic text search?

Codanna understands code structure and intent, not just string matches, so it finds actual symbols, call relationships, and semantically related code rather than incidental text occurrences.

Can I see transitive callers and callees?

Yes. find_callers and get_calls support configurable depth to reveal transitive relationships and full call paths.