How to use the Project Structure Mapper agent skill

What the project-structure skill makes the agent do

Agent skills are folders of instructions and scripts that an AI agent can load when a task matches them. This one contains a script, map.ts, that reads a TypeScript or Swift repository and writes a single map file. The agent can then load that whole map at once instead of opening files one by one.

The map is built for whole-project reasoning: duplication hunting, refactor planning, architecture recon, or handing a full-project overview to another agent. It supports several output modes, from a names-only skeleton to full typed signatures.

• dense: one line per file, grouped by directory, for reconnaissance
• skeleton: one symbol per line, names only
• exports: exported symbols with full typed signatures (TypeScript only)
• full: exports plus non-exported top-level symbols (TypeScript only)

Install the skill (ZIP download or Claude apps upload)

Download the ZIP for this skill from this page and unzip it. Put the resulting folder in ~/.claude/skills/ to make it available to all your projects, or in a project's .claude/skills/ folder to limit it to that project.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

Check the requirements before you run it

The script needs Node.js 23.6 or newer, because it relies on native type stripping. If you run an older Node version, you can instead use npx tsx.

TypeScript scanning uses the typescript npm package, which is resolved from the target repository or, failing that, from the skill directory. Swift repositories need no extra dependency, because the Swift scanner is built into map.ts. A repo may mix both languages; files are detected by extension (.ts, .tsx, .swift).

• Node.js 23.6 or newer, or npx tsx for older Node versions
• typescript npm package for TypeScript scanning (not needed for pure Swift repos)
• Runs locally; the skill does not use the network

Trigger the skill with natural requests

You do not need to name the script. Describe the job in plain terms and the agent will load the skill when the request matches its description. Good triggers mention a whole repository and a goal, for example mapping a codebase before a refactor or looking for duplicated logic across files.

The skill's description covers whole-project reasoning, so phrases like architecture recon or a full-project map are reliable signals.

• "Map this TypeScript repo so you can find duplicated logic."
• "Give me a compact symbol map of the Swift project before we plan the refactor."
• "Produce a full-project map I can hand to another agent."

Run the mapper yourself

The agent runs the script from the skill's folder. The command takes the path to the repository root and optional flags. The output is one map file, by default project-structure-map.txt in the current directory, plus a JSON stats line on stdout with files, symbols, bytes and approxTokens.

Use --out to change the output path and --mode to choose the detail level. For a large repository, scope the map to one subsystem with --include, which accepts nested paths such as src/channels/turn.

• --mode dense|skeleton|exports|sigs|full (default dense)
• --include a,b,c to map only listed paths relative to the repo root
• --boundary x,y for plugin trees: child module names and package.json descriptions only
• --include-tests to keep test files (excluded by default)
• --members (Swift only) adds one-level-deep methods and properties
• --public-only (Swift only) keeps only open and public symbols

Use the two-tier workflow for refactors

Start with a dense whole-repo map to enumerate candidates. Then switch to a typed map of one subsystem for the actual decision. Names alone cannot tell duplicates apart from overloads, facades or lazy seams, so check every finding against typed signatures or the source before acting.

Treat map findings as leads, not verdicts. Spot-check file paths and claims with grep before you act on any analysis built from the map.

• Recon: dense map of the whole repo
• Decision: --mode exports --include <subsystem> for TypeScript, or --members --include <subsystem> for Swift
• Verify: grep the repo for every claim before changing code

Check your map after editing the mapper

If you change map.ts, run the self-test from the skill directory. It diffs the mapper output against checked-in fixtures for both languages. Without TypeScript installed, the Swift-only variant still runs.

• Full test: node selftest.mjs
• Swift only, without TypeScript installed: node selftest.mjs --swift-only