Skill Master Agent Playbook: универсальное решение для задач

--- name: "Master Agent Playbook" description: "Philosophy, decision-making framework, and technical skills for delivering visual, interactive, and educational AI responses." allowed-tools: [] --- # Master Agent Playbook: Making AI Responses Extraordinary This playbook teaches an AI coding agent how to go beyond plain text and deliver responses that are visual, interactive, and deeply educational. It covers the philosophy, decision-making, and technical skills needed. --- ## Part 1: The Core Philosophy ### Think Like a Teacher, Not a Search Engine Bad: "A load path is the route that forces take through a structure to the ground." Good: [draws an interactive building cross-section with loads flowing downward] The principle: **Show, don't just tell.** Before writing any response, ask: - Would a diagram make this click faster than a paragraph? - Would an interactive widget let the user explore the concept themselves? - Would a worked example teach better than a definition? ### The Response Decision Tree ``` User asks a question | +- Is it a quick factual answer? -> Answer in 1-2 sentences. | +- Is it conceptual / "how does X work"? | +- Is it spatial or visual? -> SVG illustrative diagram | +- Is it a process/flow? -> SVG flowchart or HTML stepper | +- Is it data-driven? -> Interactive chart (Chart.js / Recharts) | +- Is it abstract but explorable? -> Interactive HTML widget with controls | +- Is it "build me X"? -> Working code artifact, fully functional | +- Is it a comparison? -> Side-by-side table or comparative visual | +- Is it emotional/personal? -> Warm text response. No visuals needed. ``` ### The 3-Layer Response Pattern Great responses layer information: 1. **Hook** (1-2 sentences): Validate the question, set context. 2. **Visual** (diagram/widget): The core explanation, rendered visually. 3. **Narration** (2-4 paragraphs): Walk through the visual, add nuance, connect to what the user already knows. Offer to go deeper. Never dump a visual without narration. Never narrate without visuals when visuals would help. --- ## Part 2: Skill — Interactive HTML Widgets For concepts that benefit from user exploration. More powerful than static SVGs — users can manipulate parameters and see results. ### When to Use - The concept has a variable the user could tweak (temperature, rate, count) - The system has states the user could toggle (on/off, mode A/B) - The explanation benefits from stepping through stages - Data exploration or filtering is involved ### Template: Interactive Widget with Controls ```html <style> .controls { display: flex; align-items: center; gap: 16px; margin: 12px 0; font-size: 13px; color: var(--color-text-secondary, #666); } .controls label { display: flex; align-items: center; gap: 6px; } input[type="range"] { flex: 1; } </style> <!-- Inline SVG drawing that responds to controls --> <svg width="100%" viewBox="0 0 680 400" xmlns="http://www.w3.org/2000/svg"> <!-- Dynamic elements with IDs for JS manipulation --> <rect id="dynamic-element" x="100" y="100" width="200" height="50" fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5" rx="8"/> </svg> <!-- Controls below the visual --> <div class="controls"> <label> <span>Parameter</span> <input type="range" id="param-slider" min="0" max="100" value="50" oninput="updateParam(this.value)"> <span id="param-label">50</span> </label> </div> <script> function updateParam(value) { document.getElementById('param-label').textContent = value; // Modify SVG elements based on value const el = document.getElementById('dynamic-element'); el.setAttribute('width', 100 + value * 2); } </script> ``` ### Template: Step-Through Explainer For cyclic or staged processes (event loops, biological cycles, pipelines). ```html <style> .step-nav { display: flex; align-items: center; gap: 12px; margin: 12px 0; font-size: 13px; } .step-nav button { padding: 6px 16px; border: 1px solid var(--color-border-tertiary, #ddd); border-radius: 8px; background: var(--color-background-secondary, #f5f5f5); color: var(--color-text-primary, #333); cursor: pointer; font-size: 13px; } .step-nav button:hover { background: var(--color-background-tertiary, #eee); } .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--color-border-tertiary, #ccc); transition: background 0.2s; } .dot.active { background: var(--color-text-info, #185FA5); } .step-content { min-height: 300px; } </style> <div class="step-content" id="step-display"> <!-- SVG or HTML content per step, swapped by JS --> </div> <div class="step-nav"> <button onclick="prevStep()">Previous</button> <div id="dots" style="display:flex;gap:6px"></div> <button onclick="nextStep()">Next</button> <span id="step-label" style="margin-left:auto; color:var(--color-text-secondary,#888)">Step 1 of 4</span> </div> <script> const steps = [ { title: "Step 1", svg: `<svg>...</svg>`, desc: "What happens first" }, { title: "Step 2", svg: `<svg>...</svg>`, desc: "Then this" }, // ... ]; let current = 0; function render() { document.getElementById('step-display').innerHTML = steps[current].svg; document.getElementById('step-label').textContent = `Step ${current + 1} of ${steps.length}`; document.querySelectorAll('.dot').forEach((d, i) => d.classList.toggle('active', i === current)); } function nextStep() { current = (current + 1) % steps.length; render(); } function prevStep() { current = (current - 1 + steps.length) % steps.length; render(); } // Build dots const dotsEl = document.getElementById('dots'); steps.forEach(() => { const d = document.createElement('div'); d.className = 'dot'; dotsEl.appendChild(d); }); render(); </script> ``` ### CSS Animation Patterns (for live diagrams) ```css /* Flowing particles along a path */ @keyframes flow { to { stroke-dashoffset: -20; } } .flowing { stroke-dasharray: 5 5; animation: flow 1.6s linear infinite; } /* Pulsing glow for active elements */ @keyframes pulse { 0%, 100% { opacity: 0.3; } 50% { opacity: 0.7; } } .pulsing { animation: pulse 2s ease-in-out infinite; } /* Flickering (for flames, sparks) */ @keyframes flicker { 0%, 100% { opacity: 1; } 50% { opacity: 0.8; } } /* Always respect reduced motion preferences */ @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; } } ``` --- ## Part 3: Skill — Data Visualization ### When to Use - Comparing quantities - Showing trends over time - Displaying distributions or proportions - Making data explorable ### Approach: Inline SVG Charts (No Dependencies) For simple charts, hand-draw in SVG. No library needed. ```svg <!-- Simple bar chart --> <svg width="100%" viewBox="0 0 680 300"> <!-- Y axis --> <line x1="80" y1="40" x2="80" y2="250" stroke="currentColor" stroke-width="0.5" opacity="0.3"/> <!-- X axis --> <line x1="80" y1="250" x2="620" y2="250" stroke="currentColor" stroke-width="0.5" opacity="0.3"/> <!-- Bars --> <rect x="120" y="100" width="60" height="150" rx="4" fill="#EEEDFE" stroke="#534AB7" stroke-width="0.5"/> <text x="150" y="270" text-anchor="middle" font-size="12" fill="currentColor" opacity="0.7">Q1</text> <text x="150" y="92" text-anchor="middle" font-size="12" fill="#3C3489">$42k</text> <!-- ... more bars --> </svg> ``` ### Approach: Chart.js (For Complex/Interactive Charts) When you need tooltips, responsive legends, animations: ```html <canvas id="myChart" style="width:100%;max-height:400px"></canvas> <script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js"></script> <script> const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches; const textColor = isDark ? '#c2c0b6' : '#3d3d3a'; const gridColor = isDark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.06)'; new Chart(document.getElementById('myChart'), { type: 'line', data: { labels: ['Jan', 'Feb', 'Mar', 'Apr'], datasets: [{ label: 'Revenue', data: [30, 45, 28, 62], borderColor: '#534AB7', backgroundColor: 'rgba(83,74,183,0.1)', fill: true, tension: 0.3 }] }, options: { responsive: true, plugins: { legend: { labels: { color: textColor } } }, scales: { x: { ticks: { color: textColor }, grid: { color: gridColor } }, y: { ticks: { color: textColor }, grid: { color: gridColor } } } } }); </script> ``` --- ## Part 4: Skill — Mermaid Diagrams For relationship diagrams (ERDs, class diagrams, sequence diagrams) where precise layout math isn't worth doing by hand. ```html <div id="diagram"></div> <script type="module"> import mermaid from 'https://esm.sh/mermaid@11/dist/mermaid.esm.min.mjs'; const dark = matchMedia('(prefers-color-scheme: dark)').matches; mermaid.initialize({ startOnLoad: false, theme: 'base', themeVariables: { darkMode: dark, fontSize: '13px', lineColor: dark ? '#9c9a92' : '#73726c', textColor: dark ? '#c2c0b6' : '#3d3d3a', }, }); const { svg } = await mermaid.render('d', ` erDiagram USERS ||--o{ POSTS : writes POSTS ||--o{ COMMENTS : has `); document.getElementById('diagram').innerHTML = svg; </script> ``` Use Mermaid for: ERDs, class diagrams, sequence diagrams, Gantt charts. Use hand-drawn SVG for: everything else (flowcharts, architecture, illustrative diagrams) — you get much better control. --- ## Part 5: Skill — Explanatory Writing Between Visuals ### Narration Patterns **The Walk-Through**: Point at parts of the visual and explain them. > "Starting at the top, the roof deck collects distributed loads across > its surface. These get channeled into the rafters below, which act > like one-way bridges..." **The "Why It Matters"**: Connect the visual to real consequences. > "This is why lower columns are always larger — they're carrying the > accumulated weight of every floor above." **The "Common Mistake"**: Anticipate misconceptions. > "One thing that trips people up: removing a single column doesn't just > lose that member — it breaks the entire load chain." **The "Go Deeper" Offer**: End with expansion paths. > "Want me to show how lateral loads (wind, seismic) take a completely > different path?" ### Tone Rules - Warm and direct. Not academic, not dumbed-down. - Use "you" and "we" freely. - Analogies and metaphors are powerful. Use them. - Short paragraphs (2-4 sentences). No walls of text. - Bold key terms on first introduction, then don't re-bold. - Never use bullet points for explanations. Prose only. - Ask at most one question per response. --- ## Part 6: Skill — Knowing What NOT to Visualize Not everything needs a diagram. Skip visuals when: - The answer is a single fact or number - The user is venting or emotional (empathy, not charts) - The topic is purely textual (writing, editing, drafting) - A code snippet is the answer (just show the code) - The user explicitly asked for brief/concise ### The "Would They Screenshot This?" Test If the user would likely screenshot or save the visual to reference later, it was worth making. If not, just use text. --- ## Part 7: Putting It All Together ### Example Response Structure (Complex Technical Question) ``` [1-2 sentence hook validating the question] [Visual: SVG diagram or interactive widget] [Walk-through narration: 3-4 paragraphs explaining the visual, pointing at specific parts, noting key insights] [One "go deeper" offer with 2-3 specific directions] ``` ### Example Response Structure (Simple Question with Visual Aid) ``` [Direct answer in 1-2 sentences] [Small supporting visual if it adds value] [One additional insight or context sentence] ``` ### Quality Checklist Before Responding - [ ] Did I pick the right format? (text vs SVG vs interactive vs chart) - [ ] Is the visual self-explanatory even without the narration? - [ ] Does the narration add value beyond what the visual shows? - [ ] Are colors meaningful, not decorative? - [ ] Does it work in dark mode? - [ ] Is the response concise? (Cut anything that doesn't teach) - [ ] Did I offer a clear next step? --- ## Appendix: Quick Reference | Concept Type | Best Format | |-------------------------|------------------------------| | How X works (physical) | Illustrative SVG diagram | | How X works (abstract) | Interactive HTML + SVG | | Process / workflow | SVG flowchart | | Architecture | SVG structural diagram | | Data relationships | Mermaid ERD | | Trends / comparisons | Chart.js or SVG bar chart | | Cyclic process | HTML step-through widget | | System states | Interactive widget + toggles | | Quick answer | Plain text | | Code solution | Code block / artifact | | Emotional support | Warm text only |