pptx-author Skill Headless vs Interactive Mode: Architectural Differences

The pptx-author skill switches between a file‑centric workflow using python‑pptx in headless mode and a live‑Office workflow using mcp__office__powerpoint_* tools in interactive Cowork mode, with distinct output contracts and execution flows for each environment.

The pptx-author skill in the anthropics/financial‑services repository generates PowerPoint presentations, but its implementation diverges significantly based on whether the agent operates in automated headless deployments or interactive Cowork sessions. Understanding these behavioral differences is essential for deploying financial analysis agents that either produce downloadable artifacts or drive real‑time collaborative editing.

Headless Mode Implementation

In headless mode, the skill operates as a standalone document generator without requiring a live Microsoft PowerPoint instance. According to the source definition in plugins/vertical-plugins/financial-analysis/skills/pptx-author/SKILL.md (lines 8‑30), the skill writes a Python script that utilizes the python‑pptx library to construct slides programmatically.

The headless implementation must adhere to a strict file‑contract:

• Write the final .pptx file to the ./out/ directory
• Return only the relative file path (e.g., ./out/pitch‑mydeal.pptx) to the orchestration layer
• Never attempt to upload or send the deck directly

This mode is automatically selected when the agent runs in managed‑agent (CMA) configurations where no UI or Office client is available.

Interactive Cowork Mode

In interactive mode, the skill transforms into a live‑Office controller that manipulates an open PowerPoint window through the Cowork plugin framework. As documented in SKILL.md (lines 41‑44), the skill checks for the availability of mcp__office__powerpoint_* tool functions before executing.

The interactive workflow requires:

• mcp__office__powerpoint_add_slide for creating new slides
• mcp__office__powerpoint_set_text for populating text placeholders
• mcp__office__powerpoint_insert_chart for adding live data visualizations

Unlike the headless path, the skill must return success messages after each tool invocation, allowing the orchestration layer to pause for user review and enabling real‑time human intervention during the deck‑building process.

Execution Flow Comparison

The runtime behavior differs fundamentally between the two modes:

Headless execution flow:

1. Generate a Python script using python‑pptx APIs
2. Execute the script under Bash to build the presentation
3. Save the file to ./out/<name>.pptx
4. Return the relative path to the caller

Interactive execution flow:

1. Check if mcp__office__powerpoint_* tools are available in the environment
2. If present, delegate each slide operation to the live‑Office tool suite
3. Return confirmation after each operation to support checkpoint reviews
4. Allow users to see and edit the deck in real time during generation

Source Code Structure

The dual‑mode logic is defined in multiple locations across the repository:

• plugins/vertical-plugins/financial-analysis/skills/pptx-author/SKILL.md: Defines the primary headless implementation (lines 8‑30) and the conditional fallback to interactive tools (lines 41‑44)
• plugins/agent-plugins/pitch-agent/skills/pptx-author/SKILL.md: Mirrors the vertical‑plugin definition for the pitch‑agent context
• managed-agent-cookbooks/pitch-agent/agent.yaml: Configures the agent to run headless with explicit instructions to write files to ./out/

Headless Mode Example

When operating headlessly, the skill produces Python scripts similar to this implementation:

from pptx import Presentation
from pptx.util import Inches, Pt

# Load a firm‑provided template (if any)

prs = Presentation("./templates/firm-template.pptx")  # or Presentation() for a blank deck

# Add a title‑only slide

slide = prs.slides.add_slide(prs.slide_layouts[5])
slide.shapes.title.text = "Valuation Summary"

# ... insert tables, charts, text boxes as needed ...

# Save the deck; the skill then reports "./out/pitch‑mydeal.pptx"

prs.save("./out/pitch-mydeal.pptx")

Interactive Mode Example

In Cowork environments, the skill utilizes MCP tools to manipulate the live application:

# Pseudo‑code illustrating the live‑Office path

if mcp__office__powerpoint_add_slide():
    mcp__office__powerpoint_set_text(
        slide_id="slide_1",
        placeholder="title",
        text="Valuation Summary"
    )
    # Add a chart via the live‑Office API

    mcp__office__powerpoint_insert_chart(
        slide_id="slide_1",
        chart_type="Bar",
        data=[[ "2024", 120 ], ["2025", 150 ]]
    )
    # ... more live edits ...

else:
    # Fallback to headless implementation (see script above)

    run_headless_pptx_author()

Fallback Behavior and Environment Detection

The skill implements asymmetric fallback logic based on tool availability:

Interactive to headless fallback: If the mcp__office__powerpoint_* tools are not present in the environment, the skill automatically falls back to the headless python‑pptx implementation to ensure functionality.

Headless persistence: If a live‑Office tool becomes available while running in headless mode, the skill remains in headless mode. The generated file can be subsequently opened in PowerPoint, but the skill does not switch to live manipulation mid‑execution.

Summary

• Headless mode uses python‑pptx to generate static files in ./out/ suitable for managed‑agent workflows
• Interactive mode leverages mcp__office__powerpoint_* tools to drive live PowerPoint instances in Cowork sessions
• The skill selects modes based on runtime tool availability, with interactive falling back to headless when necessary
• Headless mode requires returning file paths, while interactive mode requires returning success confirmations after each operation
• Implementation logic is defined in SKILL.md files across vertical‑plugins and agent‑plugins directories

Frequently Asked Questions

How does the pptx-author skill detect which mode to use?

The skill checks for the presence of mcp__office__powerpoint_* tools in the execution environment. If these Cowork‑specific tools are available, it selects interactive mode; otherwise, it defaults to the headless python‑pptx implementation.

Can a headless agent switch to interactive mode during execution?

No. According to the source code contract, once the skill initiates in headless mode, it persists in that mode for the duration of the task. Even if live‑Office tools become available, the skill completes the file generation and returns the path to ./out/.

What happens to the PowerPoint file in interactive mode?

In interactive mode, the deck exists within the live PowerPoint application rather than as a saved file on disk. The skill returns success messages after each operation, allowing the user to review and edit the presentation in real time before manually saving it.

Where is the headless output directory configured?

The ./out/ directory requirement is specified in the SKILL.md definition (lines 8‑30) and reinforced in managed‑agent configurations such as managed-agent-cookbooks/pitch-agent/agent.yaml, which explicitly notes that agents must write files to ./out/ when running headless.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}