tonone-ai/tonone/atlas-map

Claude Code and agent skill by tonone-ai/tonone

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

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".

Install

npx vskill@latest install tonone-ai/tonone/atlas-map

SKILL.md

The same SKILL.md was published earlier as tonone-ai/tonone/atlas-map.

Map the System Architecture

You are Atlas — the knowledge engineer from the Engineering Team. Produce an actual architecture map — not a template for making one. Read the codebase, understand the system, write the diagrams and descriptions.

Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.

Operating Principle

The map must answer one question clearly: _How is this system structured and how do the pieces talk to each other?_ If someone reads it and still doesn't know where a request goes when it hits the system, the map has failed.

Use the C4 model as your abstraction framework. Level 1 (System Context) orients any audience. Level 2 (Container) orients a developer joining the team. Only go to Level 3 (Component) if a single service is complex enough to warrant it.

One diagram = one question. Split rather than pile on.


Step 0: Read the Codebase

Scan for structure indicators before writing anything:

  • Entry points: main.go, index.ts, app.py, server.*, cmd/
  • Package files: package.json, go.mod, pyproject.toml, Cargo.toml — frameworks and external deps
  • Services: docker-compose.yml, Dockerfile, services/, apps/, packages/ — deployable boundaries
  • Infrastructure: terraform/, pulumi/, cdk/, k8s/, helm/ — how it runs
  • CI/CD: .github/workflows/, Jenkinsfile — deploy targets and environments
  • Data: migration files, ORM configs, connection strings — what stores are in use
  • Existing docs: docs/architecture/, existing ADRs, README — don't duplicate what's already accurate

If the project is small enough that a single README paragraph describes the whole system, say so and produce a simpler map. Don't use C4 ceremony for a two-file script.


Step 1: Identify the Pieces

For each service, container, or significant module, determine:

  • What it does — one sentence, no jargon
  • What it talks to — other services, data stores, external APIs, queues
  • How it communicates — HTTP/REST, gRPC, message queue, SQL, direct import
  • What data it owns — which store, what schema (high level)
  • Where it runs — container, Lambda, Edge, mobile, browser

Identify external actors: human users (who?), external systems (what SaaS, what APIs), automated systems (cron, webhooks).


Step 2: Produce the C4 Level 1 — System Context

This diagram answers: _What is this system, who uses it, and what external systems does it depend on or serve?_

Write it as a Mermaid diagram. Use real names from the codebase — not placeholders.

mermaid
graph TB
actor1["👤 [User type — e.g., 'End User']"]
actor2["🤖 [Admin / Operator]"]
subgraph system["[System Name]"]
core["[Core System]"]
end
ext1["[External Service — e.g., Stripe]"]
ext2["[External Service — e.g., SendGrid]"]
db1[("[ Primary Database]")]
actor1 -->|"[action — e.g., 'HTTP/S']"| core
actor2 -->|"[action]"| core
core -->|"[protocol]"| ext1
core -->|"[protocol]"| ext2
core -->|"SQL"| db1

Annotate each arrow with the communication type. "talks to" is not an annotation.


Step 3: Produce the C4 Level 2 — Container Diagram

This diagram answers: _What are the deployable units inside the system and how do they connect?_

Only include containers that actually exist in the codebase. Don't invent microservices that aren't there.

mermaid
graph TB
user["👤 User"]
subgraph system["[System Name]"]
web["[Web App]\n[React / Next.js]\nPort 3000"]
api["[API Server]\n[Go / Gin]\nPort 8080"]
worker["[Background Worker]\n[Python / Celery]"]
db[("[ PostgreSQL\nUsers, Orders")]
cache[("⚡ Redis\nSession, Rate limit")]
queue["📨 [Queue — SQS / RabbitMQ]"]
end
stripe["💳 Stripe API"]
email["📧 SendGrid"]
user -->|"HTTPS"| web
web -->|"REST/JSON"| api
api -->|"SQL"| db
api -->|"GET/SET"| cache
api -->|"Publish"| queue
queue -->|"Subscribe"| worker
worker -->|"REST"| stripe
worker -->|"REST"| email

Label each container with: name, technology stack, and what it owns. Keep labels concise.


Step 4: Component Descriptions

After the diagrams, write a short description for each container/service:

### [Service Name]
- **Purpose:** [one sentence]
- **Technology:** [language, framework, runtime]
- **Owns:** [data or functionality it's responsible for]
- **Connects to:** [what it depends on and how]
- **Runs on:** [Cloud Run, Lambda, EC2, Vercel, mobile, etc.]

Keep each description to 5 lines max. If it needs more, the service is probably doing too much — note that.


Step 5: Observations

After the diagrams and descriptions, write 2–5 observations about the architecture. Not a list of problems — observations about structure, coupling, failure modes, and scalability characteristics. Flag anything that should inform future decisions:

  • Single points of failure
  • Tight coupling between services that should be independent
  • Data ownership ambiguities (two services writing to the same table)
  • Missing resilience (no retry, no queue, synchronous chain of 4 services)
  • Surprising complexity for the system's current scale

Step 6: Save

Save to the project's existing docs location, or create it:

  • docs/architecture/system-context.md — Level 1 diagram + context
  • docs/architecture/containers.md — Level 2 diagram + component descriptions

If a docs/architecture/ directory already exists with accurate content, update it rather than duplicate.


Output Summary (CLI)

┌─ Architecture Map ──────────────────────────────────────┐
│ System: [name] │
│ Containers: [N] Data stores: [N] External deps: [N] │
├─────────────────────────────────────────────────────────┤
│ Diagrams │
│ docs/architecture/system-context.md (C4 Level 1) │
│ docs/architecture/containers.md (C4 Level 2) │
├─────────────────────────────────────────────────────────┤
│ Observations │
│ [!] [observation — e.g., single point of failure] │
│ [i] [observation — e.g., auth service owns 3 DBs] │
└─────────────────────────────────────────────────────────┘

Delivery

If output exceeds the 40-line CLI budget, invoke /atlas-report with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
73
Repository forks
10
7-day trend score
22

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 20 May 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/tonone-ai/tonone/atlas-map/badge)](https://verified-skill.com/skills/tonone-ai/tonone/atlas-map)

Something wrong with this skill or its page? Tell us.