Skip to content
Skills Library
Programming · Building & coding

map

/map

Scan project structure and generate ARCHITECTURE.md with a Mermaid module relationship diagram. Use when user says \"/map\".

Repository
clade ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

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

  1. Canonical Clade workflow
  2. Purpose
  3. Execution Steps
  4. Implementation Notes
  5. Success Criteria
  6. Completion Status
  7. Delivery completion
Original SKILL.md headings · 161 lines, 836 words
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

RepositoryScoreLicence
This page · shenxingy/clade100MIT
milansolutionsai-ops/claude-code-map-skill100MIT
acaprino/alfio-claude-plugins100MIT
DaBaoAgent/Auto-Video100MIT
bgmacris/quimera-ai100MIT
fabiozagaria/spring-security-advisor100MIT
htlin222/dotfiles100MIT
roma8ok/getmapstack100MIT
smg-project/smg-dev-guide100Apache-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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.