New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Project Structure Map

by steipete in steipete/agent-scripts

Compresses a TypeScript or Swift repository into one symbol-map text file sized for an LLM context window, for refactor planning and architecture recon.

MITAuto-check passedAgent Workflows

Install Project Structure Map

skills CLI
$ npx skills add steipete/agent-scripts --skill project-structure -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install steipete/agent-scripts project-structure --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/steipete/agent-scripts.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/project-structure .claude/skills/project-structure && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
project-structure
GitHub stars
7.3k
Token cost
~1.9k tokens
SKILL.md length
941 words
Files
11
Skills in repo
45
Repo updated
First seen
Licence
MIT

At a glance

Compresses a TypeScript or Swift repository into one symbol-map text file sized for an LLM context window, for refactor planning and architecture recon.

  • Planning a refactor that touches many files in a TypeScript or Swift repo
  • SKILL.md covers Run, Flags, Swift specifics and Sizing, plus 1 more section
  • Runs Swift, TypeScript and JavaScript scripts from its folder; calls node and npx
  • Hunting for duplicated helpers across a whole project

What it does

This skill squeezes a TypeScript or Swift repository into a single text file that fits in a model's context window, listing files, exported symbols, typed signatures and plugin boundaries. A bundled `map.ts` does the work: for TypeScript it runs the compiler in parse-only mode without type-checking, and for Swift it uses a dependency-free scanner based on regexes and brace depth. A repository can mix both languages, and files are picked up by extension.

You run it with Node against a repo root and choose a detail level with `--mode`. Dense gives one line per file, skeleton lists symbol names, exports adds typed signatures and the first doc-comment line, sigs collapses type bodies, and full also includes non-exported symbols. The last three apply to TypeScript only, and Swift files fall back to the dense style. `--include` limits the map to a subtree, `--boundary` lists plugin directories by module name only, and `--out` sets the file path. The default output is `project-structure-map.txt` plus a JSON line with file, symbol, byte and token estimates.

It needs Node 23.6 or newer, which strips types natively, or `npx tsx`. The folder also holds fixtures with expected output for TypeScript and Swift and a `selftest.mjs` script.

When your agent uses it

  • Planning a refactor that touches many files in a TypeScript or Swift repo
  • Hunting for duplicated helpers across a whole project
  • Giving another agent a compact map of the full codebase
  • Getting oriented in the architecture of an unfamiliar repository

Example prompts

  • “Generate a project map of this repo in exports mode so we can plan the refactor.”
  • “Map only src/channels and treat the plugins directory as a boundary.”
  • “Build a dense map of the iOS app and point out where similar helpers are duplicated.”
  • “Produce a map file small enough to paste into a fresh agent session.”

Requirements

  • Node 23.6 or newer, or `npx tsx`
  • A TypeScript or Swift repository to map

What it can do on your machine

Read from SKILL.md and the folder at commit 79150cf. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships script files (Swift, TypeScript and JavaScript), which the agent can run.

    Shell commands in SKILL.md call:

    • node
    • npx

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Project Structure Map loads about 1.9k tokens when it runs. Until then it costs about 84 tokens; SKILL.md has 941 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~84
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from steipete/agent-scripts at commit 79150cf, republished under its MIT licence (© steipete). 941 words, ~1,876 tokens.

