skills.rest
adikpb
adikpbCOMMUNITY
Explore all skills by this author →
GitHub

codemap

Generate hierarchical codemaps and change-aware state files for unfamiliar repositories.

1|Updated Mar 15, 2025
Search Tags:#onboarding#node.js#change detection#codebase documentation#codemap#glob patterns#repository mapping
One-click install
npx skills add https://github.com/adikpb/dotfiles --skill codemap-adikpb
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codemap
Source: https://github.com/adikpb/dotfiles/tree/main/.config/opencode/skills/codemap
Command: npx skills add https://github.com/adikpb/dotfiles --skill codemap-adikpb

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Onboarding onto an unfamiliar codebase requires reading many files before any real work can begin. This Skill automates repository mapping by selecting relevant source files, tracking file and folder hashes for change detection, and scaffolding per-directory codemap.md documents that describe architecture, data flow, and integration points. ## Core Features & Use Cases - Repository Initialization: Scans a repo with include/exclude glob patterns, respects .gitignore, and writes .slim/codemap.json plus empty codemap.md templates in every relevant folder. - Incremental Change Detection: Compares current file hashes against saved state to report added, removed, and modified files and the affected folders, so only impacted codemaps get updated. - Legacy Migration and Agent Registration: Automatically migrates .slim/cartography.json to the new state format and registers the codemap in AGENTS.md so agents discover it on every session. - Use Case: When starting work on a new TypeScript project, run the init command to map src/**/*.ts files, then delegate fixer agents to fill each folder's codemap.md with responsibility, design patterns, and flow documentation. ## Quick Start Ask the agent to generate a codemap for this repository so it initializes the state file and scaffolds documentation for every source folder.

Frequently Asked Questions about codemap

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a codemap for a repository?▼

Run node codemap.mjs init with --root pointing at the repo and glob patterns like --include "src/**/*.ts" and --exclude "node_modules/**". This creates .slim/codemap.json with file hashes and empty codemap.md templates in each folder.

How to detect which files changed since the last codemap run?▼

Run node codemap.mjs changes --root ./ to compare current MD5 file hashes against the saved state. It lists added, removed, and modified files plus the affected folders that need codemap updates.

Does the codemap script respect .gitignore rules?▼

Yes, the script loads patterns from the repository's .gitignore file and excludes matching paths during file selection. It also skips hidden directories starting with a dot during the filesystem walk.

What files should be excluded from repository mapping?▼

Exclude tests (**/*.test.ts, tests/**), documentation (docs/**, *.md), and build artifacts (node_modules/**, dist/**, *.min.js). Only core code and config files should be included to keep the codemap focused.

What happens to legacy cartography.json state files?▼

The script automatically migrates .slim/cartography.json to .slim/codemap.json on the next load. If the new state file already exists, the legacy file is left untouched and no migration occurs.

When should I not run codemap generation?▼

Avoid running it on familiar repositories or as a routine step, since it is an expensive operation involving full file scans and agent delegation. Use it only when explicitly asked for codebase documentation or initial repository mapping.

Related Skills

Explore More Software Engineering Skills→
PaulKinlanPaulKinlan
2

codebase-survey

Survey codebases to inventory structure, dependencies, and programming patterns.

Community
Intermediate
dlwlrmaxdlwlrmax

codemap

Generates hierarchical codemaps and change-aware state files for unfamiliar repositories.

Community
Intermediate
Ramprasad4121Ramprasad4121
1

audit-prep-assistant

Prepare codebases for security review with static analysis and documentation.

Community
Advanced
TitoPrauseeTitoPrausee

inter-agent-gitlab-message-queue

Coordinate asynchronous AI agent messages through GitLab issues.

Community
Intermediate