Giving Copilot a CODEMAP
I like coding assistants, but I do not particularly like watching them wander through a repository.
On a small code base, that wandering is often harmless. On a larger one, the assistant quickly ends up reading too much, crossing boundaries between unrelated areas, or anchoring on files that merely happen to match a keyword. The result is usually slower, and sometimes simply wrong.
That is why I ended up building copilot-codemap-skill myself.
The repository is not a big framework and it does not try to be one. I put it together as a very small collection of reusable assets for a simple workflow: give GitHub Copilot a hierarchical map of the repository before asking it to reason about implementation details.
What is in the repository?
The repository currently contains three main pieces:
- a skill in
.github/skills/analyze-submodule-map/SKILL.md - a reusable setup prompt in
.github/prompts/setup-codemap.prompt.md - a snippet for
.github/copilot-instructions.md
That is intentionally modest.
The point is not to create another giant layer on top of Copilot. The point is to package a navigation habit that can be copied into another repository with very little effort.
The actual workflow
The workflow revolves around CODEMAP.md files.
At the repository root, a CODEMAP.md gives a high-level overview of the major submodules and points to narrower maps. Larger areas then get their own child CODEMAP.md files, each scoped to its own directory. When Copilot is asked to analyze a part of the code base, the expected path is straightforward:
- read the root
CODEMAP.md - resolve the relevant submodule
- read the nearest child
CODEMAP.md - open only the source files that the selected map names
I like this because it is boring in the best possible way.
Instead of treating repository navigation as a fuzzy search problem every single time, the skill turns it into a repeatable sequence. Read the map first, narrow scope second, inspect source files third.
That alone already fixes a common problem with coding agents: they are often too eager to scan broadly before they understand where they are.
Why the skill is the interesting part
The skill itself is very explicit.
It tells Copilot to use the code-map hierarchy as the default navigation workflow for backend code, frontend code, tests, docs, prompts, and other major repository areas. It also tells the assistant what a useful answer should contain: scope, responsibilities, key files, important flows, and hotspots.
I find that last bit especially helpful. A lot of generated explanations are verbose but directionless. Asking for hotspots and key flows nudges the analysis toward the parts that are usually worth human attention.
Just as importantly, the skill does not pretend that the maps are always perfect. If a CODEMAP.md is stale or incomplete, Copilot should say so and then continue with targeted inspection. That is an important constraint. A map can help a lot, but it should never become a fake source of truth.
The setup prompt makes this reusable
The setup prompt is what turns the idea into something practical.
It tells Copilot to inspect the repository first, then create the root and child CODEMAP.md files, then add the skill, then update .github/copilot-instructions.md, and finally validate the links between the maps. In other words, it does not only describe the destination. It also describes how to get there in a repository that does not have any code maps yet.
That makes the repository useful beyond its own contents. It is a source of truth for reusable Copilot assets, not merely a demo.
There is also a small but important note in the README: the skill only becomes active when those files are copied into the target repository. That sounds obvious, but it matters. Copilot behavior is local to the project setup, not magically inherited from a separate repository living somewhere else on GitHub.
Why I think this is worth doing
What I like most about this approach is that it helps both the assistant and the human maintainer.
A good CODEMAP.md is lightweight architecture documentation. It gives future me a quick way back into the repository after some time away. At the same time, it gives Copilot a structured entry point that is much better than "search for something that looks relevant and hope for the best".
This also fits my general preference for making systems easier to understand through explicit structure rather than through clever prompting alone. Prompting still matters, of course. But if the repository itself exposes its shape clearly, the assistant has a much better chance of behaving sensibly.
copilot-codemap-skill is small, but I think it captures a useful idea: if we want coding agents to work better, we should not only improve the agent. We should also improve the surface the agent reads.
For me, that is exactly what a code map is supposed to do.