convez.ai
SkillDesign & UIIntermediário
lqdflying

Architect Library - Skill Excalidraw

lqdflying/architect-library

Gera diagramas Excalidraw profissionais via agentes de código

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill que capacita Claude Code e agentes de IA a gerar diagramas Excalidraw bonitos e práticos. Integra-se com Cursor, VS Code + GitHub Copilot e ferramentas de coding, oferecendo também suporte para manipulação de artefatos Office (Word, PowerPoint, PDF) e workflows de arquitetura.

Instalação

$npx convez-ai lqdflying/architect-library

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 dia
Versão
—
Issues abertas
0
Contribuidores
4

Casos de uso

  • Criar diagramas de arquitetura de API durante pair programming
  • Gerar visualizações de fluxo de dados em sessões de design
  • Documentar padrões arquiteturais em artefatos reutilizáveis

Veredito

Skill robusto e bem estruturado para agentes de código que precisam produzir diagramas visuais. Excelente integração com ecossistema Cursor/Copilot, mas requer setup inicial de dependências (Python 3.11+, Node.js, LibreOffice para PPT). Recomendado para times que querem diagramação automática em workflows de desenvolvimento.

README

A tradução para o português deste README ainda está na fila.

Architect Library

A skill library and custom agent library for Cursor and VS Code Copilot. Install once globally; use in any project.

Skills handle artifacts (Excalidraw, Word, PowerPoint, spreadsheets, PDFs) and architecture workflows (API design, deprecation/migration). Custom agents handle focused readonly tasks such as code review and security audit.

Compatible with Cursor, VS Code + GitHub Copilot, Claude Code, and OpenCode.

For coding agents:

Full install means instructions + runtimes: When an agent handles install library, it should install the runtime dependencies first, then copy skills and agents for the active editor. Manual installs should follow the same order below.

First-time preparation (one-time per machine)

Run these steps once on each computer (or CI image) where you want rendering, Office XML tools, or offline Excalidraw. You do not repeat them for every project—only copy the skill folders per project or globally (Installation).

Prerequisites

RequirementNeeded for
Python 3.11+Excalidraw renderer, Office toolkit (uv installs deps)
uvInstalled automatically by install_deps.sh if missing
Node.js + npmbash scripts/install_deps.sh node (or included in install_deps.sh all); offline Excalidraw vendor uses same npm bootstrap pattern
python-docxIncluded in bash scripts/install_deps.sh office — Word fallback when npm/docx unavailable
sudo (Linux only)Optional OS libraries for headless Chromium (install_deps.sh) and LibreOffice/Poppler (office-system)
LibreOffice + PopplerOptional for Word-only / XML tooling; required for every PowerPoint delivery (mandatory layout preview). Also needed for DOCX/PPTX→PDF and accept tracked changes. Install once: bash scripts/install_deps.sh office-system

Artifact capability without npm: Word new DOCX → python-docx; PowerPoint new deck → not supported (template/XML edit only). Run bash scripts/runtime_readiness.sh after install to see status.

All-in-one (recommended)

From the repository root (after git clone):

cd architect-library   # or your clone path
bash scripts/install_deps.sh              # Excalidraw + Office + PDF + Node/npm (docx, pptxgenjs)
bash scripts/install_deps.sh office-system   # add LibreOffice Impress + Poppler (PPT layout preview, XLSX recalc, accept changes)
bash scripts/install_library.sh all cursor   # or: all copilot — skills + agents for your editor

Is LibreOffice mandatory? Not for creating .docx or building .pptx source (Node/python). Yes for completing PowerPoint skill work—every deck must go through layout preview (thumbnail), which needs LibreOffice Impress + Poppler. Word-only tasks can skip office-system. Install: bash scripts/install_deps.sh office-system.

Install only one runtime:

bash scripts/install_deps.sh excalidraw
bash scripts/install_deps.sh office
bash scripts/install_deps.sh office-system
bash scripts/install_deps.sh pdf              # pypdf, pdfplumber, reportlab (pdf-document skill)

Excalidraw renderer (first-time)

Playwright + Chromium let the agent render .excalidraw files to PNG for visual QA. Included in bash scripts/install_deps.sh; to run alone:

cd skills/excalidraw-diagram/references
bash install_deps.sh

Manual equivalent:

