Context Map
- 4 installs
- 7 repo stars
- Updated August 2, 2026
- practicalswan/agent-skills
context-map is a Claude Code skill for ai & agent building.
About
Builds a concrete map of the files, dependencies, tests, and risks a change is likely to touch before implementation starts. A developer uses it when planning a feature, bugfix, refactor, or review to scope the work.
- Maps touch points, dependencies, and tests
- Flags nearby risks before editing
Context Map by the numbers
- 4 all-time installs (skills.sh)
- Ranked #2,331 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/practicalswan/agent-skills --skill context-mapAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 4 |
|---|---|
| repo stars | ★ 7 |
| Last updated | August 2, 2026 |
| Repository | practicalswan/agent-skills ↗ |
How do I helps with ai & agent building tasks.?
Scopes the real change surface before editing by mapping likely touch points, dependencies, tests, and nearby risks.
Who is it for?
A solo builder working on ai & agent building tasks who needs structured help with context map.
Skip if: Teams with no ai & agent building needs, or anyone wanting a generic chat assistant without this specific workflow.
When should I use this skill?
When you need to helps with ai & agent building tasks., or when context-map is a claude code skill for ai & agent building.
What you get
Structured output aligned to context-map: context-map, AI & Agent Building.
Files
Context Map
Build a task-focused map of the codebase before changing files.
- Leverage native parallel subagent dispatch and 200k+ context windows where available.
When to Use
Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.
- A request spans more than one file and the impact is not obvious yet.
- You need to identify the minimum safe edit set before implementation.
- You are debugging a bug or regression and need to trace nearby code paths.
- You want a review-quality summary of likely code, test, config, and documentation touch points.
Core Workflow
1. Restate the change in one sentence. 2. Search for obvious entry points by feature name, route, symbol, command, or error text. 3. Expand outward into direct dependencies, tests, docs, config, schemas, and scripts. 4. Separate likely edit targets from read-only reference patterns. 5. Call out risk multipliers such as public APIs, migrations, auth, secrets, environment variables, or generated artifacts. 6. Produce a compact context map before implementation.
Search Order
1. Primary Targets
Look for the files most likely to hold the requested behavior:
- route handlers, commands, services, jobs, or pages
- components, helpers, validators, and serializers
- feature-specific configs, manifests, templates, and generated sources
2. Direct Dependencies
Trace the files that import, export, call, or configure the primary targets:
- imports and exports
- DI registration and factory wiring
- schema or model definitions
- build or deployment hooks
3. Verification Surface
Find the evidence paths that should move with the change:
- unit, integration, E2E, and snapshot tests
- fixtures, golden files, and sample payloads
- README, usage docs, changelogs, and migration notes
4. Reference Patterns
Find nearby examples that show the house style for the same kind of work:
- similar endpoints or handlers
- related UI components
- existing test patterns
- prior migrations or config changes
Output Format
Use this structure unless the user asked for a different format:
## Context Map
### Likely Edit Targets
| File | Why it matters | Expected change |
|------|----------------|-----------------|
| path/to/file | Main entry point | Update logic |
### Nearby Dependencies
| File | Relationship |
|------|--------------|
| path/to/file | Imported by the main target |
### Verification Files
| File | Coverage |
|------|----------|
| path/to/test | Existing tests for the feature |
### Reference Patterns
| File | Pattern to reuse |
|------|------------------|
| path/to/example | Similar implementation shape |
### Risks
- Public API or contract may change
- Config, env vars, or generated files may need updates
- Docs or changelog may need to move with the codeHeuristics
- Prefer the smallest edit set that can fully implement the task.
- Include tests and docs whenever the behavior or setup might move.
- Treat migrations, auth, secrets, caching, build scripts, and generated artifacts as high-risk neighbors.
- If multiple subsystems are involved, split the map by subsystem instead of producing one giant table.
- Revise the map after discovery if the real scope is materially different from the initial request.
Anti-Patterns
- Delegating or evaluating without a scoped success condition: The output becomes hard to review and easy to overbuild.
- Skipping the evidence step: A workflow that cannot be re-checked quickly is not ready for handoff.
- Bundling unrelated subtasks together: It creates noisy prompts, weaker ownership, and avoidable integration risk.
Verification Protocol
Before claiming "skill applied successfully":
1. Pass/fail: The Context Map workflow names the agent boundary, delegated scope, and expected return artifact. 2. Pass/fail: Context passed to helpers is minimal, task-local, and free of hidden expected answers. 3. Pass/fail: Results are integrated only after evidence, diffs, or citations are checked by the controller. 4. Pressure-test scenario: Run the workflow on two similar tasks that must not share assumptions or leaked context. 5. Success metric: Zero context leakage; every delegated output is independently reviewable.
Scripts And References
- Context Map Template
- Context Map Builder
<!-- PORTABILITY:START -->
Cross-Client Portability
This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.
- GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
- Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
- Codex: install or sync the folder into
$CODEX_HOME/skills/<skill-name>and restart Codex after major changes. - Gemini CLI: this repository generates a project command named
/skills:context-mapfrom this skill. Rebuild commands withpython scripts/export-gemini-skill.py context-mapand then run/commands reloadinside Gemini CLI.
<!-- PORTABILITY:END -->
<!-- MCP:START -->
MCP Availability And Fallback
Preferred MCP Server: None required
- Fallback prompt: "Use the Context Map skill without MCP. Rely on the local
SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding." - If the current host does not expose a matching server, use the bundled references, scripts, native toolchain, and manual workflow already described in this skill.
- Treat direct local verification, rendered output, logs, tests, or screenshots as the fallback evidence path before completion.
<!-- MCP:END -->
Related Skills
- agent-task-mapping: Use it when the workflow also needs task-to-agent routing decisions.
- custom-agent-usage: Use it when the workflow also needs loading and invoking custom agent definitions safely.
- subagent-delegation: Use it when the workflow also needs safe, scoped delegation to helper agents.
- subagent-driven-development: Use it when the workflow also needs plan-driven implementation with reviewer loops.
Changelog
[2026-04-25] - Version 1.2 Verification Protocol Refresh
Added
- Added a
Verification Protocolsection with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric. - Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.
Changed
- Updated
SKILL.mdfrontmatter toversion: "1.2"andlast_updated: 2026-04-25. - Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.
[2026-04-24] - Version 1.1 Refresh
Changed
- Updated the SKILL frontmatter version to
1.1for the 2026-04-24 catalog refresh.
[2026-04-24] - Skill Refresh
Changed
- Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
- Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
- Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.
[2026-04-04] - Initial Import and Catalog Upgrade
Added
- Imported
context-mapfrom theawesome-copilotreference catalog into the canonical maintained workspace - Added a stronger scoping workflow, risk heuristics, and a reusable Markdown output format
- Added
references/context-map-template.mdandscripts/build-context-map.pyto make the skill actionable across clients
Tested
- Ran
python context-map/scripts/build-context-map.py --root . --query sync-skills --query codex --limit 5 - Planned validation through
python scripts/validate-skills.py
Context Map Template
Use this template when a request needs a concrete pre-edit map of the codebase.
## Context Map
### Task
- One-sentence restatement of the requested outcome.
### Likely Edit Targets
| File | Why it matters | Expected change |
|------|----------------|-----------------|
| path/to/file | Main logic or entry point | Update implementation |
### Nearby Dependencies
| File | Relationship |
|------|--------------|
| path/to/file | Imported by or configures the main target |
### Verification Files
| File | Coverage |
|------|----------|
| path/to/test | Existing verification path |
### Reference Patterns
| File | Pattern to reuse |
|------|------------------|
| path/to/example | Similar implementation |
### Risks
- Public API or contract may change
- Config, env vars, or generated files may need updates
- Docs or changelog may need to move with the code
### Open Questions
- Anything still uncertain after discoveryGuidance:
- Keep the map short enough to act on quickly.
- Split by subsystem if the request spans backend, frontend, infra, or docs.
- Revise the map if discovery shows the scope is materially different from the initial assumption.
#!/usr/bin/env python3
from __future__ import annotations
import argparse
import re
from collections import defaultdict
from pathlib import Path
IGNORE_DIRS = {
".git",
".gemini",
".next",
".serena",
".turbo",
".venv",
"__pycache__",
"bin",
"build",
"coverage",
"dist",
"node_modules",
"obj",
"out",
"tmp",
}
TEXT_SUFFIXES = {
".c",
".cs",
".css",
".go",
".java",
".js",
".json",
".jsx",
".md",
".mjs",
".php",
".ps1",
".py",
".rb",
".rs",
".sh",
".sql",
".toml",
".ts",
".tsx",
".txt",
".xml",
".yaml",
".yml",
}
IMPORT_RE = re.compile(
r"(?:^|\s)(?:from|import)\s+['\"]([^'\"]+)['\"]|require\(\s*['\"]([^'\"]+)['\"]\s*\)",
re.MULTILINE,
)
def is_text_file(path: Path) -> bool:
return path.suffix.lower() in TEXT_SUFFIXES
def iter_files(root: Path) -> list[Path]:
files: list[Path] = []
for path in root.rglob("*"):
if not path.is_file():
continue
if any(part in IGNORE_DIRS for part in path.parts):
continue
if is_text_file(path):
files.append(path)
return files
def score_file(path: Path, text: str, terms: list[str]) -> int:
path_text = path.as_posix().lower()
lowered_text = text.lower()
score = 0
for term in terms:
score += path_text.count(term) * 5
score += lowered_text.count(term)
return score
def summarize_role(path: Path) -> str:
name = path.name.lower()
lowered = path.as_posix().lower()
if "test" in name or "spec" in name or "__tests__" in lowered:
return "Test or verification file"
if path.suffix.lower() in {".md", ".txt"}:
return "Documentation or notes"
if name in {"package.json", "pyproject.toml", "go.mod", "pom.xml", "composer.json"}:
return "Project manifest or dependency config"
if path.suffix.lower() in {".yml", ".yaml", ".json", ".toml"}:
return "Configuration or metadata"
return "Primary implementation candidate"
def collect_imports(text: str) -> list[str]:
imports: list[str] = []
for match in IMPORT_RE.finditer(text):
value = match.group(1) or match.group(2)
if value:
imports.append(value)
return imports[:8]
def classify(path: Path) -> str:
lowered = path.as_posix().lower()
if "test" in lowered or "spec" in lowered:
return "test"
if path.suffix.lower() in {".md", ".txt"}:
return "reference"
if path.name.lower() in {"package.json", "pyproject.toml", "go.mod", "pom.xml", "composer.json"}:
return "dependency"
if path.suffix.lower() in {".json", ".toml", ".yaml", ".yml"}:
return "dependency"
return "edit"
def build_map(root: Path, queries: list[str], limit: int) -> str:
terms = [term.lower() for term in queries if term.strip()]
scores: dict[Path, tuple[int, str]] = {}
for path in iter_files(root):
try:
text = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
continue
score = score_file(path, text, terms)
if score <= 0:
continue
scores[path] = (score, text)
ranked = sorted(scores.items(), key=lambda item: (-item[1][0], item[0].as_posix()))[: max(limit * 3, 12)]
buckets: dict[str, list[tuple[Path, str]]] = defaultdict(list)
for path, (_, text) in ranked:
buckets[classify(path)].append((path, text))
def table(rows: list[str]) -> str:
return "\n".join(rows) if len(rows) > 2 else "None found."
edit_rows = [
"| File | Why it matters | Expected change |",
"|------|----------------|-----------------|",
]
for path, text in buckets["edit"][:limit]:
imports = collect_imports(text)
why = summarize_role(path)
expected = "Inspect implementation and confirm whether logic, types, or callers must move"
if imports:
expected = f"Inspect implementation; imported modules include {', '.join(imports[:2])}"
edit_rows.append(f"| {path.as_posix()} | {why} | {expected} |")
dep_rows = [
"| File | Relationship |",
"|------|--------------|",
]
for path, text in (buckets["dependency"] + buckets["reference"])[:limit]:
relation = summarize_role(path)
imports = collect_imports(text)
if imports:
relation = f"Likely wiring or shared dependency; references {', '.join(imports[:2])}"
dep_rows.append(f"| {path.as_posix()} | {relation} |")
test_rows = [
"| File | Coverage |",
"|------|----------|",
]
for path, _ in buckets["test"][:limit]:
test_rows.append(f"| {path.as_posix()} | Existing verification path touching the requested area |")
reference_rows = [
"| File | Pattern to reuse |",
"|------|------------------|",
]
for path, _ in buckets["reference"][:limit]:
reference_rows.append(f"| {path.as_posix()} | Nearby documentation or example that can anchor the implementation |")
risk_flags = []
lowered_paths = [path.as_posix().lower() for path, _ in ranked]
if any(any(token in value for token in ("auth", "permission", "secret", "token")) for value in lowered_paths):
risk_flags.append("- Authentication, authorization, or secrets may be involved.")
if any(any(token in value for token in ("schema", "migration", "sql", "model")) for value in lowered_paths):
risk_flags.append("- Schema or persistence changes may expand the blast radius.")
if any(any(token in value for token in ("readme", "changelog", "docs")) for value in lowered_paths):
risk_flags.append("- Documentation may need to move with the code change.")
if any(path.endswith(("package.json", "pyproject.toml", "go.mod", "pom.xml")) for path in lowered_paths):
risk_flags.append("- Dependency or build configuration updates may be required.")
if not risk_flags:
risk_flags.append("- No special risk markers found from filename heuristics; confirm manually after deeper reads.")
return "\n".join(
[
"## Context Map",
"",
"### Query",
f"- {', '.join(queries)}",
"",
"### Likely Edit Targets",
table(edit_rows),
"",
"### Nearby Dependencies",
table(dep_rows),
"",
"### Verification Files",
table(test_rows),
"",
"### Reference Patterns",
table(reference_rows),
"",
"### Risks",
*risk_flags,
]
)
def main() -> int:
parser = argparse.ArgumentParser(description="Generate a starter Markdown context map for a task.")
parser.add_argument("--root", default=".", help="Repository root to scan.")
parser.add_argument("--query", action="append", required=True, help="Query term to search for. Repeat as needed.")
parser.add_argument("--limit", type=int, default=6, help="Maximum rows per section.")
args = parser.parse_args()
root = Path(args.root).resolve()
print(build_map(root, args.query, args.limit))
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
Grill MeHave an agent relentlessly pressure-test their plan or design until every decision branch is resolved and shared understanding is reached.691k196kGrill With DocsPressure-test architecture decisions against their live codebase and living documentation before writing production code.585k196k
Lark CalendarLet their coding agents read, create, and manage events inside Lark (Feishu) Calendar directly from natural language instructions.493kLark ImLet their coding agent send instant notifications, post updates, and receive commands directly inside Lark (Feishu) workspaces.493kLark ContactLet their AI coding agents read and write contacts, send messages, and manage user data inside Lark (Feishu).493kLark AttendanceAutomatically fetch and report daily attendance data from Lark (Feishu) into their own tools or agents.493kFAQ
What does context-map do?
context-map is a Claude Code skill for ai & agent building.
When should I use context-map?
When you need to helps with ai & agent building tasks., or when context-map is a claude code skill for ai & agent building.
What are the main capabilities?
context-map; AI & Agent Building; AI-coding skill.