How do I install the Project Map skill?

Run npx skillmds@latest add theophiluschinomona/project-map in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Project Map safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Project Map?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Project Map free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Project Map?

TheophilusChinomona (@theophiluschinomona) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Project Map by theophiluschinomona — Agent Skill

Name: Project Map
Author: TheophilusChinomona

Project Map

Generates and maintains a detailed project map (all FE/BE files with mappings) at .claude/idev/project-map/project.map.md via Python watcher scripts. Use when generating or refreshing the project map, configuring the map watcher, or when another skill needs the map as a data source.

TheophilusChinomona 838913b 5 files · 27.3 KB Updated Sep 17, 2026

File contents

Project Map Skill

Purpose

Maintain a detailed, greppable map of the project — every frontend file (pages, containers, services) and every backend file (controllers, services). The map is the data source for the smart-context, file-index, and api-contract-validation skills.

State (per project)

File	Purpose
`.claude/idev/project-map/project.map.md`	The generated map (note the filename: `project.map.md`, NOT `project-map.md`)
`.claude/idev/project-map/watcher_config.json`	FE/BE paths + project type for the watcher

Scripts (in this skill folder)

Script	Purpose
`${CLAUDE_PLUGIN_ROOT}/skills/project-map/ai_map_updater.py`	One-shot map generation (CLI + importable `create_project_map`)
`${CLAUDE_PLUGIN_ROOT}/skills/project-map/map_watcher.py`	Long-running watcher; regenerates the map only when source files change (run from the project root)

Generate the map

# from the project root — auto-detects split vs unified, safe non-interactively
python3 "${CLAUDE_PLUGIN_ROOT}/skills/project-map/ai_map_updater.py"

# or with explicit options
python3 "${CLAUDE_PLUGIN_ROOT}/skills/project-map/ai_map_updater.py" \
  --root . --mode split --frontend ./frontend --backend ./backend

# or start the watcher (interactive config on first run)
python3 "${CLAUDE_PLUGIN_ROOT}/skills/project-map/map_watcher.py"

Always access the map via Grep — never load the whole file. Grep for the feature or file name (e.g. Grep "Order" .claude/idev/project-map/project.map.md), then Read only the source files it points to.
Load only the relevant section (frontend / backend / a single category) when a section-level view is needed.
If the map is missing or stale, regenerate it (command above) before trusting it.
Follow ${CLAUDE_PLUGIN_ROOT}/skills/project-map/map.rules.md for the full rules.

Staleness Detection

The map file records a Generated: timestamp at the top. Check staleness:

1. Read the first 5 lines of project.map.md
2. Extract the "Generated: YYYY-MM-DD" date
3. If older than 14 days → warn: "project-map is N days old — results may be stale"
4. If older than 30 days → fail loudly: "project-map is severely stale — regenerate before trusting"
5. If missing → generate before proceeding

The session-start hook also checks file mtime and warns if > 14 days old. When regenerating, update the Generated: timestamp in the output.

---name: project-mapdescription: Generates and maintains a detailed project map (all FE/BE files with mappings) at .claude/idev/project-map/project.map.md via Python watcher scripts. Use when generating or refreshing the project map, configuring the map watcher, or when another skill needs the map as a data source.---# Project Map Skill## PurposeMaintain a detailed, greppable map of the project — every frontend file (pages, containers, services) and every backend file (controllers, services). The map is the data source for the smart-context, file-index, and api-contract-validation skills.## State (per project)| File | Purpose ||------|---------|| `.claude/idev/project-map/project.map.md` | The generated map (note the filename: `project.map.md`, NOT `project-map.md`) || `.claude/idev/project-map/watcher_config.json` | FE/BE paths + project type for the watcher |## Scripts (in this skill folder)| Script | Purpose ||--------|---------|| `${CLAUDE_PLUGIN_ROOT}/skills/project-map/ai_map_updater.py` | One-shot map generation (CLI + importable `create_project_map`) || `${CLAUDE_PLUGIN_ROOT}/skills/project-map/map_watcher.py` | Long-running watcher; regenerates the map only when source files change (run from the project root) |## Generate the map```bash# from the project root — auto-detects split vs unified, safe non-interactivelypython3 "${CLAUDE_PLUGIN_ROOT}/skills/project-map/ai_map_updater.py"# or with explicit optionspython3 "${CLAUDE_PLUGIN_ROOT}/skills/project-map/ai_map_updater.py" \ --root . --mode split --frontend ./frontend --backend ./backend# or start the watcher (interactive config on first run)python3 "${CLAUDE_PLUGIN_ROOT}/skills/project-map/map_watcher.py"```- Always access the map via Grep — never load the whole file. Grep for the feature or file name (e.g. `Grep "Order" .claude/idev/project-map/project.map.md`), then Read only the source files it points to.- Load only the relevant section (frontend / backend / a single category) when a section-level view is needed.- If the map is missing or stale, regenerate it (command above) before trusting it.- Follow `${CLAUDE_PLUGIN_ROOT}/skills/project-map/map.rules.md` for the full rules.## Staleness DetectionThe map file records a `Generated:` timestamp at the top. Check staleness:```1. Read the first 5 lines of project.map.md2. Extract the "Generated: YYYY-MM-DD" date3. If older than 14 days → warn: "project-map is N days old — results may be stale"4. If older than 30 days → fail loudly: "project-map is severely stale — regenerate before trusting"5. If missing → generate before proceeding```The session-start hook also checks file mtime and warns if > 14 days old.When regenerating, update the `Generated:` timestamp in the output.

Frequently asked questions