Download SKILL.mdSave it as .claude/skills/project-structure/SKILL.md (or your agent's skills folder). This skill also uses 10 other files; get the full folder from GitHub.
name
project-structure
description
Generate a single-file compressed symbol map of a TypeScript or Swift repository — files, exported symbols, typed signatures, plugin boundaries — sized to fit an LLM context window. Use for whole-project reasoning: duplication hunting, refactor planning, architecture recon, or feeding another agent a full-project map.

Project Structure

Compress a TS or Swift repo into one map file an agent can load whole. Backed by map.ts next to this file. TS: parse-only TS compiler, no type-check; ~8k files in ~5s; resolves the typescript package from the target repo, falling back to this skill dir. Swift: zero-dependency regex/brace-depth scanner built into map.ts (no typescript needed for pure-Swift repos). Requires Node >= 23.6 (native type stripping) or npx tsx. .ts/.tsx and .swift files are detected by extension; a repo may mix both.

Run

bash
node <this-skill-dir>/map.ts <repoRoot> [flags]

<this-skill-dir> is the base directory of this skill as announced when the skill loads (canonical: ~/Projects/agent-scripts/skills/project-structure).

Output: one map file (default project-structure-map.txt in cwd) plus a JSON stats line (files, symbols, bytes, approxTokens) on stdout.

Flags

  • --out <file> — output path.
  • --mode dense|skeleton|exports|sigs|full — default dense.
    • dense: dir-grouped, one line per file: file fn:a,b ty:T cl:C c:x re:./y. Recon tier. File extensions are stripped for compactness, so a same-basename TS and Swift file in one dir share a line prefix (theoretical in practice; grep the repo to disambiguate).
    • skeleton: one symbol per line, names only.
    • exports: exported symbols with full typed signatures, type bodies, first doc-comment line. Refactor-decision tier. TS-only — Swift files fall back to their dense-style line (no fabricated signatures).
    • sigs: exports but type/interface bodies collapsed to member names (only ~10% smaller than exports; rarely worth it). TS-only, same Swift fallback.
    • full: exports + non-exported top-level symbols (marked internal; internal consts appear only when function-valued or explicitly typed — untyped internal consts are filtered as noise). TS-only, same Swift fallback.
  • --include a,b,c — paths to map, relative to repoRoot (default: all top-level dirs, minus skips/boundaries). Accepts nested paths, not just top-level dirs: --include src/channels/turn maps exactly that subtree. Headers stay repoRoot-relative, so running from repo root with --include <subsystem> is the recommended way to map a subsection.
  • --boundary x,y — dirs listed as boundary index only: child module names + one-line package.json descriptions, no symbol content. Use for plugin/extension trees.
  • --include-tests — keep test files and test-support infra (default: both excluded; Swift test detection is path-based: Tests?/ dirs and *Tests.swift).
  • --no-docs — strip doc comments (saves ~13% on typed modes).
  • --fn-consts-only — drop non-function const exports (on Swift files: drops every let/var symbol — closure-valued consts are indistinguishable without type info). Caution: silently drops files whose only exports are consts (plugin definition objects, schemas, registries). Prefer keeping consts in dense (names are cheap).
  • --re-counts — collapse re-export path lists to a count (dense; saves ~10%).
  • --max-per-kind N — cap each symbol-kind list per file with +n overflow marker (dense; 10–12 is safe).
  • --members — Swift only (ignored for TS files): additionally emit one-level-deep methods/properties as Type.member; extension members appear under their target type.
  • --public-only — Swift only (ignored for TS files): keep only symbols whose written access is open/public.

When --include is absent, source files sitting directly in repoRoot are scanned too (so pointing repoRoot at a leaf source dir works); with --include, only the listed paths are walked.

Show full SKILL.md (462 more words)Show less

Swift specifics

Zero-dependency line scanner (lexical masking of comments/strings + brace-depth tracking), validated 1:1 against SourceKitten on 1,850 files across two real repos (100% top-level symbol agreement) at ~100× SourceKitten's speed. Known limitations (accepted tradeoffs of the parserless design): one declaration per line is assumed — a member on the same line as its type (struct Box { var v = 1 }) or a second semicolon-separated declaration is not emitted; bare /…/ regex literals are not masked (lexically ambiguous with division), so a brace inside one can desync depth for the rest of that file — extended #/…/# literals are masked correctly; comments or raw/multiline literals nested inside string interpolations, emoji identifiers, and #if branches whose alternative headers declare differently named containers are best-effort (same-name platform-split containers work). Kinds: fn = func (incl. operator funcs); cl = class, actor; ty = struct, enum, protocol, typealias, macro, and extensions as extension:TargetType; c = let/var. Visibility is appended per symbol as [open]/[public]/[package]/[private]/[fileprivate]; internal (Swift's default) is deliberately untagged to save map bytes. Tags reflect written access; members of protocols/extensions without a written modifier inherit the container's access. Swift puts most code inside types, so the default top-level map is thin (median ~2 symbols/file) — reach for --members when method-level recon matters.

Sizing

TS (reference: openclaw, ~7M LOC, ~14k source files; o200k tokens; byte/4 estimate runs ~5–15% high — verify with a real tokenizer when near a budget):

  • exports, whole repo: ~2.5M tokens — never fits; scope typed maps to one subsystem.
  • exports, one subsystem (e.g. src/channels, 257 files): ~79k.
  • skeleton, whole repo: ~717k (fits 1M-class windows).
  • dense, whole repo: ~430k real.
  • dense, src+packages + extensions boundary, --re-counts --max-per-kind 12: ~218k real.
  • dense, src only + boundaries, --re-counts --max-per-kind 10: ~197k real (fits a 200k window).