cd skills/excalidraw-diagram/references
uv sync
uv run python -m playwright install chromium

Online (default): each render can load Excalidraw from esm.sh (network required).

Offline / firewalled (first-time, requires Node.js): build a local bundle once:

bash scripts/vendor_excalidraw.sh

Details: skills/excalidraw-diagram/README.md → Offline rendering.

Node.js (new DOCX / new PPTX decks)

Included in bash scripts/install_deps.sh (target all or node). Installs global docx and pptxgenjs under $HOME/.npm-global when Node is available.

bash scripts/install_deps.sh node   # re-run Node step only
bash scripts/runtime_readiness.sh   # summary: Node, npm globals, python-docx
source scripts/architect_env.sh     # manual agent shell: PATH + NODE_PATH for docx/pptxgenjs

install_node.sh writes ~/.config/architect-library/env.sh and adds a hook to ~/.bashrc so new login shells pick up ~/.npm-global/bin and NODE_PATH automatically.

Without npm: Word → bash scripts/install_deps.sh office (python-docx). PowerPoint → edit/populate templates only; no greenfield deck.

Optional for PPTX icon workflows (see skills/powerpoint-presentation/README.md):

npm install -g react-icons react react-dom sharp

PDF tools (first-time)

For the pdf-document skill (included in bash scripts/install_deps.sh all):

bash scripts/install_deps.sh pdf

Office tools (first-time)

Shared by Word, PowerPoint, and spreadsheet skills. Included in bash scripts/install_deps.sh; to run alone:

cd skills/_shared/office-tools
bash install_deps.sh
bash install_deps.sh --with-system   # LibreOffice + Poppler when needed

Verify:

cd skills/_shared/office-tools
uv run python3 office_tools.py --help

Quick start (every project)

After first-time preparation (skip if you only need agent instructions with no PNG/Office tooling):

  1. Clone (if you have not already)

    git clone https://github.com/lqdflying/architect-library.git
    cd architect-library
    
  2. Install library globally — skills and custom agents (pick your editor):

    bash scripts/install_library.sh all cursor    # Cursor
    bash scripts/install_library.sh all copilot   # VS Code Copilot
    

    AI agents working in this repo: see AGENTS.md. Full procedure: docs/AGENT-SKILL-INSTALL.md.

  3. Ask your agent (skills load from their descriptions—no slash command required):

    Create an Excalidraw diagram of our payment authorization flow.

See Installation for Copilot / Claude Code paths, or docs/AGENT-SKILL-INSTALL.md for the full agent install procedure.

Skills

SkillUse when
excalidraw-diagramCreate Excalidraw architecture diagrams, workflows, system maps, and concept visuals.
word-documentCreate or edit DOCX architecture documents, HLDs, LLDs, ADRs, design docs, requirements, comments, and tracked changes.
powerpoint-presentationCreate or edit PPTX decks; every delivery requires layout preview (slide images via LibreOffice + Poppler).
spreadsheet-documentCreate or edit .xlsx; formula recalc via office_tools.py recalc (LibreOffice).
pdf-documentRead, create, merge, split, and fill PDFs.
verification-before-completionFresh verification evidence before any completion or delivery claim.
api-and-interface-designDesign stable APIs and module boundaries — contract-first, error semantics, pagination, Hyrum's Law.
deprecation-and-migrationDeprecate and migrate systems safely — strangler pattern, migration guides, zero-usage removal.
_sharedShared principles and Office tooling for Word, PowerPoint, and spreadsheet skills. Must be a sibling of those skills.

Custom agents

AgentUse when
code-reviewRead-only review of PRs, diffs, or modules; five-axis review; MCP and web verification. Cursor: /code-review. Copilot: agents dropdown.
security-auditorRead-only security review — STRIDE, OWASP, LLM security, CVE checks. Cursor: /security-auditor. Copilot: agents dropdown.

Catalog: docs/AGENTS.md. Deep dive: docs/CODE-REVIEW-AGENT.md, docs/SECURITY-AUDITOR-AGENT.md.

Documentation map

