Overview

Chapter 05: Claude Code & Antigravity CLI Workflows, Skills & Plugins

Playbook Track: 05 – Presentation Slides & Architecture Diagrams (Visual Systems, Claude Code & Antigravity Workflows)
Target Audience: Year 1 Computer Science & Software Engineering Students Core Tooling Stack: Claude Code (Claude 3.7 Sonnet CLI), Antigravity CLI (agy), Model Context Protocol (MCP), Marp CLI, Python 3.11+
Delivery Status: 🔍 Ready for Review (Tier 1 Markdown)

1. The Big Picture & Real-World Analogy

The Creative Director and the Autonomous Art Department

Imagine you are the technical lead of an autonomous software startup:

• The Chatbot Copy-Paste Struggle: You type prompts into a web browser chat window: "Can you design a slide about our backend?" The model prints some bullet points and ASCII boxes. You have to manually copy the text, open PowerPoint, drag rectangles, install fonts, export PDFs, and fix layout errors yourself. It takes hours of manual busywork!
• The Autonomous Agent Studio: You work with a terminal-native AI agent (Claude Code or Antigravity CLI). Guided by your repository style manual (CLAUDE.md), the agent has direct access to local development tools via the Model Context Protocol (MCP):
  1. It reads your real service code and benchmark logs directly from your repo.
  2. It generates Mermaid or D2 diagram code and compiles them to crisp SVGs using local command-line tools.
  3. It formats the presentation into Marp Markdown and compiles it directly into .pptx and .pdf files.
  4. It inspects the rendered slides for visual bugs and commits the result to Git!

Instead of acting as a passive conversational chatbot, the agent acts as an autonomous digital coworker with terminal and tool capabilities.

2. Engineering Jargon Demystifier Table

3. The 5-Minute Micro-Lab: The MCP Tool Dispatcher

Run this zero-dependency Python script to see how an agentic orchestrator registers and invokes specialized tools via a mock Model Context Protocol (MCP) bus:

"""
Micro-Lab: Model Context Protocol (MCP) Dispatcher
PB-05 Chapter 5 Micro-Lab (Zero External Dependencies)
"""

class MockMCPRegistry:
    def __init__(self):
        self.tools = {}

    def register_tool(self, name: str, handler):
        self.tools[name] = handler

    def call_tool(self, name: str, arguments: dict) -> dict:
        if name not in self.tools:
            return {"status": "ERROR", "message": f"Tool '{name}' not found in registry."}
        try:
            output = self.tools[name](**arguments)
            return {"status": "SUCCESS", "result": output}
        except Exception as e:
            return {"status": "ERROR", "message": str(e)}

# 1. Define local CLI rendering tools
def render_marp_slide(title: str, bullets: list) -> str:
    body = "\n".join([f"- {b}" for b in bullets])
    return f"---\n# {title}\n\n{body}\n---"

if __name__ == "__main__":
    registry = MockMCPRegistry()
    registry.register_tool("marp_compiler", render_marp_slide)

    # Agent issues structured tool call
    tool_call = {
        "tool": "marp_compiler",
        "arguments": {
            "title": "Cloud Architecture Overview",
            "bullets": ["Stateless Go API Gateway", "PostgreSQL Relational Ledger", "Redis 24h Idempotency Cache"]
        }
    }

    print("=== Agent Dispatching MCP Tool Call ===")
    response = registry.call_tool(tool_call["tool"], tool_call["arguments"])
    print(f"Tool Execution Status: [{response['status']}]")
    print("\nGenerated Slide Output:")
    print(response["result"])

4. Agentic Tooling Architecture & MCP Bus

In the era of autonomous engineering agents, software development is no longer confined to human typing in an IDE. Frontier developer agents like Claude Code (Anthropic's agentic command-line interface powered by Claude 3.7 Sonnet) and Antigravity CLI (agy, Google DeepMind's pair-programming agent powered by Gemini 2.5 Pro and Flash) possess the ability to read repositories, formulate plans, execute terminal commands, and create files autonomously.

However, when engineers attempt to use raw AI chat to produce presentation decks or architectural diagrams, they hit severe bottlenecks:

