PPTAgent Skill

[!TIP] You can use a multimodal vision model as a multimodal reviewer and apply for an API token through the Duanyan (端砚) Token Plan. We recommend deepseek-v4-flash-vision as the multimodal model. Setup guide →

Quick Start 🚀

Requirements: Linux (including WSL) or macOS, Python 3.11+, uv, npm, and LibreOffice available as libreoffice on PATH. On macOS, the upstream converter also uses an installed Google Chrome.

sudo apt-get install npm libreoffice-impress

brew install node
brew install --cask libreoffice google-chrome
ln -sf "$(command -v soffice)" "$(brew --prefix)/bin/libreoffice"

From the repository root:

cd skills/pptagent
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt
.venv/bin/python -m playwright install --with-deps chromium

# Choose claude, codex, or opencode.
.venv/bin/python scripts/install.py --client opencode
.venv/bin/python scripts/pptagent.py doctor

The installer prepares Node dependencies and registers this directory with the selected host. Keep the skill directory in place. Its tools use the local virtual environment, so your host does not need to activate it. OpenCode installs a small routing entry at ~/.config/opencode/skills/pptagent; restart the client after registration.

Try Atria Dawn Preview ✨

The example below connects Atria Dawn Preview to Claude Code or Codex to develop the content and author slide HTML. As a text-only model, Atria uses the text workflow: set mode: text and configure a visual model to review the rendered slides.

[!TIP] Get a free Token Plan: Discovery · Atria. Create an API key in the Atria console, then follow the example below. See the official Atria integration guide for current service details.

1. Check your Atria API key

Set your key in the terminal you will use to launch your client, then send a minimal request:

export ATRIA_API_KEY="<your-atria-api-key>"

curl -X POST https://api.atria-asi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ATRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Atria-Dawn-Preview",
    "messages": [{"role": "user", "content": "hi"}]
  }'

Check that the response contains an assistant reply in choices[0].message.content. This checks your key and Chat Completions access; client integration uses the other Atria interfaces below.

2. Configure your client and register the skill

Complete Quick Start first, then choose your client. Atria supports all three API formats:

Use the base URL shown for your client; it appends the API path itself. Keep the model ID exactly Atria-Dawn-Preview.

.venv/bin/python scripts/install.py --client claude

{
  "model": "Atria-Dawn-Preview",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.atria-asi.ai"
  }
}

export ANTHROPIC_AUTH_TOKEN="$ATRIA_API_KEY"
mkdir -p ~/pptagent-demo
cd ~/pptagent-demo
claude

.venv/bin/python scripts/install.py --client codex

model = "Atria-Dawn-Preview"
model_provider = "atria"

[model_providers.atria]
name = "Atria"
base_url = "https://api.atria-asi.ai/v1"
env_key = "ATRIA_API_KEY"
wire_api = "responses"

mkdir -p ~/pptagent-demo
cd ~/pptagent-demo
codex

3. Start a presentation task

Set up text-mode visual review before generating the deck: set mode: text, visual.base_url, and visual.model in the skill's config.yaml, and VISUAL_API_KEY in its .env or environment. Follow the complete configuration example, then send the presentation request below.

The workflow is Atria authors HTML → the skill renders images → the external visual model reviews them → Atria fixes reported issues. The skill also renders and reviews the exported PPTX before final delivery. Its CLI calls the visual API directly and returns structured review results to the text model.

In Claude Code, explicitly invoke /pptagent with your request; in Codex, use $pptagent. If the skill is unavailable, check the registration path above and start a new client session. The skill's .env configures its own tools; set the host's Atria key in the launch terminal as shown above.

Try It 💬

Open Claude Code or Codex in a separate task folder and ask:

Use the pptagent skill to create a 6-slide presentation on our Q3 results
for a leadership review. Use the files in this folder as source material.
Render and visually review the deck before delivering the editable PPTX.

Then iterate in the same task:

Shorten the opening to one slide and make the recommendations more concrete.
Keep the presentation at 6 slides, then rebuild and review the updated deck.

Your deliverable is answer.pptx. The task folder also keeps the HTML slide sources, local assets, rendered previews, and a final review report. Supported layouts are 16:9, 4:3, and A1.

From brief to deck

Configuration ⚙️

If your host model can view images, start with the default multimodal mode. For text-only models, such as Atria or text models in the GLM family, use mode: text and configure an external visual model to review the slides. MinerU and search are optional additions for better PDF extraction and source gathering.

Your authoring model, such as Atria, stays in the host's configuration. The skill directly configures visual review; document parsing and retrieval are tools your host can call while preparing the slides.

Visual review

In text mode, the skill sends rendered slides to the visual API and returns review results to your host model. The optional document and search MCP servers below help the host gather source material.

For first-time text-mode setup, run these commands from skills/pptagent/. If you already have local configuration files, edit those instead of replacing them:

cp config.example.yaml config.yaml
cp .env.example .env
chmod 600 .env

You can use a multimodal vision model as a multimodal reviewer and apply for an API token through the Duanyan (端砚) Token Plan. We recommend deepseek-v4-flash-vision as the multimodal model.

Edit config.yaml as follows, replacing base_url with the OpenAI-compatible API base URL shown in your Duanyan console:

mode: text

