code-search
/code-search
Use when you need to find where something is defined, understand how a feature is implemented, or explore an unfamiliar repo. Guides which tools to use and in what order.
- Author
- elastic ↗
- Repository
- sourcerer ↗
- Licence
- Apache-2.0
- Last repository change
- 23.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.09.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Use when you need to find where something is defined, understand how a feature is implemented, or explore an unfamiliar repo. Guides which tools to use and in what order.
Original author description
Use when you need to find where something is defined, understand how a feature is implemented, or explore an unfamiliar repo. Guides which tools to use and in what order.
How it works
- Repo discovery and ref resolution
- Choosing the right tool
- Iterating toward an answer
- Narrowing with filepath
- Reading for citation
- Parallel calls
SKILL.md preview
---
name: "code-search"
description: "Use when you need to find where something is defined, understand how a feature is implemented, or explore an unfamiliar repo. Guides which tools to use and in what order."
---
## Repo discovery and ref resolution
If you don't know which repo or ref (branch, tag, or version) to search, use your `repo-discovery` or `ref-resolution` skills first.
## Choosing the right tool
### `code.search` - BM25 keyword/concept search
Use when you know *what* you're looking for but not *where*:
- Concept or feature names ("circuit breaker", "token refresh", "shard allocation")
- Natural-language descriptions of behavior
- When exact spelling is uncertain (BM25 scores partial matches)
Returns the top-N highest-scoring lines. Default n=10; increase to 25-50 for broader coverage. Results are ranked by relevance, not by file or line order.
### `code.grep` - regex search
Use when you know the exact identifier or pattern:
- Symbol definitions: class names, function names, constants, config keys
- Import statements, annotation usages, string literals
- Structural patterns (`public.*interface.*Service`, `@Override`)
Returns all matching lines up to n. Default n=100; lower for focused lookups, raise if you expect many matches. Results are in file/line order.
### `files.ls` and `files.tree` - file and directory listings
Use to orient yourself or confirm a path before reading:
- Explore an unfamiliar repo's top-level structure
- Find which subdirectory contains a feature (e.g. `src/main/java/org/elasticsearch/*/`)
- Verify a file path exists before passing it to cat/head/grep
Supports `*` (one path segment) and `**` (recursive) glob patterns. A bare `*` lists the top level.
### `files.cat` - full file contents
Use for small, complete files where you need all the context:
- Config files, build descriptors, short modules
- Avoid on large source files - use grep/search with a narrow `file_path` instead
Returns the entire file; no line limit.
### `files.head` - first N lines of a file
Use when the top of the file is sufficient:
- Package/module declarations, imports, class-level structure
- File headers
Default n=10; increase for longer preambles.
### `files.tail` - last N lines of a file
Use when the bottom of the file is what matters:
- Closing blocks, trailing configuration entries
Default n=10.
### `files.wc` - count lines in file(s)
Use to verify file sizes before deciding how to read files:
- Avoid using `files.cat` on large files. Prefer `files.head`, `files.tail`, or `files.read_lines` to save tokens.
- Prefer using l=true to count just the lines (not bytes, words, etc).
## Iterating toward an answer
**Pattern 1 - concept → file → definition:**
1. `code.search` on the concept to identify candidate files
2. `files.ls` on a promising directory to confirm the layout
3. `code.grep` with a specific symbol pattern (e.g. `.*class CircuitBreaker.*`) to find the definition
4. `files.cat` or `files.head` for surrounding context
**Pattern 2 - known symbol → definition:**
1. `code.grep` with an anchored regex scoped to `**` or a known subdirectory
2. If context is needed beyond the match lines, `files.cat` the file or widen the grep pattern
**Pattern 3 - explore unfamiliar repo:**
1. `files.ls` at `*` to see the top-level structure
2. `files.ls` into the relevant subdirectory
3. `files.head` on key files (entry points, primary config)
4. `code.search` or `code.grep` to locate the specific feature
## Narrowing with `file_path`
All content tools accept a `file_path` glob. Narrowing it cuts noise and speeds results:
- `**/*.java` - all Java files
- `src/main/**` - source tree only, excluding tests
- `src/main/java/org/elasticsearch/index/**` - one subsystem
- `config/elasticsearch.yml` - a specific file (exact match)
A bare `*` matches a single path segment, so it lists only top-level files (no `/` in the path). Use `**` to recurse.
## Reading for citation
When you read to cite a specific line or range, follow each tool's own citation guidance in its description, and see the `code-citations` skill for the full rules:
- `code.grep` / `code.search` return one row per line, each with an authoritative `line.number` - cite single lines and never merge separate rows into a range.
- `files.cat` / `files.head` / `files.tail` / `files.read_lines` prefix each returned line with its 1-indexed number by default (grep -n style, `<line>:<content>`) - read the number off the first and last lines to cite a range. Pass `show_line_numbers=false` when you want raw, unprefixed text.
- Never derive a line position by counting lines inside returned content - read it from the per-line prefix.
## Parallel calls
When two searches are independent, issue them in the same turn. For example, grep for a class definition and search for its concept simultaneously, then synthesize the results.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · elastic/sourcerer | 100 | Apache-2.0 |
| langwatch/langwatch | 100 | Apache-2.0 |
| edmundmiller/dotfiles | 100 | MIT |
| atretyak1985/swarmery | 100 | Apache-2.0 |
| athola/claude-night-market | 100 | MIT |
| brettatoms/agent-skills | 100 | MIT |
| agentscope-ai/agentscope-java | 90 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 04adfecd04e7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90explore
Read-only file search and codebase exploration specialist. Use when you need to find files by pattern, search code with regex, navigate unfamiliar codebases, or understand code architecture without making changes. - 100gitnexus-exploring
Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\ - 100memory-exploring
Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "how does X work?", "what calls this function?", "show me the auth flow", "where is the DB logic?". - 90kit-learn-repo
Learn an unfamiliar codebase — purpose, layout, how to run/test, safe change points. Use when joining a repo, switching projects, or before the first change in a new area. - 100explore
Multi-angle codebase exploration by parallel agents: structure, data flow, architecture, health. Use to map an unfamiliar repo. NOT for task research files (use create-research). - 90repo-onboarding
Use when starting in an unfamiliar repository, new codebase, greenfield checkout, or 'where do I start' moment and you need a fast structured map of stack, entrypoints, patterns, risks, and next steps before any edits. Triggers: onboard me to this repo, map the codebase, explore unfamiliar project.