• The model outputs disconnected code snippets that the user must manually copy, paste, and render.
• The model lacks access to local rendering tools (like marp-cli, mmdc, or d2) and cannot verify whether its generated diagram compiles cleanly.
• The agent does not understand repo-specific design guidelines, resulting in off-brand color schemes and inconsistent layouts.

To unlock end-to-end autonomous presentation engineering, we integrate Custom Skills, Plugins, and the Model Context Protocol (MCP) into Claude Code and Antigravity CLI.

+---------------------------------------------------------------------------------------------------+
|                  AGENTIC PRESENTATION & DIAGRAM ORCHESTRATION PIPELINE                            |
+---------------------------------------------------------------------------------------------------+
|                                                                                                   |
|   +--------------------------+         +--------------------------+                               |
|   |  LOCAL GIT REPOSITORY    | ------> |  CLAUDE CODE / AGY       |                               |
|   |  - Go / Python Services  |         |  ORCHESTRATOR            |                               |
|   |  - OpenAPI Contracts     |         |  - Guided by CLAUDE.md   |                               |
|   |  - Benchmark Logs        |         |  - Dispatches Subagents  |                               |
|   +--------------------------+         +--------------------------+                               |
|                                                      |                                            |
|                                                      v Structured Tool Calls                      |
|   +-------------------------------------------------------------------------------------------+   |
|   |                         MODEL CONTEXT PROTOCOL (MCP) TOOL BUS                             |   |
|   |  - mcp-server-mermaid: In-memory SVG rendering and bounding box calculation               |   |
|   |  - mcp-server-drawio: Programmatic XML cell geometry injection                            |   |
|   |  - puppeteer-mcp: Headless Chromium screenshotting and vector PDF rendering               |   |
|   |  - marp-compiler-skill: Transforms slide JSON into 16:9 Marp decks                       |   |
|   +-------------------------------------------------------------------------------------------+   |
|                                                      |                                            |
|                                                      v Verified Visual Artifacts                  |
|   +--------------------------+         +--------------------------+                               |
|   |  VISUAL QA AUDITOR       | <------ |  DELIVERY DIRECTORY      |                               |
|   |  - WCAG Contrast Check   |         |  - architecture.svg      |                               |
|   |  - Collision Inspector   |         |  - executive_deck.pptx   |                               |
|   |  - Multimodal Vision Gate|         |  - presentation.pdf      |                               |
|   +--------------------------+         +--------------------------+                               |
|                                                                                                   |
+---------------------------------------------------------------------------------------------------+

1.1 Custom Skills in Claude Code & Antigravity CLI

Both modern CLI agent environments provide extensible plugin architectures:

1. Claude Code Architecture:
   • CLAUDE.md: Placed in the repository root, defining non-negotiable architectural invariants, design tokens, and slide rules that the model follows on every execution turn.
   • .claude/skills/: Reusable executable bash scripts or Python hooks invoked via slash commands (e.g., /generate-deck).
   • Headless Mode (claude -p "..."): Enables background CI/CD execution without human terminal interaction.
2. Antigravity CLI (agy) Architecture:
   • Custom Skills (SKILL.md): Located in /root/.gemini/config/skills/, declaring frontmatter metadata, tool permissions, and specialized system prompts.
   • Sidecars & Daemons: Background processes (like agentmemory and headless renderers) that persist state across sessions.
   • Tool Groups: Built-in declarative read, write, and bash command primitives allowing agents to inspect file systems and run compilation pipelines.

2. Agentic Skill Dispatch & MCP Tool State Machine

flowchart TD
    A["Developer Command: /generate-deck path='services/order'"] --> B["Orchestrator Agent Ingests Codebase & CLAUDE.md Rules"]
    B --> C["Subagent 1: Architecture Extractor parses AST & Routes"]
    C --> D["MCP Call: mermaid-server.render_mermaid(code)"]
    D --> E{"Render Success?"}
    E -- "Syntax Error" --> F["Self-Correction Loop: Fix Mermaid Delimiters"]
    F --> D
    E -- "SVG Validated" --> G["Subagent 2: Storyboard Drafter generates 6-Slide JSON"]
    G --> H["MCP Call: marp-server.compile_marp_deck(slides)"]
    H --> I["Headless Chromium Export: Render 16:9 PDF & PPTX"]
    I --> J["Final Visual QA & Delivery to Output Folder"]

    style A fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px;
    style D fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px;
    style H fill:#e8f5e9,stroke:#4caf50,stroke-width:2px;
    style J fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;

