repo-surveyor

What This Skill Does

The repo-surveyor is a diagnostic and investigative skill designed for OpenClaw agents operating in environments where standard automated discovery tools like Cartograph CLI or MCP are absent, misconfigured, or unreliable. Rather than brute-forcing a repository by reading every file, which is costly and noisy, the repo-surveyor implements a systematic manual investigation workflow. It acts as an expert human developer would: identifying entry points, mapping the architecture through high-fan-in dependency hubs, and filtering out noise like vendored libraries or build artifacts. By manually curating the minimal viable set of files, the skill provides the context required for high-quality documentation generation or task resolution without overwhelming the agent's context window.

Installation

To integrate this tool into your OpenClaw environment, execute the following command in your terminal:

clawhub install openclaw/skills/skills/anthony-maio/repo-surveyor

Ensure that you have the necessary read permissions for your project directory, as the skill will need to traverse file structures to identify key architectural hubs.

Use Cases

• Legacy Repo Onboarding: Use this when inheriting undocumented codebases where automated scanners fail to identify the main entry points.
• Verify AI Hallucinations: Use this as a cross-check if Cartograph or other automated tools produce conflicting reports about repository structure.
• Low-Context Environments: When you lack access to MCP servers or CLI toolsets, the repo-surveyor acts as your primary navigation compass.
• Focused Documentation: When you only need to summarize a specific feature slice rather than the entire repository, use this to extract only the relevant file set.

Example Prompts

1. "I'm stuck in an unknown project directory. Run repo-surveyor to identify the entry points and main dependency hubs so I can start working on the authentication module."
2. "Cartograph is offline. Perform a manual survey of this repository and provide a summary of the API surface so I can build a new client implementation."
3. "Use repo-surveyor to narrow down the file set to only the critical configuration and business logic files for the search feature. Ignore the build folder."

Tips & Limitations

• Prefer Automation: Always check if use-cartograph is available first. The repo-surveyor is intended as a backup or verification mechanism.
• Narrowing Scope: The effectiveness of the survey depends on your initial prompts. Be specific about which subsystem you want to survey to prevent the tool from drifting into irrelevant directories.
• OpenProse Integration: If you have the OpenProse plugin enabled, start your documentation efforts by looking at the openprose/ template folder. The repo-surveyor can automatically map files into these structured templates for you.
• Depth Limits: To prevent context bloat, the tool is designed to stop at immediate dependency hubs rather than mapping the entire transitive graph.