Swift (reference: Peekaboo, 1,122 source files after test exclusion; byte/4 estimates):

  • dense top-level: ~34k tokens (3,962 symbols).
  • dense --members: ~197k (20,909 symbols) — ~6× top-level.
  • dense --public-only: ~12k (1,285 symbols).
  • dense --members --public-only: ~74k — the API-surface tier for big Swift repos.

Workflow guidance

  • Two-tier: dense whole-repo map for reconnaissance and candidate enumeration; then --mode exports --include <subsystem> (TS) or --members --include <subsystem> (Swift) for the actual refactor decision. Names alone cannot distinguish duplicates from overloads, facades, or .runtime.ts lazy seams — verify every dense-tier finding against typed signatures or source before acting.
  • Feeding codex CLI: turn input hard-caps at 1,048,576 chars (~260k tokens); pipe the map via stdin. Bigger maps need a direct Responses API call ($codex-huge-context) or a model with a larger window.
  • Do not bother with dictionary/abbreviation compression: measured on openclaw, total possible savings were 292 tokens (0.15%) — BPE already compresses repeated identifiers.
  • Map findings are leads, not verdicts: spot-verify file paths and claims with grep before acting on any model analysis of a map.
  • node selftest.mjs (in this skill dir) diffs the mapper against checked-in fixtures for both languages — run it after editing map.ts.

© steipete, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 10 other files in skills/project-structure of steipete/agent-scripts.

  • SKILL.md
  • fixtures/expected/swift-dense.txt
  • fixtures/expected/swift-members.txt
  • fixtures/expected/swift-public.txt
  • fixtures/expected/swift-skeleton.txt
  • fixtures/expected/ts-dense.txt
  • fixtures/swift/SyntaxFixture.swift
  • fixtures/swift/visibility/Visibility.swift
  • fixtures/ts/destructured.ts
  • map.ts
  • selftest.mjs

Open the folder on GitHubat commit 79150cf

Compare with similar skills

Project Structure Map next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Project Structure Map compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Project Structure Map this skillsteipete/agent-scripts7.3k—~1.9kAutomated safety check: PassMIT
Ripwire Code Navigationredhat-et/ripwire2.4k—~4.8kAutomated safety check: NotesApache-2.0
Swarmcj-vana/claude-swarm117—~11kAutomated safety check: WarnMIT
Typescript Best Practicesjwynia/agent-skills165—~2.5kAutomated safety check: PassMIT
Sonarjsmanagedcode/dotnet-skills486—~1.6kAutomated safety check: PassMIT
Frontend Module Standardssiteboon/claudecodeui14k—~2.6kAutomated safety check: PassAGPL-3.0

Similar skills

  • Ripwire Code Navigation

    redhat-et/ripwire

    Answers questions about a named symbol, such as its callers, what it calls, the path between two symbols or the downstream impact of changing it, using the ripwire CLI.

    2.4k GitHub stars~4.8k tokensUpdated 2 days ago
    DevelopmentAuto-check: notes

  • Swarm

    cj-vana/claude-swarm

    Orchestrate parallel Claude Code worker swarms with protocol-based behavioral governance.

    117 GitHub stars~11k tokensUpdated 7 mo ago
    Agent WorkflowsAuto-check: warnings

  • Typescript Best Practices

    jwynia/agent-skills

    Guide AI agents through TypeScript coding best practices including type safety, error handling, code organization, and architecture patterns.

    165 GitHub stars~2.5k tokensUpdated 7 mo ago
    DevelopmentAuto-check passed

  • Sonarjs

    managedcode/dotnet-skills

    Use SonarJS-derived rules in .NET repositories that ship JavaScript or TypeScript frontends and need deeper bug-risk, code-smell, or cognitive-complexity checks than a minimal ESLint baseline.

    486 GitHub stars~1.6k tokensUpdated today
    DevelopmentAuto-check passed

  • Frontend Module Standards

    siteboon/claudecodeui

    Enforces one repository's React and TypeScript module layout for code under src/: source-root imports, feature barrels, deliberate exports and no deep imports.

    14k GitHub stars~2.6k tokensUpdated 2 days ago
    Frontend & DesignAuto-check passed

  • ccc Semantic Code Search

    cocoindex-io/cocoindex-code

    Semantic code search and index management with the ccc CLI: the agent initializes, indexes and queries the project by concept, filtering by language or path.

    2.7k GitHub stars~938 tokensUpdated today
    Agent WorkflowsAuto-check passed

More from steipete/agent-scripts