Read thisWhen you need
AGENTS.mdAgent (Cursor + Copilot): install library contract, editor scope, anti-patterns
.cursor/Agent: Cursor project rules and config (tracked in git)
docs/MAINTAINING-SKILLS.mdMaintainer/agent: checklist when adding skills, steps, or dependencies
tmp/README.mdMaintainer: staging area for external ref skills/agents before absorption
.cursor/skills/absorb-reference-materials/SKILL.mdMaintainer: triage tmp/ ref material — ship, harden, or ignore (not in global install)
.cursor/skills/absorb-reference-materials/references/readme-after-absorb.mdMaintainer: README audit checklist after each absorb session
docs/AGENT-SKILL-INSTALL.mdAgent: install or refresh skills + custom agents (global)
docs/AGENTS.mdCustom agent catalog
docs/CODE-REVIEW-AGENT.mdcode-review agent usage
docs/SECURITY-AUDITOR-AGENT.mdsecurity-auditor agent usage
skills/api-and-interface-design/SKILL.mdAPI and interface design workflow
skills/deprecation-and-migration/SKILL.mdDeprecation and migration workflow
This README → How to useUsing installed skills in Cursor, Copilot, or Claude Code chat
skills/excalidraw-diagram/SKILL.mdDiagram design rules and agent workflow
skills/excalidraw-diagram/README.mdRender setup, offline bundle, PNG validation
skills/word-document/SKILL.mdDOCX agent workflow (new vs edit, comments, redlines)
skills/word-document/README.mdWord skill setup and pointers
skills/word-document/references/docx-guide.mddocx-js and XML editing patterns (explicit table theming)
skills/word-document/references/production-lessons.mdReal-delivery lessons: one table style path, parallel tables, TOC, Word verify
skills/word-document/references/python-docx-patterns.mdpython-docx: built-in Medium Shading 1 Accent 1 + tblHeader, or explicit fills
skills/powerpoint-presentation/SKILL.mdPPTX agent workflow
skills/powerpoint-presentation/README.mdPPT setup (including optional icon packages)
skills/powerpoint-presentation/references/pptx-guide.mdpptxgenjs and template editing
skills/powerpoint-presentation/references/layout-preview.mdPPTX layout preview images (grid + per-slide JPEGs)
skills/spreadsheet-document/SKILL.mdXLSX workflow and recalc
skills/pdf-document/SKILL.mdPDF workflows and form fill
skills/_shared/architecture-document-principles.mdShared structure for architecture docs and decks
skills/_shared/office-tools/README.mdFull office_tools.py command reference and validation checks

Repository layout

architect-library/
  README.md
  AGENTS.md                   # cross-editor agent guide (install library, scope law)
  tmp/                        # maintainer staging — external ref before absorption (see tmp/README.md)
  .cursor/
    rules/                    # maintainer rules (not installed globally)
    skills/
      absorb-reference-materials/   # maintainer skill — triage tmp/ ref (not in SKILL_BUNDLE)
  agents/                     # custom agent library (source)
    code-review/
    security-auditor/
  docs/
    AGENT-SKILL-INSTALL.md
    AGENTS.md
  scripts/
    install_library.sh        # skills + agents → global Cursor / Copilot
    install_deps.sh           # all | excalidraw | office | office-system | pdf
    vendor_excalidraw.sh
    vendor_excalidraw/
  skills/                     # skill library (source)
    excalidraw-diagram/
      SKILL.md
      README.md
      references/
        install_deps.sh
        render_excalidraw.py
        render_template.html
        vendor/                 # generated: excalidraw.bundle.mjs (gitignored, ~19MB)
    word-document/
      SKILL.md
      README.md
      references/docx-guide.md
    powerpoint-presentation/
      SKILL.md
      README.md
      references/pptx-guide.md
    spreadsheet-document/
      SKILL.md
      references/xlsx-guide.md
    pdf-document/
      SKILL.md
      references/pdf-guide.md
      scripts/
    verification-before-completion/
      SKILL.md
      README.md
    api-and-interface-design/
      SKILL.md
      README.md
    deprecation-and-migration/
      SKILL.md
      README.md
    _shared/
      architecture-document-principles.md
      office-tools/
        office_tools.py
        README.md
        install_deps.sh

Installation

Clone the repository:

git clone git@github.com:lqdflying/architect-library.git

If you prefer HTTPS:

git clone https://github.com/lqdflying/architect-library.git

Install library (recommended)

From the repo root — installs runtime dependencies, skills, and custom agents globally for your editor:

