repo-mapping
Use when user asks to "create repo map", "generate repo map", "update repo map", "repo map status", or "map symbols/imports". Builds and validates an AST-based repo map using ast-grep.
Best use case
repo-mapping is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when user asks to "create repo map", "generate repo map", "update repo map", "repo map status", or "map symbols/imports". Builds and validates an AST-based repo map using ast-grep.
Teams using repo-mapping should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/repo-mapping/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How repo-mapping Compares
| Feature / Agent | repo-mapping | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when user asks to "create repo map", "generate repo map", "update repo map", "repo map status", or "map symbols/imports". Builds and validates an AST-based repo map using ast-grep.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Repo Mapping Skill
Build and maintain a cached AST-based map of repository symbols and imports using ast-grep.
## Parse Arguments
```javascript
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const action = args.find(a => !a.startsWith('--')) || 'status';
const force = args.includes('--force');
```
## Primary Responsibilities
1. **Generate map** on demand (`/repo-map init`)
2. **Update map** incrementally (`/repo-map update`)
3. **Check status** and staleness (`/repo-map status`)
4. **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:
```json
{
"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 updatedRelated Skills
turborepo-caching
Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing distributed caching.
power-bi-report-design-consultation
Power BI report visualization design prompt for creating effective, user-friendly, and accessible reports with optimal chart selection and layout design.
monorepo-management
Master monorepo management with Turborepo, Nx, and pnpm workspaces to build efficient, scalable multi-package repositories with optimized builds and dependency management. Use when setting up monor...
daily-news-report
Scrapes content based on a preset URL list, filters high-quality technical information, and generates daily Markdown reports.
clinical-reports
Write comprehensive clinical reports including case reports (CARE guidelines), diagnostic reports (radiology/pathology/lab), clinical trial reports (ICH-E3, SAE, CSR), and patient documentation (SOAP, H&P, discharge summaries). Full support with templates, regulatory compliance (HIPAA, FDA, ICH-GCP), and validation tools.
make-repo-contribution
All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly.
azure-cosmos-java
Azure Cosmos DB SDK for Java. NoSQL database operations with global distribution, multi-model support, and reactive patterns.
azure-cosmos-db-py
Build Azure Cosmos DB NoSQL services with Python/FastAPI following production-grade patterns. Use when implementing database client setup with dual auth (DefaultAzureCredential + emulator), service...
azure-containerregistry-py
Azure Container Registry SDK for Python. Use for managing container images, artifacts, and repositories.
azure-compute-batch-java
Azure Batch SDK for Java. Run large-scale parallel and HPC batch jobs with pools, jobs, tasks, and compute nodes.
azure-communication-sms-java
Send SMS messages with Azure Communication Services SMS Java SDK. Use when implementing SMS notifications, alerts, OTP delivery, bulk messaging, or delivery reports.
azure-communication-common-java
Azure Communication Services common utilities for Java. Use when working with CommunicationTokenCredential, user identifiers, token refresh, or shared authentication across ACS services.