3. Gate 2: Mandatory Manual vs. Programmatic Contrasts

Using structured skills and MCP tools completely transforms how technical slides and diagrams are created.

4. Gate 3: Frontier AI Prompts & Skill Configurations

4.1 Production CLAUDE.md Configuration for Architecture Decks

# Repository Presentation & Architecture Invariants

Architecture Diagram Rules

• All architecture diagrams must be written in declarative Mermaid.js (flowchart TD or flowchart LR).
• Never exceed 12 nodes per diagram (Miller's Law).
• Every connection MUST state the protocol: -->|HTTPS REST| or -.->|Kafka Event|.
• When generating diagrams, call the mermaid-server:render_mermaid tool to verify SVG validity.

Slide Deck Rules

• All presentations must be formatted for 16:9 widescreen using Marp (theme: gaia).
• Enforce the 30-word limit per slide. Use 3-column metric cards for quantitative findings.
• When compiling decks, invoke the marp-server:compile_marp_deck tool.
• Output compiled artifacts to docs/architecture/decks/.

### 4.2 Antigravity Custom Skill Definition (`SKILL.md`)

```yaml
---
name: presentation-architect
description: Autonomously analyzes repository architecture and generates 16:9 Marp decks and Mermaid diagrams.
model: inherit
tool_groups:
  - read
  - write
  - bash
  - mcp:mermaid-server
  - mcp:marp-server
---

You are the Lead Presentation Architect in an autonomous AI engineering team.
Your responsibility:
1. Scan the repository to identify core microservices, datastores, and message brokers.
2. Formulate a canonical architecture graph and generate a valid Mermaid diagram.
3. Call `mermaid-server:render_mermaid` to verify that the diagram compiles with zero syntax errors.
4. Compose an executive 6-slide briefing deck adhering to the 16:9 widescreen format.
5. Compile the deck using `marp-server:compile_marp_deck` and deliver the `.md` and `.pdf` artifacts.

5. Gate 4: Quantitative Visual & Tooling Trade-Off Matrix

The following matrix compares developer agent execution modes for visual workflows:

6. Gate 5: The 10 Methodological Threats to Validity & Agentic Workflow Pitfalls

When orchestrating autonomous visual workflows via Claude Code and Antigravity, engineers must defend against ten technical pitfalls:

1. Context Bloat from Raw SVG Ingestion

• Threat: Passing an uncompressed 50KB SVG XML string back into the model context after every render, burning thousands of tokens and degrading reasoning performance.
• Defense: MCP tools must return compact metadata summaries (e.g., {"status": "COMPILED", "bytes": 48200, "bbox": [800, 600]}) and save the SVG to disk.

2. MCP Socket Hanging & Process Deadlocks

• Threat: A headless Chromium process in Puppeteer hangs on an unhandled JavaScript error, blocking the agent indefinitely.
• Defense: Equip all MCP tool calls with strict execution timeouts (e.g., $15$ seconds maximum) and process termination killswitches.

3. Shell Injection via Unsanitized Arguments

• Threat: The agent constructs a shell string like marp --pdf "$user_input" allowing arbitrary bash command execution.
• Defense: Execute compiler subprocesses using structured argument arrays (subprocess.run(["marp", "--pdf", path], shell=False)).

4. Non-Deterministic Layout Inversion

• Threat: Running the same workflow twice produces diagrams with inverted top-to-bottom rankings due to non-deterministic node traversal order.
• Defense: Sort all nodes and edges alphabetically before emitting DSL syntax.

5. Memory Leaks in Headless Puppeteer / Chromium Instances

• Threat: Generating 20 slides spawns 20 orphaned Chromium zombie processes that exhaust server RAM.
• Defense: Implement a singleton browser pool with automated process cleanup in finally: blocks.

6. Working Directory Resolution Failures

• Threat: The agent attempts to save an artifact to a relative path (./output.pdf) that resolves to the user's home directory instead of the repo root.
• Defense: Require all file-writing tools to resolve paths against the immutable repository workspace root.

7. Hallucinated MCP Tool Signatures

• Threat: The agent invents parameter names (e.g., compile_deck(presentation_code=...)) that do not exist in the MCP schema.
• Defense: Enforce strict JSON Schema Draft 2020-12 validation on all tool inputs prior to dispatch.

8. Recursive Subagent Loops

• Threat: Subagent A asks Subagent B to refine a slide, which asks Subagent A for clarification, entering an infinite token-burning conversation.
• Defense: Enforce a Maximum Delegation Depth ($D_{\max} \le 3$) and turn budgets.

9. Broken Git Tracking on Generated Binary Artifacts

• Threat: Committing massive 50MB .pdf and .pptx builds directly to Git history, bloating repository size.
• Defense: Commit only the declarative source (.md, .mmd, .d2) to Git; publish binaries as GitHub Release assets or CI artifacts.

10. Missing Cryptographic Build Checksums

• Threat: Stakeholders receive a presentation deck with no way to verify which Git commit or benchmark run generated it.
• Defense: Automatically stamp the slide deck footer with the Git commit hash and build timestamp.

11. Gate 6: Mandatory Hands-On Lab (Visual Engineering Challenge)

Objective

You will engineer an automated Agentic Diagram Workflow Orchestrator & MCP Skill Dispatcher in zero-dependency Python 3.11+. The engine will register MCP tools, validate tool schemas, simulate skill execution, and orchestrate an end-to-end autonomous pipeline from repository analysis to a validated 16:9 Marp presentation deck.

Experimental Protocol

1. MCP Tool & Skill Registration: Register simulated MCP tools (render_mermaid, compile_marp_deck) with parameter schemas, and register an autonomous presentation_architect skill.
2. Multi-Stage Workflow Execution: Ingest a mock repository summary, extract microservice entities, generate a Mermaid architecture graph, invoke the diagram rendering tool, and compile a 16:9 Marp deck.
3. Error Interception: Test that unregistered tool calls or invalid syntax parameters are intercepted cleanly with structured error messages.
4. Self-Test Verification: Confirm that all tool executions, state transitions, and artifact generations pass unit test assertions.

12. Gate 7: Mandatory Recommended Answer & Executable Solution

The following zero-dependency Python 3.11+ script provides the complete reference implementation of the Agentic Diagram Workflow Orchestrator & MCP Skill Dispatcher.

"""
test_ch05_diagram_engine.py
Zero-dependency Python 3.11+ engine for PB-05 Chapter 5:
AgenticDiagramWorkflowOrchestrator & MCPSkillDispatcher
"""

from dataclasses import dataclass, field
from enum import Enum
from typing import List, Dict, Any, Optional, Callable

class ToolType(str, Enum):
    MCP_TOOL = "MCP_TOOL"
    NATIVE_TOOL = "NATIVE_TOOL"
    SKILL = "SKILL"

@dataclass
class ToolExecutionResult:
    success: bool
    data: Any
    error_message: Optional[str] = None

@dataclass
class MCPToolDefinition:
    server_name: str
    tool_name: str
    description: str
    parameters_schema: Dict[str, Any]

@dataclass
class AgentSkillDefinition:
    skill_name: str
    description: str
    system_prompt: str
    required_mcp_tools: List[str]

class AgenticDiagramWorkflowOrchestrator:
    """Simulates Claude Code and Antigravity CLI skill dispatching and MCP tool execution."""

    def __init__(self):
        self.mcp_registry: Dict[str, MCPToolDefinition] = {}
        self.skill_registry: Dict[str, AgentSkillDefinition] = {}
        self.execution_history: List[Dict[str, Any]] = []

    def register_mcp_tool(self, tool: MCPToolDefinition):
        key = f"{tool.server_name}:{tool.tool_name}"
        self.mcp_registry[key] = tool

    def register_skill(self, skill: AgentSkillDefinition):
        self.skill_registry[skill.skill_name] = skill

    def execute_mcp_tool(self, server_name: str, tool_name: str, arguments: Dict[str, Any]) -> ToolExecutionResult:
        key = f"{server_name}:{tool_name}"
        if key not in self.mcp_registry:
            return ToolExecutionResult(success=False, data=None, error_message=f"MCP Tool '{key}' not registered.")

        # Simulate standard MCP tool behaviors
        if tool_name == "render_mermaid":
            code = arguments.get("mermaid_code", "")
            if not code or "flowchart" not in code:
                return ToolExecutionResult(success=False, data=None, error_message="Invalid Mermaid syntax.")
            svg_mock = f"<svg viewBox='0 0 800 600'><text>Rendered Diagram: {len(code)} bytes</text></svg>"
            res = {"svg_artifact": svg_mock, "status": "COMPILED"}
            self.execution_history.append({"tool": key, "args": arguments, "result": res})
            return ToolExecutionResult(success=True, data=res)

        elif tool_name == "compile_marp_deck":
            slides = arguments.get("slides", [])
            title = arguments.get("title", "Untitled Deck")
            deck_content = f"---\nmarp: true\ntheme: gaia\n---\n# {title}\n"
            for s in slides:
                deck_content += f"\n---\n## {s.get('title', 'Slide')}\n{s.get('body', '')}\n"
            res = {"marp_markdown": deck_content, "slide_count": len(slides) + 1}
            self.execution_history.append({"tool": key, "args": arguments, "result": res})
            return ToolExecutionResult(success=True, data=res)

        return ToolExecutionResult(success=False, data=None, error_message=f"Unhandled tool '{tool_name}'")

    def run_end_to_end_presentation_pipeline(self, raw_repo_summary: str) -> Dict[str, Any]:
        """
        Executes an autonomous 3-stage agentic pipeline:
        Stage 1: Codebase architecture extraction
        Stage 2: Mermaid diagram generation & MCP rendering
        Stage 3: 16:9 Marp presentation deck compilation
        """
        # Stage 1: Architecture extraction
        services = ["API Gateway (Envoy)", "Order Service (Go)", "Payment Service (Node.js)", "PostgreSQL DB"]
        edges = [("API Gateway", "Order Service", "HTTPS/REST"), ("Order Service", "Payment Service", "gRPC"), ("Order Service", "PostgreSQL DB", "SQL")]

        # Stage 2: Mermaid generation & MCP render
        mermaid_lines = ["flowchart TD"]
        for s in services:
            clean_id = s.split()[0].lower()
            mermaid_lines.append(f"    {clean_id}[\"{s}\"]")
        for src, tgt, proto in edges:
            src_id = src.split()[0].lower()
            tgt_id = tgt.split()[0].lower()
            mermaid_lines.append(f"    {src_id} -->|\"{proto}\"| {tgt_id}")
        mermaid_code = "\n".join(mermaid_lines)

        render_res = self.execute_mcp_tool("mermaid-server", "render_mermaid", {"mermaid_code": mermaid_code})
        if not render_res.success:
            raise RuntimeError(f"Diagram rendering failed: {render_res.error_message}")

        # Stage 3: Marp presentation compilation
        slides_payload = [
            {
                "title": "System Architecture Topology",
                "body": f"```mermaid\n{mermaid_code}\n```\n\n*Key Protocol*: High-speed gRPC inter-service communication."
            },
            {
                "title": "Production Deployment SLOs",
                "body": "- **P95 Latency**: < 45ms\n- **Availability**: 99.99%\n- **Throughput**: 12,000 rps"
            }
        ]

        deck_res = self.execute_mcp_tool("marp-server", "compile_marp_deck", {
            "title": "Autonomous Architecture Brief",
            "slides": slides_payload
        })
        if not deck_res.success:
            raise RuntimeError(f"Deck compilation failed: {deck_res.error_message}")

        return {
            "status": "COMPLETED",
            "mermaid_code": mermaid_code,
            "svg_artifact": render_res.data["svg_artifact"],
            "marp_deck": deck_res.data["marp_markdown"],
            "total_slides": deck_res.data["slide_count"]
        }


# ==========================================
# Self-Test Verification Suite
# ==========================================
if __name__ == "__main__":
    import unittest

    class TestAgenticWorkflowOrchestrator(unittest.TestCase):
        def setUp(self):
            self.orch = AgenticDiagramWorkflowOrchestrator()
            # Register MCP tools
            self.orch.register_mcp_tool(MCPToolDefinition(
                server_name="mermaid-server",
                tool_name="render_mermaid",
                description="Renders Mermaid code into SVG vector artifacts",
                parameters_schema={"mermaid_code": "string"}
            ))
            self.orch.register_mcp_tool(MCPToolDefinition(
                server_name="marp-server",
                tool_name="compile_marp_deck",
                description="Compiles structured slide definitions into Marp Markdown",
                parameters_schema={"title": "string", "slides": "array"}
            ))
            # Register Skill
            self.orch.register_skill(AgentSkillDefinition(
                skill_name="presentation_architect",
                description="Transforms repositories into executive architecture decks",
                system_prompt="You are an autonomous presentation architect...",
                required_mcp_tools=["mermaid-server:render_mermaid", "marp-server:compile_marp_deck"]
            ))

        def test_mcp_registration_and_execution(self):
            res = self.orch.execute_mcp_tool(
                "mermaid-server",
                "render_mermaid",
                {"mermaid_code": "flowchart LR\nA --> B"}
            )
            self.assertTrue(res.success)
            self.assertIn("<svg", res.data["svg_artifact"])

        def test_unregistered_mcp_tool_failure(self):
            res = self.orch.execute_mcp_tool("unknown-server", "some_tool", {})
            self.assertFalse(res.success)
            self.assertIn("not registered", res.error_message)

        def test_end_to_end_pipeline_success(self):
            pipeline_res = self.orch.run_end_to_end_presentation_pipeline("Repo: microservices demo")
            self.assertEqual(pipeline_res["status"], "COMPLETED")
            self.assertEqual(pipeline_res["total_slides"], 3)
            self.assertIn("marp: true", pipeline_res["marp_deck"])
            self.assertIn("flowchart TD", pipeline_res["mermaid_code"])
            self.assertIn("Rendered Diagram", pipeline_res["svg_artifact"])
            self.assertEqual(len(self.orch.execution_history), 2)

    suite = unittest.TestLoader().loadTestsFromTestCase(TestAgenticWorkflowOrchestrator)
    runner = unittest.TextTestRunner(verbosity=2)
    test_result = runner.run(suite)
    if not test_result.wasSuccessful():
        exit(1)
    print("\n[PASS] All PB-05 Chapter 5 Unit Tests Passed Successfully (100% Conformance).")

Verification & Execution Output

When executed in Python 3.11+, this engine confirms MCP tool registration, unregistered tool failure handling, and end-to-end pipeline execution:

test_end_to_end_pipeline_success (__main__.TestAgenticWorkflowOrchestrator.test_end_to_end_pipeline_success) ... ok
test_mcp_registration_and_execution (__main__.TestAgenticWorkflowOrchestrator.test_mcp_registration_and_execution) ... ok
test_unregistered_mcp_tool_failure (__main__.TestAgenticWorkflowOrchestrator.test_unregistered_mcp_tool_failure) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

[PASS] All PB-05 Chapter 5 Unit Tests Passed Successfully (100% Conformance).

9. Summary & Visual Engineering Milestone Checklist

Before moving to Chapter 06 (Multimodal Vision Critique & Visual Quality Assurance):

• Configured Claude Code and Antigravity CLI workflows for visual systems.
• Integrated the Model Context Protocol (MCP) for Mermaid and Marp tool dispatching.
• Contrasted ad-hoc web chat prompts with autonomous CLI skills and MCP tools.
• Authored production CLAUDE.md and Antigravity SKILL.md configuration files.
• Compiled the Quantitative Trade-Off Matrix for agent execution modes.
• Analyzed and mitigated the 10 Technical Pitfalls in agentic visual workflows.
• Executed and validated the zero-dependency Python 3.11+ workflow orchestrator engine.