visual:
  base_url: "<OpenAI-compatible API base URL from the Duanyan console>"
  model: "deepseek-v4-flash-vision"
  api_key_env: VISUAL_API_KEY
  timeout_seconds: 300

delivery:
  mode: strict

Set your Duanyan API key in the skill's .env:

VISUAL_API_KEY=<your-duanyan-api-key>

The Token Plan link opens the service console; it is not an API endpoint. Use the console's exact model ID if it differs from deepseek-v4-flash-vision. The reviewer must accept image inputs through an OpenAI-compatible Chat Completions API. Set base_url to the API prefix, including /v1 when required; the skill appends /chat/completions. api_key_env names the environment variable containing the key. Existing environment variables take precedence over .env.

Run .venv/bin/python scripts/pptagent.py doctor from the skill directory to check local dependencies and required settings. It does not make an API request; the first review-slides call checks the actual endpoint. See the text-mode guide for the review response format.

OpenCode setup

Complete Quick Start, using --client opencode. Confirm that OpenCode discovers the skill:

opencode debug skill

The host model and API provider remain in your normal OpenCode configuration. For a text-only host, first configure the visual endpoint above, then initialize a separate presentation workspace:

.venv/bin/python scripts/pptagent.py init \
  --workspace /absolute/path/to/pptagent-demo \
  --slides 6

Create opencode.json in that workspace. Replace the three absolute paths:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pptagent-visual": {
      "type": "local",
      "command": [
        "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python",
        "/absolute/path/to/PPTAgent/skills/pptagent/scripts/visual_mcp.py",
        "--workspace",
        "/absolute/path/to/pptagent-demo"
      ],
      "enabled": true,
      "timeout": 1800000
    }
  }
}

Start OpenCode in the workspace and verify the server:

cd /absolute/path/to/pptagent-demo
opencode mcp list
opencode

Ask OpenCode to use the pptagent skill. During generation it should call review_slides, fix reported issues, build answer.pptx, call review_deck, and run finalize. The MCP is a local stdio adapter; it does not open a network port. It reads config.yaml and .env from the Skill directory. --config and --env can select other files when needed.

OpenCode documentation: Skills and MCP servers.

MinerU for source documents · optional

MinerU is useful when a presentation starts from papers, scanned reports, or PDFs with complex tables and equations. It improves the material available to the authoring model. For a short brief or existing Markdown, you can use the host's normal file-reading tools.

The installed pptagent package includes the deeppresenter.tools.any2markdown MCP server. Its convert_to_markdown tool uses MinerU for PDFs when configured:

Choose one: the hosted API key takes precedence if both are set. Without either setting, the conversion tool uses its standard MarkItDown fallback. You can also parse a document through MinerU separately and place the resulting Markdown and images in your task folder.

After connecting the tool, ask: “Convert report.pdf into an empty research/report/ folder, then use its Markdown and figures as sources for the presentation.” Copy figures used in slides into the task's assets/ directory.

Research and retrieval · optional

Use your host's existing search tools if they already meet your needs. For additional web and image search, the installed package includes deeppresenter.tools.search, which exposes search_web, search_images, fetch_url, and download_file.

Configure one provider. SerpAPI takes precedence if both keys are present; without either key, this server provides URL fetching and downloading but does not register web/image search. Your host model plans queries and synthesizes the results, so there is no separate search.model setting in the skill.

For example: “Find recent primary sources for this topic, record their URLs and dates, and use them to support the presentation's claims.” Search access through a custom model provider depends on the host's available tools; configuring Atria alone does not add a search service.

export WORKSPACE="$PWD"
export MINERU_API_KEY="<your-mineru-api-key>"
export TAVILY_API_KEY="<your-tavily-api-key>"

{
  "mcpServers": {
    "pptagent-docs": {
      "type": "stdio",
      "command": "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python",
      "args": ["-m", "deeppresenter.tools.any2markdown"],
      "env": {
        "WORKSPACE": "${WORKSPACE}",
        "MINERU_API_KEY": "${MINERU_API_KEY}"
      }
    },
    "pptagent-search": {
      "type": "stdio",
      "command": "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python",
      "args": ["-m", "deeppresenter.tools.search"],
      "env": {
        "WORKSPACE": "${WORKSPACE}",
        "TAVILY_API_KEY": "${TAVILY_API_KEY}"
      }
    }
  }
}

[mcp_servers.pptagent-docs]
command = "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python"
args = ["-m", "deeppresenter.tools.any2markdown"]
env_vars = ["WORKSPACE", "MINERU_API_KEY"]
startup_timeout_sec = 30
tool_timeout_sec = 1800

[mcp_servers.pptagent-search]
command = "/absolute/path/to/PPTAgent/skills/pptagent/.venv/bin/python"
args = ["-m", "deeppresenter.tools.search"]
env_vars = ["WORKSPACE", "TAVILY_API_KEY"]
startup_timeout_sec = 30
tool_timeout_sec = 120

Delivery checks

Strict delivery is the default: the deck must pass review and match the current sources. If the user explicitly accepts an incomplete draft, delivery.mode: best-effort permits delivery with the failed checks disclosed. Source changes still require a fresh build.

More Details 📖

• Skill instructions: the workflow followed by your host agent.
• Task and source contract: workspace layout and authoring guidance.
• Configuration example: available settings.
• PPTAgent project: current releases, installation, and project history.

Part of PPTAgent · MIT License