cd /path/to/architect-library
bash scripts/install_deps.sh
bash scripts/install_deps.sh office-system
bash scripts/install_library.sh all cursor    # Cursor
bash scripts/install_library.sh all copilot   # VS Code Copilot
bash scripts/install_library.sh all claude    # Claude Code

Install all editors at once (only if you use more than one):

bash scripts/install_library.sh

Partial installs (still editor-scoped):

bash scripts/install_library.sh skills cursor    # skills only, Cursor
bash scripts/install_library.sh agents copilot   # agents only, Copilot
bash scripts/install_library.sh all cursor project   # per-project copy

Global targets:

LibraryCursorCopilotClaude Code
Skills~/.cursor/skills/<name>/~/.copilot/skills/<name>/~/.claude/skills/<name>/
Agents~/.cursor/agents/<name>.md~/.copilot/agents/<name>.agent.md~/.claude/agents/<name>.md

Reload Cursor, VS Code, or Claude Code after installation. Skills appear as slash commands (/word-document, etc.). Custom agents appear in the agent picker (code-review, security-auditor, /code-review on Cursor).

See docs/AGENT-SKILL-INSTALL.md for verification steps and common mistakes.

Office workflows (manual)

Render a diagram to PNG (after first-time Excalidraw setup):

cd skills/excalidraw-diagram/references
uv run python render_excalidraw.py path/to/diagram.excalidraw

From skills/_shared/office-tools (or use paths from an installed skill folder—see each SKILL.md):

# Edit existing DOCX
uv run python3 office_tools.py unpack input.docx unpacked/
# … edit XML under unpacked/word/ …
uv run python3 office_tools.py pack unpacked/ output.docx --original input.docx

# Validate only
uv run python3 office_tools.py validate output.docx --auto-repair

# PPTX template QA
uv run python3 office_tools.py analyze template.pptx
uv run python3 office_tools.py thumbnail deck.pptx /tmp/preview --cols 4
uv run python3 office_tools.py thumbnail deck.pptx /tmp/preview --per-slide /tmp/slides --dpi 150 --no-grid

Full command list: skills/_shared/office-tools/README.md.

How to use

Skills are instructions for the coding agent, not apps you launch yourself. This section assumes skills are already installed. Not installed yet? See Quick start or docs/AGENT-SKILL-INSTALL.md.

Skill folderYou get
excalidraw-diagram.excalidraw JSON + optional PNG visual check
word-document.docx architecture documents (new or edited)
powerpoint-presentation.pptx decks (new or edited)
_sharedNot invoked directly — support files for Word/PPT tooling

Runtime setup (first-time preparation) is optional until you need PNG rendering, Office XML tools, or Node-based new DOCX/PPTX generation.

Cursor

  1. Reload Cursor — Developer: Reload Window, or quit and reopen Cursor, so it picks up any skill changes.

  2. New Agent chat — start a fresh chat in Agent mode (do not continue an old thread opened before install).

  3. Run a slash command — in the chat input, type / and pick the skill (clearest way to select which skill runs):

    Slash commandSkillTypical use
    /excalidraw-diagramExcalidrawDiagrams, workflows, system maps
    /word-documentWordHLD, LLD, ADR, DOCX edit/validate
    /powerpoint-presentationPowerPointExecutive decks, migration/roadmap slides

    _shared has no slash command — it is loaded automatically when Word or PowerPoint skills need Office tools.

  4. Add your request on the same line or next message — for example:

    /excalidraw-diagram Create a diagram of the payment authorization flow.
    
    /word-document Create an HLD with risks, assumptions, and decision records.
    
  5. Attach files when needed — for existing .docx / .pptx, @-mention or attach the file, then use the matching slash command:

    /word-document Add review comments on the risks section in the attached DOCX.
    

    You can also skip the slash command and ask in plain language; Cursor may still auto-select a skill from the description in each SKILL.md, but slash commands are more explicit.

Reload Cursor → new Agent chat → /skill-name + your task
       ↓
Agent follows that skill’s SKILL.md + references/
       ↓
Deliverable: .excalidraw / .docx / .pptx

VS Code GitHub Copilot

