Repo Mapping Skill

Build and maintain a cached AST-based map of repository symbols and imports using ast-grep.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean); const action = args.find(a => !a.startsWith('--')) || 'status'; const force = args.includes('--force');

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-validator after 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