# Mermaid Architect: Umiejętność diagramowania i dokumentacji > Generuj kompleksowe diagramy Mermaid i dokumenty projektowe z inteligentną orkiestracją, konwersją kodu na diagramy i narzędziami Python. Zacznij tworzyć szczegółową dokumentację techniczną w kilka sekund. - Canonical: https://nanoskill.ai/pl/skills/mermaid-agent-skill - Markdown: https://nanoskill.ai/pl/skills/mermaid-agent-skill.md - Author: SpillwaveSolutions - Published: 2026-05-26T01:25:42.765Z - Updated: 2026-07-19T03:48:37.206Z - Language: pl - Source type: github - Popularity signal: 66 ## Sources - https://github.com/spillwavesolutions/design-doc-mermaid ## Install ```shell npx skills add https://github.com/spillwavesolutions/design-doc-mermaid ``` ## About Umiejętność Mermaid Architect umożliwia programistom, architektom i redaktorom technicznym skuteczne tworzenie i zarządzanie kompleksowymi diagramami Mermaid oraz dokumentami projektowymi. Dzięki inteligentnej orkiestracji i ładowaniu przewodników na żądanie, ta umiejętność usprawnia wizualizację złożonych systemów, przepływów pracy i struktur kodu. Pomaga użytkownikom generować dokładne i atrakcyjne wizualnie diagramy, zapewniając jasną komunikację i aktualną dokumentację. Ta potężna umiejętność Claude Code oferuje zaawansowane funkcje, takie jak generowanie diagramów z kodu, umożliwiając wyodrębnianie architektonicznych wniosków bezpośrednio z aplikacji Spring Boot lub FastAPI. Zawiera również bogaty zestaw narzędzi Pythona do wyodrębniania, weryfikacji i konwertowania diagramów Mermaid na formaty obrazów, co ułatwia integrację z istniejącymi przepływami pracy dokumentacyjnej i narzędziami takimi jak Confluence. Hierarchiczny system zapewnia efektywne wykorzystanie tokenów i szybki czas odpowiedzi, oferując płynne doświadczenie. Niezależnie od tego, czy potrzebujesz udokumentować API, zwizualizować architekturę systemu czy zilustrować proces biznesowy, Mermaid Architect zapewnia narzędzia i szablony, które pomogą w realizacji zadania. Dzięki obsłudze różnych typów diagramów, semantycznych symboli Unicode i stylizacji o wysokim kontraście, Twoje diagramy będą zarówno informacyjne, jak i dostępne. Umiejętność oferuje również uporządkowaną ścieżkę nauki i przykłady, które pomogą użytkownikom szybko opanować tworzenie szczegółowej dokumentacji technicznej. ## Key features - **Inteligentne generowanie diagramów**: Twórz różne diagramy Mermaid, w tym diagramy aktywności, wdrożeniowe, architektury i sekwencji, dotyczące przepływów pracy, infrastruktury, komponentów systemu i przepływów API. - **Konwersja kodu na diagramy**: Automatycznie generuj diagramy z istniejących baz kodu (np. Spring Boot, FastAPI) lub plików konfiguracyjnych, aby wizualizować architekturę, wdrożenia i przepływy sekwencyjne. - **Kompleksowe tworzenie dokumentów projektowych**: Twórz kompletne dokumenty projektowe z osadzonymi diagramami Mermaid, korzystając z predefiniowanych szablonów dla architektury, API, funkcji, bazy danych i projektów systemowych. - **Semantyczne symbole Unicode i stylizacja o wysokim kontraście**: Zwiększ przejrzystość i dostępność diagramów dzięki ponad 100 znaczącym symbolom Unicode i schematom kolorów o wysokim kontraście, co poprawia czytelność. - **Narzędzia Python do zarządzania diagramami**: Korzystaj ze skryptów Python do wyodrębniania, sprawdzania i konwertowania diagramów Mermaid na obrazy PNG/SVG, z obsługą przetwarzania wsadowego i integracji z narzędziami takimi jak Confluence. ## Use cases - **Wizualizuj architekturę oprogramowania**: Deweloperzy i architekci mogą generować diagramy architektury i wdrożeń na podstawie kodu lub plików konfiguracyjnych, aby zrozumieć komponenty systemu i infrastrukturę. - **Dokumentuj przepływy API i przepływy pracy**: Pisarze techniczni i inżynierowie mogą tworzyć szczegółowe diagramy sekwencji i aktywności, aby zilustrować interakcje API, procesy biznesowe i ścieżki użytkowników. - **Zautomatyzuj tworzenie dokumentów projektowych**: Zespoły mogą szybko generować ustrukturyzowane dokumenty projektowe do różnych celów (API, system, funkcje) z automatycznie osadzonymi diagramami Mermaid, oszczędzając czas i zapewniając spójność. - **Utrzymuj aktualną dokumentację techniczną**: Zapewnij aktualność dokumentacji, generując diagramy bezpośrednio z kodu lub konfiguracji, i łatwo konwertuj je do formatów obrazów do udostępniania i współpracy. ## Result preview Zobacz diagramy Mermaid dotyczące systemu dla platformy dostawy jedzenia wygenerowane przez tę Umiejętność Agenta. ![mermaid-architect-demo1](https://file.nanoskill.ai/mermaid-architect-demo1.jpg) ![mermaid-architect-demo-2](https://file.nanoskill.ai/mermaid-architect-demo-2.jpg) ![mermaid-architect-demo-3](https://file.nanoskill.ai/mermaid-architect-demo-3.jpg) ## Result walkthrough ### Krok 1：Instalacja Dodaj umiejętność do swojego agenta. ![mermaid-architect-step-1](https://file.nanoskill.ai/mermaid-architect-step-1.jpg) ### Krok 2：Opisz proces Wprowadź przepływ pracy, system lub sekwencję, którą chcesz zwizualizować. ![mermaid-architect-step-2](https://file.nanoskill.ai/mermaid-architect-step-2.jpg) ### Krok 3：Przejrzyj wynik Otrzymaj diagramy Mermaid wygenerowane na podstawie Twojego opisu procesu. ![mermaid-architect-step-3](https://file.nanoskill.ai/mermaid-architect-step-3.jpg) ## Skill definition # Mermaid Architect - Kompleksowa Umiejętność Tworzenia Diagramów i Dokumentacji **Wersja 2.0** - Hierarchiczna architektura z inteligentną orkiestracją Potężna umiejętność Claude Code do tworzenia diagramów Mermaid i dokumentów projektowych przy użyciu ładowania przewodników na żądanie, generowania diagramów z kodu oraz narzędzi w Pythonie. ## Instalacja ### Instalacja jednym kliknięciem przez Skilz Marketplace Zainstaluj tę umiejętność natychmiast z [Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/): ```bash skilz install SpillwaveSolutions_design-doc-mermaid/design-doc-mermaid ``` ### Instalacja ręczna Sklonuj bezpośrednio do katalogu umiejętności Claude Code: ```bash # Przejdź do katalogu umiejętności cd ~/.claude/skills # Sklonuj repozytorium git clone https://github.com/SpillwaveSolutions/design-doc-mermaid.git ``` ### Weryfikacja instalacji Po instalacji sprawdź, czy umiejętność jest dostępna: ```bash # Wyświetl zainstalowane umiejętności ls ~/.claude/skills/design-doc-mermaid # Lub zapytaj Claude Code # "Wyświetl moje zainstalowane umiejętności" ``` ## Co robi ta umiejętność **Inteligentne generowanie diagramów:** - Diagramy aktywności (przepływy pracy, procesy, logika biznesowa) - Diagramy wdrożeniowe (infrastruktura chmurowa, K8s, serverless) - Diagramy architektury (komponenty systemu, mikroserwisy) - Diagramy sekwencji (przepływy API, interakcje serwisów) - Kompletne dokumenty projektowe z osadzonymi diagramami **Konwersja kodu na diagram:** - Wyodrębnianie architektury z aplikacji Spring Boot - Generowanie diagramów wdrożeniowych z plików konfiguracyjnych - Tworzenie diagramów sekwencji z wywołań metod - Dokumentowanie potoków ETL i przepływów danych **Zarządzanie diagramami:** - Wyodrębnianie diagramów Mermaid z plików Markdown - Walidacja składni diagramów za pomocą mermaid-cli - Konwersja diagramów do obrazów PNG/SVG - Przetwarzanie wsadowe całych katalogów ## Szybki start ### Tworzenie diagramu aktywności ``` Użytkownik: "Utwórz diagram aktywności dla rejestracji użytkownika z weryfikacją e-mail" ``` Umiejętność: 1. Załaduje `references/guides/diagrams/activity-diagrams.md` 2. Użyje szablonu wzorca rejestracji 3. Doda symbole Unicode (🔐 dla bezpieczeństwa, 📧 dla e-maila, ✅ dla sukcesu) 4. Zastosuje stylistykę wysokiego kontrastu 5. Wygeneruje kompletny diagram Mermaid ### Generowanie z kodu ``` Użytkownik: "Oto mój plik application.yml z Spring Boot - wygeneruj diagram wdrożeniowy" ``` Umiejętność: 1. Przeanalizuje konfigurację (źródło danych, cache, bezpieczeństwo) 2. Załaduje `references/guides/diagrams/deployment-diagrams.md` 3. Załaduje `examples/spring-boot/README.md` 4. Zmapuje konfigurację na zasoby chmurowe 5. Wygeneruje diagram wdrożeniowy ze specyfikacjami zasobów ### Tworzenie dokumentu projektowego ``` Użytkownik: "Utwórz dokument projektowy API dla API kontaktów" ``` Umiejętność: 1. Załaduje `assets/api-design-template.md` 2. Załaduje odpowiednie przewodniki po diagramach (sekwencji, ER, architektury) 3. Wygeneruje kompletny dokument z osadzonymi diagramami 4. Zapisze do `docs/design/api-contacts-v1-2025-01-13.md` ## Struktura ### Organizacja hierarchiczna ``` mermaid-architect/ ├── SKILL.md # Główny orkiestrator z drzewem decyzyjnym ├── README.md # Ten plik ├── CLAUDE.md # Instrukcje Claude Code │ ├── references/ # Materiały referencyjne │ ├── mermaid-diagram-guide.md # Stary ogólny przewodnik │ └── guides/ # Specjalistyczne przewodniki (ładowane na żądanie) │ ├── diagrams/ │ │ ├── activity-diagrams.md # ✅ Ukończone │ │ ├── deployment-diagrams.md # ✅ Ukończone │ │ ├── architecture-diagrams.md # ✅ Ukończone │ │ └── sequence-diagrams.md # ✅ Ukończone │ ├── code-to-diagram/ │ │ └── README.md # ✅ Ukończone (główny przewodnik) │ ├── unicode-symbols/ │ │ └── guide.md # ✅ Ukończone (100+ symboli) │ └── troubleshooting.md # ✅ Ukończone (28 typowych błędów) │ ├── scripts/ # Narzędzia w Pythonie │ ├── extract_mermaid.py # ✅ Wyodrębnianie i walidacja diagramów │ └── mermaid_to_image.py # ✅ Konwersja do PNG/SVG │ ├── examples/ # Wzorce specyficzne dla języka │ ├── spring-boot/ # ✅ Ukończone │ ├── fastapi/ # ✅ Ukończone │ ├── react/ # ✅ Ukończone │ ├── python-etl/ # ✅ Ukończone │ ├── node-webapp/ # ✅ Ukończone │ └── java-webapp/ # ✅ Ukończone │ └── assets/ # Szablony dokumentów projektowych ├── architecture-design-template.md ├── api-design-template.md ├── feature-design-template.md ├── database-design-template.md └── system-design-template.md ``` ## Kluczowe cechy ### 1. Semantyczne symbole Unicode Każdy diagram używa znaczących symboli Unicode: ```mermaid graph TB User[👤 Klient] --> Gateway[🌐 API Gateway] Gateway --> Auth[🔐 Serwis Auth] Gateway --> API[⚙️ Serwis API] API --> DB[(💾 Baza danych)] API --> Cache[(⚡ Redis)] API --> Queue[📬 Kolejka wiadomości] Queue --> Worker[⚙️ Pracownik tła] ``` **Kategorie symboli:** - Infrastruktura: ☁️ 🌐 🔌 📡 🗄️ - Compute: ⚙️ ⚡ 🔄 🚀 💨 - Dane: 💾 📦 📊 📈 🗃️ - Komunikacja: 📨 📬 📤 📥 🐰 - Bezpieczeństwo: 🔐 🔑 🛡️ 🚪 👤 - Monitorowanie: 📝 📊 🚨 ⚠️ ✅ ❌ ### 2. Styl wysoki kontrast Wszystkie diagramy używają dostępnych, wysoko kontrastowych kolorów - szczegóły w SKILL.md. ### 3. Narzędzia w Pythonie #### Wyodrębnianie diagramów ```bash # Lista wszystkich diagramów w pliku python scripts/extract_mermaid.py document.md --list-only # Wyodrębnij do osobnych plików .mmd python scripts/extract_mermaid.py document.md --output-dir diagrams/ # Zweryfikuj wszystkie diagramy python scripts/extract_mermaid.py document.md --validate # Zastąp diagramy odwołaniami do obrazów (dla Confluence) python scripts/extract_mermaid.py document.md --replace-with-images \ --image-format png --output-markdown output.md ``` #### Konwersja do obrazów ```bash # Pojedynczy plik python scripts/mermaid_to_image.py diagram.mmd output.png # Niestandardowy motyw i rozmiar python scripts/mermaid_to_image.py diagram.mmd output.svg \ --theme dark --background white --width 1200 # Przetwarzanie wsadowe katalogu python scripts/mermaid_to_image.py diagrams/ output/ \ --format png --recursive # Ze stdin echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png ``` ## Wymagania ### Do generowania diagramów - System umiejętności Claude Code (automatyczny) - Przewodniki i szablony (dołączone do umiejętności) ### Do walidacji i konwersji obrazów ```bash # Zainstaluj mermaid-cli globalnie npm install -g @mermaid-js/mermaid-cli # Sprawdź instalację mmdc --version ``` ### Dla skryptów w Pythonie - Python 3.7+ - Nie są wymagane dodatkowe pakiety (używa tylko stdlib) ## Ścieżka nauki ### Nowy w diagramach Mermaid? 1. **Zacznij od diagramów aktywności** - Przeczytaj `references/guides/diagrams/activity-diagrams.md` 2. **Poznaj symbole Unicode** - Przeczytaj `references/guides/unicode-symbols/guide.md` 3. **Spróbuj przykładu** - Użyj wzorców z `examples/spring-boot/` 4. **Zweryfikuj swoją pracę** - Uruchom `python scripts/extract_mermaid.py --validate` ### Potrzebujesz udokumentować istniejący kod? 1. **Zidentyfikuj framework** - Spring Boot, FastAPI, React itp. 2. **Załaduj przewodnik przykładowy** - Przeczytaj `examples/{twój-framework}/README.md` 3. **Dopasuj wzorce** - Znajdź podobne wzorce kodu w przykładach 4. **Generuj diagramy** - Użyj szablonów z przewodników 5. **Weryfikuj** - Użyj skryptów walidacyjnych ### Tworzenie dokumentów projektowych? 1. **Wybierz typ szablonu** - Architektura, API, Funkcja, Baza danych lub System 2. **Załaduj szablon** - Przeczytaj z `assets/{typ}-design-template.md` 3. **Wypełnij sekcje** - Zastąp placeholder'y rzeczywistą treścią 4. **Dodaj diagramy** - Załaduj przewodniki po diagramach według potrzeb dla każdej sekcji 5. **Użyj symboli** - Wzbogać symbolami Unicode w całym dokumencie 6. **Zapisz** - Umieść w `docs/design/` ze znacznikiem czasu ## Jak działa system hierarchiczny ### Tradycyjne podejście (nieefektywne) - Ładowanie całej dokumentacji umiejętności (~50KB) - AI przetwarza wszystkie szablony i przykłady - Wysokie zużycie tokenów - Wolny czas odpowiedzi ### Podejście hierarchiczne (efektywne) 1. **Użytkownik zgłasza żądanie** → AI analizuje intencję 2. **Aktywuje się drzewo decyzyjne** → Określa potrzebne przewodniki 3. **Ładuje tylko potrzebne** → Odczytywanie konkretnego przewodnika (~2-5KB) 4. **Generuje wynik** → Używa ukierunkowanych szablonów 5. **Efektywne tokenowo** → 10x mniej potrzebnego kontekstu ### Przykładowy przepływ **Użytkownik:** "Utwórz diagram wdrożeniowy dla mojej konfiguracji Docker Compose" **Drzewo decyzyjne:** ``` 1. Analiza: "diagram wdrożeniowy" + "Docker Compose" 2. Ustalenie: potrzebny deployment-diagrams.md 3. Załadowanie: references/guides/diagrams/deployment-diagrams.md (2 KB) 4. Znalezienie wzorca: szablon Docker Compose istnieje 5. Generowanie: Używanie szablonu + symboli Unicode 6. Wyjście: Kompletny diagram w <30 sekund ``` **Zużyte tokeny:** ~2 000 (vs ~10 000 przy tradycyjnym podejściu) ## Status ukończenia ✅ **Ukończone:** - Hierarchiczny orkiestrator z drzewem decyzyjnym - Przewodnik po diagramach aktywności z szablonami - Przewodnik po diagramach wdrożeniowych (AWS, GCP, K8s, serverless, Docker) - Przewodnik po symbolach Unicode (100+ symboli) - Skrypt wyodrębniania Mermaid z walidacją - Skrypt konwersji Mermaid na obraz - Przykłady konwersji kodu na diagram dla Spring Boot - Szablony dokumentów projektowych (5 typów) - System stylistyki wysokiego kontrastu 🚧 **W toku:** - Przykłady dla FastAPI - Przykłady architektury komponentów React - Przykłady potoków ETL w Pythonie 📋 **Planowane:** - Przewodnik po diagramach architektury - Przewodnik po diagramach sekwencji - Główny przewodnik konwersji kodu na diagram - Przykłady dla Node.js/Express - Przykłady dla aplikacji webowych w Javie ## Wkład Aby dodać nowy przewodnik typu diagramu: 1. Utwórz przewodnik w `references/guides/diagrams/{typ}-diagrams.md` 2. Dołącz: - Kiedy używać - Podstawowa składnia - Wspólne wzorce (3-5 szablonów) - Przykłady symboli Unicode - Najlepsze praktyki 3. Zaktualizuj drzewo decyzyjne w `SKILL.md` 4. Dodaj przykłady z mapowaniem kodu Aby dodać nowy przykład językowy: 1. Utwórz katalog w `examples/{framework}/` 2. Dodaj `README.md` z: - Przeglądem frameworka - Diagramem architektury ze struktury - Diagramem wdrożeniowym z konfiguracji - Diagramem sekwencji z kodu - Diagramem aktywności z logiki 3. Zaktualizuj tabelę konwersji kodu na diagram w `SKILL.md` ## Licencja Część Claude Code Skills - Licencja MIT ## Powiązane umiejętności - **confluence** - Przesyłanie diagramów do Confluence - **plantuml** - Alternatywny format diagramu ## Linki - [Repozytorium GitHub](https://github.com/SpillwaveSolutions/design-doc-mermaid) - [Wpis na Skilz Marketplace](https://skillzwave.ai/skill/SpillwaveSolutions__design-doc-mermaid__design-doc-mermaid__SKILL/) - [Oficjalna dokumentacja Mermaid](https://mermaid.js.org/) --- **Wersja:** 2.0.0 **Zaktualizowano:** 2025-01-13 **Utrzymywane przez:** SpillwaveSolutions ## FAQ ### Jakie rodzaje diagramów Mermaid może generować ten skill? Ten skill może generować diagramy aktywności, diagramy wdrożeniowe, diagramy architektury i diagramy sekwencji. Obsługuje wizualizację przepływów pracy, infrastruktury chmurowej, komponentów systemu i interakcji API. ### Jak działa konwersja kodu na diagramy? Ten skill analizuje Twój kod lub pliki konfiguracyjne (np. Spring Boot application.yml) i używa predefiniowanych wzorców i przewodników, aby automatycznie generować odpowiednie diagramy Mermaid, takie jak diagramy wdrożeniowe lub sekwencyjne. ### Czy mogę tworzyć pełne dokumenty projektowe za pomocą tego skilla? Tak, ten skill zawiera szablony różnych dokumentów projektowych (architektura, API, funkcje, baza danych, system). Może generować kompletne dokumenty z osadzonymi diagramami Mermaid na podstawie Twojego wkładu i wybranego szablonu. ### Jakie są korzyści hierarchicznego systemu generowania diagramów Mermaid? Hierarchiczny system skutecznie analizuje Twoje intencje i ładuje tylko niezbędne przewodniki i szablony (zazwyczaj 2-5 KB) zamiast całej dokumentacji skilla. To znacząco zmniejsza zużycie tokenów i przyspiesza czas odpowiedzi. ### Czy z tym skillem są dołączone jakieś narzędzia Pythonowe? Tak, ten skill udostępnia skrypty Python do wyodrębniania diagramów Mermaid z plików Markdown, sprawdzania ich składni i konwertowania ich do formatów obrazów PNG lub SVG. Te narzędzia obsługują również przetwarzanie wsadowe. ### Jakie są wymagania do korzystania z funkcji walidacji i konwersji obrazów? Aby skorzystać z walidacji diagramów i konwersji obrazów, musisz mieć globalnie zainstalowany \`mermaid-cli\` poprzez npm (\`npm install -g @mermaid-js/mermaid-cli\`). Skrypty w Pythonie wymagają Python 3.7+.