{
  "version": "act 1.0.17",
  "slug": "code-navigation",
  "name": "code-navigation",
  "description": "Traverse large repositories efficiently using act's query tools. Use when exploring unfamiliar code, mapping dependencies, understanding API surfaces, analyzing side effects before modifying functions, or following call chains across files. Avoids reading entire files by querying only the structure needed.",
  "url": "https://act101.ai/docs/skills/code-navigation",
  "body_md": "# Code Navigation with act\n\nUse act's query tools to traverse large repositories efficiently.\nDo NOT read entire files when you can query for specific information.\n\n## Rules\n\n1. **Start with repo-outline** \u2014 Before exploring a codebase, run `repo_outline` to understand the file tree, languages, and structure. Use `--symbols` for files of interest.\n\n2. **Use skeleton for file structure** \u2014 When you need to understand a file's structure, use `skeleton` to see declarations without bodies. Never read an entire file just to find function names.\n\n3. **Use interface for API surfaces** \u2014 When you need to understand how to use a class or module, use `interface` to get signatures, types, and docstrings without implementation details.\n\n4. **Follow the dependency graph** \u2014 Use `graph` to understand how files are connected. Start from the file you're interested in with `--direction out` (what it depends on) or `--direction in` (what depends on it).\n\n5. **Use mutations for side-effect analysis** \u2014 Before modifying a function, use `mutations` to understand what external state it accesses or modifies. This tells you what might break.\n\n6. **Use control-flow for complex logic** \u2014 When a function is hard to understand, use `control_flow` to get a linearized view of its branching structure.\n\n7. **Batch symbol retrieval** \u2014 When you need symbols from multiple files, use `symbols_batch --files` instead of making separate `symbols` calls. When you need specific implementations, use `symbols_batch --ids` with stable IDs.\n\n8. **Use stable symbol IDs** \u2014 After finding a symbol, use its stable ID (format: `file::QualifiedName#kind`) for subsequent operations. This avoids ambiguity and eliminates the need to specify `--file`.\n\n9. **Use definition for cross-file navigation** \u2014 When you find a reference to an unknown symbol, use `definition` to jump to its source.\n\n10. **Analyze before modifying** \u2014 Before making changes, run `mutations` on affected functions and `graph` on affected files to understand the blast radius.\n\n## Token-Saving Hints\n\n- `repo_outline` costs ~7 tokens/file (vs reading files: ~250 tokens/file)\n- `skeleton` costs ~15 tokens/declaration (vs reading full file)\n- `interface` costs ~25 tokens/member (vs reading implementation)\n- Always use compact mode (default) \u2014 ranges are strings, not objects\n- Use `--depth` limits on `graph` and `repo_outline` to control output size\n- Filter `symbols_batch` with `--kinds` to get only what you need"
}