Requires GitHub Copilot and Agent Skills support in VS Code. Skills must already be under ~/.copilot/skills/ (global) or .github/skills/ (workspace)—see Installation → VS Code GitHub Copilot.

  1. Reload VS Code — Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → Developer: Reload Window (do this after every skill install or update).

  2. Open Copilot Chat — open the Chat view (Copilot icon in the Activity Bar, or GitHub Copilot: Open Chat from the Command Palette). Use Agent mode when your VS Code build offers it (skills apply to agent-style requests).

  3. Slash command usage — in the chat input, type /. VS Code shows available commands, including skills from installed SKILL.md files:

    Slash commandSkillTypical use
    /excalidraw-diagramExcalidrawDiagrams, workflows, system maps
    /word-documentWordHLD, LLD, ADR, DOCX edit/validate
    /powerpoint-presentationPowerPointExecutive decks, migration/roadmap slides

    Pick one command, then add your task on the same message (recommended):

    /excalidraw-diagram Create a diagram of the payment authorization flow.
    
    /word-document Create an HLD with risks, assumptions, and decision records.
    
    /powerpoint-presentation Create a 10-slide executive deck for the migration plan.
    

    Tips

    • If /excalidraw-diagram (or others) does not appear, confirm skills are in ~/.copilot/skills/ or .github/skills/, reload VS Code, and start a new chat.
    • _shared has no slash command; Word and PowerPoint skills use it automatically for Office tooling.
    • You can send the slash command first, then your detailed request in a follow-up message—one combined line is usually clearer.
  4. Attach workspace files — drag a .docx or .pptx into chat, use Add context / # file references (wording depends on VS Code version), then run the matching slash command:

    /word-document Validate the attached DOCX and list any structural issues.
    
    /powerpoint-presentation Analyze placeholder layout on the attached PPTX.
    
  5. Fallback — describe the task without / if you prefer; Copilot may still match a skill by description in SKILL.md. Slash commands are the clearest way to force the right skill.

Reload VS Code → Copilot Chat (Agent) → /skill-name + your task
       ↓
Copilot follows that skill’s SKILL.md + references/
       ↓
Deliverable: .excalidraw / .docx / .pptx

Claude Code / OpenCode

  1. Start a new session in the project where .claude/skills/ is populated (or restart the CLI).
  2. Describe the task — the agent loads skills from SKILL.md descriptions in that folder.

Example prompts (with slash commands)

Use the same lines in Cursor or VS Code Copilot Chat:

Excalidraw

/excalidraw-diagram Create a diagram showing the target-state payment authorization flow.

Word

/word-document Create a Word HLD for this event-driven architecture with risks, assumptions, and decision records.
/word-document Review the attached DOCX and add comments on the risks section.

PowerPoint

/powerpoint-presentation Create an executive architecture review deck for the migration plan.
/powerpoint-presentation Analyze the attached template’s placeholders and suggest a slide outline.

Attach .docx or .pptx files in chat when the task starts from an existing document.

Deeper workflows live in each skill’s SKILL.md (see Documentation map).

Customization

Validation

Smoke checks after first-time preparation:

cd skills/_shared/office-tools
uv run python3 office_tools.py --help
uv run python3 office_tools.py validate --help
uv run python3 office_tools.py analyze --help

cd ../../excalidraw-diagram/references
uv run python render_excalidraw.py --help

Troubleshooting

ProblemWhat to try
playwright: command not found during install_deps.shUse uv run python -m playwright install chromium (already what install_deps.sh runs after setup).
Excalidraw render times out / “Could not load library”Online: allow esm.sh. Offline: run bash scripts/vendor_excalidraw.sh, then retry.
process is not defined after vendoringRebuild the bundle: bash scripts/vendor_excalidraw.sh (includes browser shims).
Office commands fail with import errorsRun from skills/_shared/office-tools with uv run python3 office_tools.py … after bash install_deps.sh.
accept or thumbnail failsInstall system deps: bash scripts/install_deps.sh office-system. Required before finishing any PowerPoint task.
Agent delivered PPTX without layout reviewReload powerpoint-presentation skill; agent must run thumbnail and view images per layout-preview.md.
Word/PPT skill can’t find toolsEnsure _shared is copied next to word-document and powerpoint-presentation in your skills folder.
Pack skipped redline checksPass --original input.docx to pack; without it, only structural validation runs (a warning is printed).
Ver o original no GitHub

Bom para

Relacionados