repo-mapping
Scannednpx machina-cli add skill works-yesed-scriptedit/awesome-slash/repo-mapping --openclawRepo Mapping Skill
Build and maintain a cached AST-based map of repository symbols and imports using ast-grep.
Primary Responsibilities
- Generate map on demand (
/repo-map init) - Update map incrementally (
/repo-map update) - Check status and staleness (
/repo-map status) - Validate output with the map-validator agent
Core Data Contract
Repo map is stored in the platform state directory:
- Claude Code:
.claude/repo-map.json - OpenCode:
.opencode/repo-map.json - Codex CLI:
.codex/repo-map.json
Minimal structure:
{
"version": "1.0.0",
"generated": "2026-01-25T12:00:00Z",
"updated": "2026-01-25T12:05:00Z",
"git": { "commit": "abc123", "branch": "main" },
"project": { "languages": ["typescript", "python"] },
"stats": { "totalFiles": 142, "totalSymbols": 847 },
"files": {
"src/auth/login.ts": {
"hash": "deadbeef1234abcd",
"language": "typescript",
"symbols": { "exports": [], "functions": [], "classes": [] },
"imports": [ { "source": "./utils", "kind": "named" } ]
}
}
}
Behavior Rules
- Never run ast-grep without user approval if it is not installed
- Never install dependencies without explicit user consent
- Always validate map output with
map-validatorafter init/update - Prefer incremental update unless map is stale or history rewritten
When to Suggest Repo Map
If a user asks for drift detection, documentation alignment, or repo analysis and repo-map is missing:
Repo map not found. For better analysis, run:
/repo-map init
Staleness Signals
- Map commit not found (rebased)
- Branch changed
- Git hooks marked stale
- Commits behind HEAD
Output Expectations
Keep outputs concise:
- init/update: file count, symbol count, commit, warnings
- status: staleness, commits behind, last updated
Source
git clone https://github.com/works-yesed-scriptedit/awesome-slash/blob/main/plugins/repo-map/skills/repo-mapping/SKILL.mdView on GitHub Overview
repo-mapping builds and maintains a cached AST-based map of repository symbols and imports using ast-grep. It supports on-demand generation, incremental updates, status checks, and validation via map-validator to ensure accuracy.
How This Skill Works
On init, the skill runs ast-grep to generate a map, stores it in the platform state directory, and records metadata like version and timestamps. It can perform incremental updates when requested and validates output with map-validator after init or update; staleness and drift logic guide updates.
When to Use It
- When you need drift detection, documentation alignment, or repo analysis and a repo map is missing
- When you need to align repository documentation with actual code structure
- When performing repo analysis to surface symbols and imports across languages
- When the user asks to create or regenerate a repo map (/repo-map init)
- When you want to verify the map’s freshness using status checks
Quick Start
- Step 1: Ensure ast-grep is installed and the user consents to usage
- Step 2: Run /repo-map init to generate the initial map
- Step 3: Run /repo-map status and, if needed, /repo-map update; validate with map-validator
Best Practices
- Never run ast-grep without user approval if it is not installed
- Never install dependencies without explicit user consent
- Always validate map output with map-validator after init/update
- Prefer incremental update unless the map is stale or history has been rewritten
- Return concise outputs (file count, symbol count, commit, warnings) per operation
Example Use Cases
- User asks to create a map for a mixed TypeScript/Python monorepo and saves results
- After adding new files, run /repo-map update to refresh symbols and imports
- Check /repo-map status to confirm the map is up to date with the latest commits
- Run map-validator to confirm map correctness before analysis reports
- Trigger drift detection workflow when a repository diverges from the map
