# pptx-author Skill Headless vs Interactive Mode: Architectural Differences

> Explore pptx-author skill differences: headless mode uses python-pptx for files, while interactive mode leverages live Office tools. Understand distinct workflows and outputs.

- Repository: [Anthropic/financial-services](https://github.com/anthropics/financial-services)
- Tags: architecture
- Published: 2026-05-07

---

**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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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:

```python
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:

```python

# 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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) definition (lines 8‑30) and reinforced in managed‑agent configurations such as [`managed-agent-cookbooks/pitch-agent/agent.yaml`](https://github.com/anthropics/financial-services/blob/main/managed-agent-cookbooks/pitch-agent/agent.yaml), which explicitly notes that agents must write files to `./out/` when running headless.