map
/map
Scan project structure and generate ARCHITECTURE.md with a Mermaid module relationship diagram. Use when user says \"/map\".
- Author
- shenxingy ↗
- Repository
- clade ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Scan project structure and generate ARCHITECTURE.md with a Mermaid module relationship diagram. Use when user says \"/map\".
Original author description
Scan project structure and generate ARCHITECTURE.md with a Mermaid module relationship diagram. Use when user says \"/map\".
How it works
- Canonical Clade workflow
- Purpose
- Execution Steps
- Implementation Notes
- Success Criteria
- Completion Status
- Delivery completion
SKILL.md preview
---
name: map
description: "Scan project structure and generate ARCHITECTURE.md with a Mermaid module relationship diagram. Use when user says \"/map\"."
---
# Clade for Codex
This workflow runs **directly in Codex**. Do not launch the `claude` CLI or
delegate the workflow to Clade's MCP bridge.
Codex compatibility rules:
- Plugin skills are namespaced. Invoke this workflow explicitly as
`$clade:map`; a bare `$name` does not select the installed Clade plugin.
- Read the nearest `AGENTS.md` files for repository instructions. If a project
has only `CLAUDE.md`, treat it as legacy project guidance and read it too.
- Store new Clade working state under `.clade/` (or `~/.clade/` for personal
state). Existing legacy Claude state may be read for migration, but do not
create new vendor-specific state.
- A `/skill-name` reference means the corresponding Codex
`$clade:skill-name` plugin skill, or the same workflow invoked naturally when
explicit skill invocation is not available.
- Use Codex web, file, shell, image, and subagent capabilities when the source
workflow names a vendor-specific tool. If a capability is unavailable, use
the documented fallback instead of spawning another agent CLI.
- Paths such as `<plugin-root>/...` are relative to the installed Clade plugin
containing this `SKILL.md`; resolve that root before invoking a helper.
## Canonical Clade workflow
# /map Skill: Generate Project Architecture Diagram
## Purpose
Automatically scan the project structure and generate `ARCHITECTURE.md` with a module relationship diagram using Mermaid.
## Execution Steps
1. **Read existing ARCHITECTURE.md**
- If `ARCHITECTURE.md` exists at the project root, read it first
- This helps preserve any existing documentation and allows you to update rather than overwrite
2. **Scan project structure**
- Use Glob to find major directories: `find . -maxdepth 2 -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*'`
- For each top-level directory (src/, lib/, app/, components/, etc.), identify:
- What it contains (modules, libraries, features)
- Its primary responsibility
- Key files or sub-modules within it
3. **Identify modules and dependencies**
- Scan key files with Grep/Read to understand module structure
- Map logical dependencies (imports, API calls, shared state)
- Identify which modules depend on which others
- Look for: package.json, setup.py, .go files, main entry points
4. **Generate Mermaid diagram**
- Create a `graph TD` (top-down) Mermaid diagram showing:
- Each major module as a node (use clear, short names)
- Arrows showing dependencies: `ModuleA --> ModuleB` means ModuleA imports/uses ModuleB
- Group related modules if they form a subsystem
- Keep the diagram readable (max ~10-15 nodes for clarity)
- Example structure:
```
graph TD
API["API Layer"]
DB["Database"]
Auth["Authentication"]
UI["Frontend"]
UI --> API
API --> Auth
API --> DB
Auth --> DB
```
5. **Write ARCHITECTURE.md**
- Create or update `ARCHITECTURE.md` at the project root
- **Structure**:
```markdown
# Project Architecture
## Overview
[1-2 sentence high-level description of what the project does]
## Directory Structure
### src/
[Description of what this directory contains]
- Key files: file1.ts, file2.ts
### lib/
[Description]
- Key files: ...
[... repeat for each top-level directory ...]
## Module Relationships
```mermaid
[Your generated Mermaid graph]
```
## Key Components
### Module Name
- **Location**: src/module/
- **Responsibility**: What this module does
- **Exports**: Key functions/classes
- **Depends on**: Other modules it uses
[... repeat for each major module ...]
## Data Flow
[Optional: describe how data flows through the system, if applicable]
```
- Keep descriptions concise (1-3 lines per section)
- Focus on "why" not "what" — what problem does each module solve?
6. **Report success**
- Tell the user: "Updated ARCHITECTURE.md"
- If the diagram is complex, add a note about what the diagram shows
## Implementation Notes
- **Diagram scope**: Show the 5-10 most important modules, not every single file
- **Avoid noise**: Don't include vendored code (node_modules, venv, .git)
- **Update strategy**: If ARCHITECTURE.md exists, preserve existing descriptions and update the diagram + file list
- **Language**: Use English for all documentation
- **Mermaid syntax**: Use valid Mermaid graph TD syntax; test the diagram visually if possible
## Success Criteria
✓ ARCHITECTURE.md exists at project root
✓ Diagram renders without syntax errors
✓ All major modules are represented
✓ Dependencies are correctly shown
✓ Descriptions are clear and concise
---
## Completion Status
- ✅ **DONE** — task completed successfully
- ⚠ **DONE_WITH_CONCERNS** — completed but with caveats to note
- ❌ **BLOCKED** — cannot proceed; write details to `.clade/blockers.md`
- ❓ **NEEDS_CONTEXT** — missing information; use AskUserQuestion
**3-strike rule:** If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.
## Delivery completion
If this workflow changes files or external state:
- Inspect the real final state before responding, including `git status` for a
repository task.
- Never report `DONE` while task-owned changes are uncommitted. Use or continue
`$clade:delivery` and create a repository-compliant checkpoint or preserve
the work when committing is unavailable.
- When the user request or trusted repository policy makes publication,
deployment, or live verification part of the task, do not silently downgrade
the result to local-only work.
- If a required delivery transition lacks authority, credentials, a destination,
or reachable external state, report `BLOCKED` or `NEEDS_CONTEXT` rather than
appending a "not committed/pushed/deployed" caveat after `DONE`.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · shenxingy/clade | 100 | MIT |
| milansolutionsai-ops/claude-code-map-skill | 100 | MIT |
| acaprino/alfio-claude-plugins | 100 | MIT |
| DaBaoAgent/Auto-Video | 100 | MIT |
| bgmacris/quimera-ai | 100 | MIT |
| fabiozagaria/spring-security-advisor | 100 | MIT |
| htlin222/dotfiles | 100 | MIT |
| roma8ok/getmapstack | 100 | MIT |
| smg-project/smg-dev-guide | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version ef1f5f8e7330 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100architecture
Living Architecture Map — auto-generate Mermaid diagrams of your codebase. Use when user wants to visualize architecture, understand code structure, generate diagrams, or document system design. - 100architecture-diagram
Generates a Mermaid architecture diagram showing high-level component relationships. Use when visualizing how plugins or modules fit together. - 100atlas-map
Map the system architecture — read the codebase, identify services and connections, output a C4-level architecture map as Mermaid diagrams with component descriptions. Use when asked to "map the architecture", "system diagram", "how does this work", or "architecture overview". - 95ui-adapter
Scan project widget/component structure and generate UI mapping file. Use when the user says "scan UI", "map components", "adapt UI", "detect widgets", or needs to understand the project's UI inventory before planning a feature. - 100c4-architecture
Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include… - 100architecture-scan
Scan a large codebase and produce a detailed, evidence-backed architecture document with diagrams. Use when asked to map, audit, document or explain a project's architecture.