playbooks

home / skills / openclaw / skills / agentlens

agentlens skill

/skills/nguyenphutrong/agentlens

This skill helps you navigate and understand a codebase using hierarchical documentation, enabling fast module discovery and symbol lookup.

npx playbooks add skill openclaw/skills --skill agentlens

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

Files (4)
SKILL.md
1.9 KB
---
name: agentlens
description: Navigate and understand codebases using agentlens hierarchical documentation. Use when exploring new projects, finding modules, locating symbols in large files, finding TODOs/warnings, or understanding code structure.
metadata:
  short-description: Codebase navigation with agentlens
  author: agentlens
  version: "1.0"
---

# AgentLens - Codebase Navigation

## Before Working on Any Codebase
Always start by reading `.agentlens/INDEX.md` for the project map.

## Navigation Hierarchy

| Level | File | Purpose |
|-------|------|---------|
| L0 | `INDEX.md` | Project overview, all modules listed |
| L1 | `modules/{slug}/MODULE.md` | Module details, file list |
| L1 | `modules/{slug}/outline.md` | Symbols in large files |
| L1 | `modules/{slug}/memory.md` | TODOs, warnings, business rules |
| L1 | `modules/{slug}/imports.md` | File dependencies |
| L2 | `files/{slug}.md` | Deep docs for complex files |

## Navigation Flow

```
INDEX.md → Find module → MODULE.md → outline.md/memory.md → Source file
```

## When To Read What

| You Need | Read This |
|----------|-----------|
| Project overview | `.agentlens/INDEX.md` |
| Find a module | INDEX.md, search module name |
| Understand a module | `modules/{slug}/MODULE.md` |
| Find function/class in large file | `modules/{slug}/outline.md` |
| Find TODOs, warnings, rules | `modules/{slug}/memory.md` |
| Understand file dependencies | `modules/{slug}/imports.md` |

## Best Practices

1. **Don't read source files directly** for large codebases - use outline.md first
2. **Check memory.md before modifying** code to see warnings and TODOs
3. **Use outline.md to locate symbols**, then read only the needed source sections
4. **Regenerate docs** with `agentlens` command if they seem stale

For detailed navigation patterns, see [references/navigation.md](references/navigation.md)
For structure explanation, see [references/structure.md](references/structure.md)

Overview

This skill helps you navigate and understand codebases using AgentLens hierarchical documentation. It provides a predictable project map so you can find modules, symbols, TODOs, and dependencies without scanning entire source trees. Use it to accelerate onboarding, code reviews, and targeted edits in large projects.

How this skill works

AgentLens organizes documentation under a .agentlens directory with an INDEX.md that maps the project and links into module-level docs. Each module exposes files like MODULE.md, outline.md, memory.md, and imports.md so you can locate symbols, discover warnings/TODOs, and inspect dependencies before opening source files. Follow the documented flow: INDEX.md → module → outline/memory → source file for efficient exploration.

When to use it

  • Onboarding into an unfamiliar repository to get a project overview quickly
  • Locating a module or file without scanning the whole codebase
  • Finding where a function or class is declared inside large files
  • Checking for TODOs, warnings, or business rules before making changes
  • Understanding file import relationships and dependency impact

Best practices

  • Always start at .agentlens/INDEX.md to get the high-level map
  • Consult modules/*/outline.md to jump to specific symbols rather than reading whole files
  • Read modules/*/memory.md before editing to surface TODOs and warnings
  • Use modules/*/imports.md to assess change impact across files
  • Regenerate the AgentLens docs if they seem out of date using the agentlens command

Example use cases

  • A new contributor reads INDEX.md, finds the responsible module, then uses outline.md to open only the relevant function in a large file
  • A maintainer checks memory.md to see existing warnings and TODOs before submitting a patch
  • A reviewer inspects imports.md to verify that a proposed refactor won't break dependent files
  • A developer searching for a symbol uses the module outline to jump directly to the declaration
  • Archiving or auditing an old project by following the AgentLens map to gather module summaries and issues

FAQ

What if the AgentLens docs are stale?

Regenerate the docs with the agentlens command and re-check INDEX.md and module pages before continuing.

Should I ever open source files directly?

For small repos it's fine, but for large codebases use outline.md first to avoid scanning irrelevant code.