Engineer Design Diagram
Generates production-grade engineering design diagrams as single-file HTML with inline SVG, grounded in real repository topology. Credit: design palette + arrow-masking pattern inspired by Cocoon AI's architecture-diagram-generator (MIT). See THIRDPARTYLICENSES.md.
Overview
Most diagramming tools produce pretty pictures disconnected from reality. This skill does the opposite: it reads the actual repo (package manifests, docker-compose, k8s, terraform, import graph) and emits a diagram that reflects the real system. It also knows how the system changed — PR-diff mode highlights structural deltas, trace mode turns a stack/log into a sequence diagram, and drift mode detects when the architecture has wandered from a stored fingerprint.
Four modes share a common pipeline (DCI grounding → node/edge graph → template fill → fingerprint write). Output is a single self-contained HTML file that opens in any browser, plus a Mermaid text block for copy-paste into docs. Dark theme with semantic OKLCH color coding by component role. Accessible by default (ARIA, </code>/<code><desc></code>, reduced-motion, keyboard navigation).</p>
<h2>Layout Philosophy — pick the shape before you draw</h2>
<p>Dense technical systems want to render <strong>wide</strong>. This is how Anthropic docs, Linear docs, and Vercel architecture pages present multi-component systems: a sticky left rail for context (nav, invariants, legend) and a generous main column for the diagram itself. Mimic that pattern when your content is dense, and use the simpler single-SVG hero when it isn't.</p>
<p>Two supported output shapes, one decision up front:</p>
<table><thead><tr>
<th>Shape</th>
<th>Use when</th>
<th>Template</th>
</tr></thead><tbody>
<tr>
<td><strong>Single-SVG hero</strong> (classic)</td>
<td>≤8 nodes, one-screen takeaway, no sub-grouping, no accompanying explanation needed</td>
<td><code>templates/base.html</code></td>
</tr>
<tr>
<td><strong>Docs-layout page</strong> (widescreen)</td>
<td>≥8 nodes, multiple planes/groupings/sub-blocks, want invariants + detail cards + legend alongside the diagram</td>
<td><code>templates/docs-layout.html</code></td>
</tr>
</tbody></table>
<p><strong>Widescreen-first for docs-layout.</strong> Target <code>min-width: 1024px</code>; do <em>not</em> add mobile breakpoints for docs-layout output — it's architecture documentation, not a landing page. The diagram needs horizontal breathing room. On narrow viewports the diagram stage scrolls horizontally inside its card while the sidebar stays visible.</p>
<p><strong>Hybrid rendering</strong> in docs-layout mode: HTML/CSS for all node cards (easier to maintain, free hover states, content edits don't trigger collision math), SVG overlay positioned absolutely <em>over</em> the node grid for arro</div>
</div>
</div>
</div>
</div>
<!-- 9. Usage / How It Works (from README) -->
<div class="section readme-section" data-astro-cid-vaomz7ca>
<h2 data-astro-cid-vaomz7ca>How It Works</h2>
<div class="readme-content" data-astro-cid-vaomz7ca><pre data-lang="bash"><code>
/design:generate # diagram from current repo
/design:diff PR-123 # diff a specific PR
/design:trace ./crash.log # sequence diagram from a stack trace
/design:watch # check for drift since last fingerprint
</code></pre>
<p>Or invoke the skill directly with natural language: <em>"draw the architecture for this repo"</em>, <em>"diagram this PR"</em>, <em>"engineer design diagram"</em>.</p></div>
</div>
<!-- 10. Use Cases (from README) -->
<div class="section readme-section" data-astro-cid-vaomz7ca>
<h2 data-astro-cid-vaomz7ca>Use Cases</h2>
<div class="readme-content" data-astro-cid-vaomz7ca><p><code>examples/aws-serverless.html</code>, <code>examples/microservices.html</code>, <code>examples/tiny-monorepo/expected-architecture.html</code> — reference outputs you can open directly to see what the skill produces.</p></div>
</div>
<!-- 11. FAQ (from README troubleshooting) -->
<!-- 12. Bottom CTA -->
<section class="detail-cta" data-astro-cid-qcigfm7x>
<h2 class="detail-cta__headline" data-astro-cid-qcigfm7x>Ready to use engineer-design-diagram?</h2>
<div class="detail-cta__actions" data-astro-cid-qcigfm7x>
<button class="detail-cta__primary" data-copy-install="/plugin install engineer-design-diagram@claude-code-plugins-plus" data-astro-cid-qcigfm7x>
<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true" data-astro-cid-qcigfm7x>
<rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" stroke-width="1.5" data-astro-cid-qcigfm7x></rect>
<path d="M3 11V3a1 1 0 011-1h8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" data-astro-cid-qcigfm7x></path>
</svg>
<span class="detail-cta__btn-text" data-astro-cid-qcigfm7x>Copy Install Command</span>
</button>
</div>
</section>
<script type="module">document.querySelectorAll("[data-copy-install]").forEach(t=>{t.addEventListener("click",async()=>{const a=t.dataset.copyInstall||"";await navigator.clipboard.writeText(a);const e=t.querySelector(".detail-cta__btn-text");if(e){const o=e.textContent;e.textContent="Copied!",t.classList.add("copied"),window.trackEvent&&window.trackEvent("install_copied",{plugin_name:a.split(" ").pop()||"",source:"detail_cta"}),setTimeout(()=>{e.textContent=o,t.classList.remove("copied")},2e3)}})});</script>
<!-- 13. Related Plugins -->
<div class="section" data-astro-cid-vaomz7ca>
<h2 data-astro-cid-vaomz7ca>Related Plugins</h2>
<div class="related-plugins" data-astro-cid-vaomz7ca>
<a href="/plugins/ansible-playbook-creator" class="related-card" data-astro-cid-vaomz7ca>
<h3 data-astro-cid-vaomz7ca>ansible-playbook-creator</h3>
<p data-astro-cid-vaomz7ca>Create Ansible playbooks for configuration management</p>
</a><a href="/plugins/auto-scaling-configurator" class="related-card" data-astro-cid-vaomz7ca>
<h3 data-astro-cid-vaomz7ca>auto-scaling-configurator</h3>
<p data-astro-cid-vaomz7ca>Configure auto-scaling policies for applications and infrastructure</p>
</a><a href="/plugins/backup-strategy-implementor" class="related-card" data-astro-cid-vaomz7ca>
<h3 data-astro-cid-vaomz7ca>backup-strategy-implementor</h3>
<p data-astro-cid-vaomz7ca>Implement backup strategies for databases and applications</p>
</a><a href="/plugins/ci-cd-pipeline-builder" class="related-card" data-astro-cid-vaomz7ca>
<h3 data-astro-cid-vaomz7ca>ci-cd-pipeline-builder</h3>
<p data-astro-cid-vaomz7ca>Build CI/CD pipelines for GitHub Actions, GitLab CI, Jenkins, and more</p>
</a><a href="/plugins/cloud-cost-optimizer" class="related-card" data-astro-cid-vaomz7ca>
<h3 data-astro-cid-vaomz7ca>cloud-cost-optimizer</h3>
<p data-astro-cid-vaomz7ca>Optimize cloud costs and generate cost reports</p>
</a><a href="/plugins/compliance-checker" class="related-card" data-astro-cid-vaomz7ca>
<h3 data-astro-cid-vaomz7ca>compliance-checker</h3>
<p data-astro-cid-vaomz7ca>Check infrastructure compliance (SOC2, HIPAA, PCI-DSS)</p>
</a>
</div>
</div>
<!-- 14. Tags Footer -->
<div class="tags-footer" data-astro-cid-vaomz7ca>
<span class="tags-label" data-astro-cid-vaomz7ca>Tags</span>
<div class="tags-list" data-astro-cid-vaomz7ca>
<span class="tag" data-astro-cid-vaomz7ca>architecture</span><span class="tag" data-astro-cid-vaomz7ca>diagram</span><span class="tag" data-astro-cid-vaomz7ca>visualization</span><span class="tag" data-astro-cid-vaomz7ca>svg</span><span class="tag" data-astro-cid-vaomz7ca>html</span><span class="tag" data-astro-cid-vaomz7ca>pr-review</span><span class="tag" data-astro-cid-vaomz7ca>drift-detection</span><span class="tag" data-astro-cid-vaomz7ca>sequence-diagram</span><span class="tag" data-astro-cid-vaomz7ca>engineering-design</span><span class="tag" data-astro-cid-vaomz7ca>documentation</span><span class="tag" data-astro-cid-vaomz7ca>onboarding</span>
</div>
</div>
</div>
</div>
<script type="module">const c=document.getElementById("copy-btn"),a=document.querySelector(".install-command");c&&a&&c.addEventListener("click",async()=>{const t=a.textContent||"";await navigator.clipboard.writeText(t),c.textContent="Copied!",c.classList.add("copied"),window.trackEvent&&window.trackEvent("install_copied",{plugin_name:t.split(" ").pop()||"",source:"plugin_detail"}),setTimeout(()=>{c.textContent="Copy",c.classList.remove("copied")},2e3)});document.querySelectorAll(".gist-toggle").forEach(t=>{t.addEventListener("click",()=>{const e=t.closest(".gist-card");if(!e)return;const n=e.querySelector(".gist-content"),o=t.querySelector(".toggle-icon");if(!n||!o)return;const l=n.style.display!=="none";n.style.display=l?"none":"block",o.style.transform=l?"":"rotate(90deg)",e.classList.toggle("expanded",!l)})});document.querySelectorAll(".gist-header").forEach(t=>{t.addEventListener("click",e=>{const n=e.target;if(n.closest("a")||n.closest(".gist-toggle"))return;const o=t.querySelector(".gist-toggle");o&&o.click()})});const s=document.getElementById("expand-all-btn");if(s){let t=!1;s.addEventListener("click",()=>{t=!t,s.textContent=t?"Collapse All":"Expand All",document.querySelectorAll(".gist-card").forEach(e=>{const n=e.querySelector(".gist-content"),o=e.querySelector(".toggle-icon");!n||!o||(n.style.display=t?"block":"none",o.style.transform=t?"rotate(90deg)":"",e.classList.toggle("expanded",t))})})}document.querySelectorAll("[data-expandable]").forEach(t=>{const e=t.querySelector(".readme-content");if(!e||e.scrollHeight<=400)return;e.classList.add("truncated");const n=document.createElement("button");n.className="show-more-btn",n.textContent="Show more",n.addEventListener("click",()=>{const o=e.classList.contains("truncated");e.classList.toggle("truncated",!o),n.textContent=o?"Show less":"Show more"}),e.insertAdjacentElement("afterend",n)});</script>
</main>
<!-- Footer -->
<footer data-astro-cid-37fxchfa>
<div class="footer-inner" data-astro-cid-37fxchfa>
<div class="footer-signup-row" data-astro-cid-37fxchfa>
<h4 data-astro-cid-37fxchfa>Stay in the Loop</h4>
<form data-signup-form="footer" class="footer-signup-form" data-astro-cid-37fxchfa>
<input type="email" name="email" placeholder="you@example.com" required data-astro-cid-37fxchfa>
<input type="text" name="website" tabindex="-1" autocomplete="off" aria-hidden="true" style="position:absolute;left:-9999px;opacity:0;height:0;width:0;" data-astro-cid-37fxchfa>
<button type="submit" data-astro-cid-37fxchfa>Subscribe</button>
</form>
<p class="footer-form-note" data-astro-cid-37fxchfa>No spam. Unsubscribe anytime.</p>
</div>
<div class="footer-columns" data-astro-cid-37fxchfa>
<div class="footer-col" data-astro-cid-37fxchfa>
<h5 data-astro-cid-37fxchfa>Product</h5>
<ul data-astro-cid-37fxchfa>
<li data-astro-cid-37fxchfa><a href="/explore" data-astro-cid-37fxchfa>Explore</a></li>
<li data-astro-cid-37fxchfa><a href="/skills" data-astro-cid-37fxchfa>Skills</a></li>
<li data-astro-cid-37fxchfa><a href="/cowork" data-astro-cid-37fxchfa>Cowork</a></li>
<li data-astro-cid-37fxchfa><a href="/compare-marketplaces" data-astro-cid-37fxchfa>Compare</a></li>
<li data-astro-cid-37fxchfa><a href="/tools" data-astro-cid-37fxchfa>Tools</a></li>
</ul>
</div>
<div class="footer-col" data-astro-cid-37fxchfa>
<h5 data-astro-cid-37fxchfa>Resources</h5>
<ul data-astro-cid-37fxchfa>
<li data-astro-cid-37fxchfa><a href="/docs" data-astro-cid-37fxchfa>Docs</a></li>
<li data-astro-cid-37fxchfa><a href="/changelog" data-astro-cid-37fxchfa>Changelog</a></li>
<li data-astro-cid-37fxchfa><a href="/collections" data-astro-cid-37fxchfa>Collections</a></li>
<li data-astro-cid-37fxchfa><a href="/playbooks" data-astro-cid-37fxchfa>Playbooks</a></li>
<li data-astro-cid-37fxchfa><a href="/research" data-astro-cid-37fxchfa>Research</a></li>
<li data-astro-cid-37fxchfa><a href="/learning" data-astro-cid-37fxchfa>Learning</a></li>
</ul>
</div>
<div class="footer-col" data-astro-cid-37fxchfa>
<h5 data-astro-cid-37fxchfa>Company</h5>
<ul data-astro-cid-37fxchfa>
<li data-astro-cid-37fxchfa><a href="/community" data-astro-cid-37fxchfa>Community</a></li>
<li data-astro-cid-37fxchfa><a href="/community#hall-of-fame" data-astro-cid-37fxchfa>Hall of Fame</a></li>
<li data-astro-cid-37fxchfa><a href="https://github.com/jeremylongshore/claude-code-plugins" target="_blank" data-astro-cid-37fxchfa>GitHub</a></li>
</ul>
</div>
<div class="footer-col" data-astro-cid-37fxchfa>
<h5 data-astro-cid-37fxchfa>Legal</h5>
<ul data-astro-cid-37fxchfa>
<li data-astro-cid-37fxchfa><a href="/privacy" data-astro-cid-37fxchfa>Privacy</a></li>
<li data-astro-cid-37fxchfa><a href="/terms" data-astro-cid-37fxchfa>Terms</a></li>
<li data-astro-cid-37fxchfa><a href="/acceptable-use" data-astro-cid-37fxchfa>Acceptable Use</a></li>
</ul>
</div>
</div>
<div class="footer-bottom" data-astro-cid-37fxchfa>
<p class="footer-blurb" data-astro-cid-37fxchfa>Tons of Skills by <a href="https://intentsolutions.io" target="_blank" data-astro-cid-37fxchfa>Intent Solutions</a>. Marine. Citadel Grad. 20 years ops → self-taught dev → AI architect.</p>
<p class="footer-copyright" data-astro-cid-37fxchfa>© 2026 Tons of Skills | <a href="https://intentsolutions.io" target="_blank" data-astro-cid-37fxchfa>Intent Solutions</a></p>
</div>
</div>
</footer>
<!-- Light theme global overrides (must be unscoped to target body/nav/footer) -->
<!-- Email Signup Form Handler -->
<script type="module">
import { getFunctions, httpsCallable } from 'https://www.gstatic.com/firebasejs/11.8.1/firebase-functions.js';
import { getApp } from 'https://www.gstatic.com/firebasejs/11.8.1/firebase-app.js';
function initSignupForms() {
var functions;
try {
functions = getFunctions(getApp());
} catch (e) {
console.warn('[TonsOfSkills] Firebase not initialized — signup forms disabled:', e.message);
document.querySelectorAll('[data-signup-form] button').forEach(function(btn) {
btn.disabled = true;
btn.textContent = 'Unavailable';
btn.style.opacity = '0.5';
btn.style.cursor = 'not-allowed';
});
return;
}
var subscribeEmail = httpsCallable(functions, 'subscribeEmail');
document.querySelectorAll('[data-signup-form]').forEach(function(form) {
form.addEventListener('submit', async function(e) {
e.preventDefault();
var input = form.querySelector('input[type="email"]');
const honeypot = form.querySelector('input[name="website"]');
var btn = form.querySelector('button');
var originalText = btn.textContent;
btn.textContent = 'Subscribing...';
btn.disabled = true;
try {
var result = await subscribeEmail({
email: input.value,
source: form.dataset.signupForm,
website: honeypot ? honeypot.value : ''
});
if (result.data.status === 'already_subscribed') {
btn.textContent = 'Already on it!';
} else {
btn.textContent = 'You\'re in!';
}
btn.style.opacity = '0.85';
input.value = '';
if (window.logFirebaseEvent) {
window.logFirebaseEvent('email_signup', { source: form.dataset.signupForm });
}
} catch (err) {
if (err.code === 'invalid-argument' && (!input.value || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input.value))) {
btn.textContent = 'Invalid Email';
} else {
btn.textContent = 'Something went wrong';
}
setTimeout(function() { btn.textContent = originalText; btn.disabled = false; btn.style.opacity = ''; }, 3000);
}
});
});
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initSignupForms);
} else {
initSignupForms();
}
</script>
<!-- Nomination Form Handler -->
<script type="module">
import { getFunctions, httpsCallable } from 'https://www.gstatic.com/firebasejs/11.8.1/firebase-functions.js';
import { getApp } from 'https://www.gstatic.com/firebasejs/11.8.1/firebase-app.js';
function initNominationForms() {
var functions;
try { functions = getFunctions(getApp()); }
catch (e) {
document.querySelectorAll('[data-nomination-form] button').forEach(function(btn) {
btn.disabled = true;
btn.textContent = 'Unavailable';
btn.style.opacity = '0.5';
btn.style.cursor = 'not-allowed';
});
return;
}
var submitNomination = httpsCallable(functions, 'submitNomination');
var ghPattern = /^https:\/\/github\.com\/[^\/]+\/[^\/\s]+/;
document.querySelectorAll('[data-nomination-form]').forEach(function(form) {
form.addEventListener('submit', async function(e) {
e.preventDefault();
var input = form.querySelector('input[name="repo"]');
var honeypot = form.querySelector('input[name="website"]');
var btn = form.querySelector('button');
var originalText = btn.textContent;
if (!ghPattern.test(input.value)) {
btn.textContent = 'GitHub URLs only';
setTimeout(function() { btn.textContent = originalText; btn.disabled = false; }, 3000);
return;
}
btn.textContent = 'Submitting...';
btn.disabled = true;
try {
var result = await submitNomination({
repoUrl: input.value,
source: form.dataset.nominationForm,
website: honeypot ? honeypot.value : ''
});
btn.textContent = result.data.status === 'already_nominated'
? 'Already submitted!' : 'Submitted!';
btn.style.opacity = '0.85';
input.value = '';
if (window.logFirebaseEvent) {
window.logFirebaseEvent('killer_skill_nomination', {
source: form.dataset.nominationForm
});
}
} catch (err) {
btn.textContent = 'Something went wrong';
setTimeout(function() {
btn.textContent = originalText; btn.disabled = false; btn.style.opacity = '';
}, 3000);
}
});
});
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initNominationForms);
} else { initNominationForms(); }
</script>
<!-- Theme Toggle Script -->
<script>
document.addEventListener('DOMContentLoaded', function() {
var themeToggle = document.querySelector('.theme-toggle');
if (themeToggle) {
themeToggle.addEventListener('click', function() {
var current = document.documentElement.getAttribute('data-theme') || 'dark';
var next = current === 'dark' ? 'light' : 'dark';
document.documentElement.setAttribute('data-theme', next);
localStorage.setItem('theme', next);
var meta = document.querySelector('meta[name="theme-color"]');
if (meta) meta.setAttribute('content', next === 'dark' ? '#1a1816' : '#f5f3f0');
});
}
window.matchMedia('(prefers-color-scheme: light)').addEventListener('change', function(e) {
if (!localStorage.getItem('theme')) {
document.documentElement.setAttribute('data-theme', e.matches ? 'light' : 'dark');
}
});
});
</script>
<!-- Nav Scroll State -->
<script>
(function() {
var nav = document.querySelector('nav');
if (!nav) return;
function onScroll() {
if (window.scrollY > 20) {
nav.classList.add('scrolled');
} else {
nav.classList.remove('scrolled');
}
}
window.addEventListener('scroll', onScroll, { passive: true });
onScroll();
})();
</script>
<!-- Mobile Menu Script -->
<script>
document.addEventListener('DOMContentLoaded', function() {
var menuToggle = document.querySelector('.mobile-menu-toggle');
var navLinks = document.querySelector('.nav-links');
var menuIcon = document.querySelector('.menu-icon');
var closeIcon = document.querySelector('.close-icon');
if (menuToggle && navLinks) {
menuToggle.addEventListener('click', function() {
navLinks.classList.toggle('active');
document.body.classList.toggle('menu-open');
if (navLinks.classList.contains('active')) {
menuIcon.style.display = 'none';
closeIcon.style.display = 'block';
} else {
menuIcon.style.display = 'block';
closeIcon.style.display = 'none';
}
});
navLinks.querySelectorAll('a').forEach(function(link) {
link.addEventListener('click', function() {
navLinks.classList.remove('active');
document.body.classList.remove('menu-open');
menuIcon.style.display = 'block';
closeIcon.style.display = 'none';
});
});
document.addEventListener('click', function(e) {
if (navLinks.classList.contains('active') &&
!navLinks.contains(e.target) &&
!menuToggle.contains(e.target)) {
navLinks.classList.remove('active');
document.body.classList.remove('menu-open');
menuIcon.style.display = 'block';
closeIcon.style.display = 'none';
}
});
}
// Track outbound link clicks (nav + footer)
document.querySelectorAll('nav a[target="_blank"], footer a[target="_blank"]').forEach(function(link) {
link.addEventListener('click', function() {
if (window.trackEvent) {
window.trackEvent('outbound_click', {
url: link.href,
link_text: link.textContent.trim()
});
}
});
});
});
</script>
</body>
</html>