All 45 skills in this repo

  • Mac Fleet Maintenance

    steipete/agent-scripts

    Inventories and maintains a fleet of Macs from a desired-state file: package updates, repo and Xcode sync, and disk, backup and security health reports.

    7.3k GitHub stars~4.8k tokensUpdated 2 days ago
    Auto-check passed

  • Agent Transcript for PRs

    steipete/agent-scripts

    Finds a coding agent's session log, trims and redacts it, and inserts it into a GitHub PR or issue only when the user has asked for a transcript.

    7.3k GitHub starsUsed in 1 repo~698 tokens
    Auto-check passed

  • Parallels macOS VM Lab

    steipete/agent-scripts

    Uses a clean Parallels macOS VM to test GUI automation, TCC permission prompts and screenshot tools like Peekaboo, verifying results from outside the guest.

    7.3k GitHub stars~1.8k tokensUpdated 2 days ago
    Auto-check passed

  • ClawSweeper Status

    steipete/agent-scripts

    Reports ClawSweeper's status with a bundled script: workflow health, active workers, queue health and recently merged, reviewed, commented and closed items.

    7.3k GitHub stars~972 tokensUpdated 2 days ago
    Auto-check passed

  • GitHub Project Triage

    steipete/agent-scripts

    Produces maintainer-facing triage cards for a project's GitHub issues and pull requests, each with its URL, risk, test state, blockers and a next action.

    7.3k GitHub stars~4k tokensUpdated 2 days ago
    Auto-check passed

  • Nano Banana Image Generation

    steipete/agent-scripts

    Generates and edits images with Google's Nano Banana 2 (Gemini 3.1 Flash Image) through a uv script, with a draft-then-final workflow and sizes from 512 to 4K.

    7.3k GitHub stars~1.4k tokensUpdated 2 days ago
    Auto-check passed

Works with

Categories

Questions about Project Structure Map

What does Project Structure Map do?

Compresses a TypeScript or Swift repository into one symbol-map text file sized for an LLM context window, for refactor planning and architecture recon. This skill squeezes a TypeScript or Swift repository into a single text file that fits in a model's context window, listing files, exported symbols, typed signatures and plugin boundaries.ts` does the work: for TypeScript it runs the compiler in parse-only mode without type-checking, and for Swift it uses a dependency-free scanner based on regexes and brace depth.

When should I use Project Structure Map?

Project Structure Map fits situations like: planning a refactor that touches many files in a TypeScript or Swift repo; hunting for duplicated helpers across a whole project; giving another agent a compact map of the full codebase; getting oriented in the architecture of an unfamiliar repository.

How do I install Project Structure Map in Claude Code?

Run `npx skills add steipete/agent-scripts --skill project-structure -a claude-code`. Or copy the skill folder (skills/project-structure in steipete/agent-scripts) into .claude/skills/project-structure in your project. Claude Code loads it when a task matches its description.

How do I install Project Structure Map in Codex?

Run `npx skills add steipete/agent-scripts --skill project-structure -a codex`. Or copy the skill folder (skills/project-structure in steipete/agent-scripts) into .agents/skills/project-structure in your project. Codex loads it when a task matches its description.

Can I use Project Structure Map in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add steipete/agent-scripts --skill project-structure -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/project-structure, .gemini/skills/project-structure, .github/skills/project-structure and .opencode/skills/project-structure in your project.

What does Project Structure Map need to run?

Going by SKILL.md and its folder, Project Structure Map needs Swift, TypeScript and JavaScript for the scripts in its folder and the command-line tools its instructions call (node and npx). Our summary lists: Node 23.6 or newer, or `npx tsx`; A TypeScript or Swift repository to map.

Does Project Structure Map access the network?

SKILL.md contains no URLs. Its commands use npx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Project Structure Map safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Project Structure Map use?

Project Structure Map is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Project Structure Map use?

About 1.9k tokens (SKILL.md is roughly 7.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Project Structure Map?

Skills that share tags, products or a category with Project Structure Map: Ripwire Code Navigation (redhat-et/ripwire, 2.4k stars), Swarm (cj-vana/claude-swarm, 117 stars), Typescript Best Practices (jwynia/agent-skills, 165 stars) and Sonarjs (managedcode/dotnet-skills, 486 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Project Structure Map?

steipete (a GitHub user) maintains it in steipete/agent-scripts, which has 7,259 GitHub stars. The repository holds 45 skills in this directory. The repository was last updated on October 4, 2026.

Source: steipete/agent-scripts on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.