name: canva-manager
description: |
Comprehensive Canva API integration skill for managing designs, folders, assets, and exports.
Uses a 3-mode workflow: PLAN (analyze what needs to be done), CLARIFY (ask user questions),
and IMPLEMENT (execute changes via Python scripts). Ensures safe operations by always
confirming changes before execution. Use this skill when the user wants to work with their
Canva account, manage designs, organize folders, upload assets, or export designs.

Canva Manager Skill

A comprehensive skill for managing Canva designs, folders, and assets through the Canva Connect API. This skill operates in a 3-mode workflow to ensure safe and accurate operations on your Canva account.

Overview

This skill provides full control over your Canva account including:
- Designs: List, view, create, import (PPTX/PDF/AI/PSD), export, and manage designs
- Folders: Create, organize, move items, and manage your project structure
- Assets: Upload images/videos, manage asset library
- Exports: Export designs to various formats (PDF, PNG, JPG, PPTX, MP4, GIF)

3-Mode Workflow

CRITICAL: Always follow this workflow. Never skip to implementation without completing Plan and Clarify modes.

Mode 1: PLAN

Before making ANY changes to Canva, you MUST:

1. Analyze the Request
2. What exactly does the user want to accomplish?
3. Which Canva resources are involved (designs, folders, assets)?

4. What API operations will be needed?

5. Gather Current State

6. Run the discovery scripts to understand current Canva account state
7. List relevant designs, folders, or assets

8. Identify exactly which items will be affected

9. Create Detailed Plan

10. Document every action that will be taken
11. List which designs/folders/assets will be modified
12. Specify the exact changes (names, exports, moves, etc.)

13. Identify potential risks or irreversible actions

14. Present Plan to User

Mode 2: CLARIFY

After presenting the plan, you MUST ask clarifying questions:

1. Required Questions
2. "Does this plan accurately reflect what you want to do?"

3. "Are there any items I should exclude from this operation?"

4. Context-Specific Questions

5. For exports: "What format and quality do you prefer?"
6. For folder operations: "Should I create backups first?"

7. For design modifications: "Should I work on copies instead of originals?"

8. Confirmation Requirements

9. Get explicit "yes" or confirmation before proceeding
10. If user has concerns, return to PLAN mode with modifications

Mode 3: IMPLEMENT

Only after explicit user approval:

1. Execute with Logging
2. Run the appropriate Python scripts
3. Log every API call and response

4. Save results to the output folder

5. Report Results

6. Show exactly what was changed
7. Provide links/IDs of affected items
8. Note any errors or partial completions

Environment Setup

Ensure the .env file is configured:

# Required - Get from https://www.canva.com/developers/
CANVA_CLIENT_ID=your_client_id
CANVA_CLIENT_SECRET=your_client_secret

# OAuth tokens (obtained after authorization)
CANVA_ACCESS_TOKEN=your_access_token
CANVA_REFRESH_TOKEN=your_refresh_token

# Optional
CANVA_REDIRECT_URI=http://127.0.0.1:3001/oauth/redirect

Running Python Scripts (Virtual Environment)

IMPORTANT: Always use the virtual environment Python:

# Windows
.venv\Scripts\python.exe scripts/<script_name>.py

# macOS/Linux
.venv/bin/python scripts/<script_name>.py

Available Scripts

All scripts are in scripts/:

Discovery Scripts (Safe - Read Only)

auth_check.py - Verify credentials and get user info

.venv\Scripts\python.exe scripts/auth_check.py

list_designs.py - List all designs with metadata

.venv\Scripts\python.exe scripts/list_designs.py
.venv\Scripts\python.exe scripts/list_designs.py --query "presentation" --limit 10
.venv\Scripts\python.exe scripts/list_designs.py --json

list_folders.py - List folder structure

.venv\Scripts\python.exe scripts/list_folders.py
.venv\Scripts\python.exe scripts/list_folders.py --json

get_design_details.py - Get detailed info about a specific design

.venv\Scripts\python.exe scripts/get_design_details.py "DESIGN_ID"
.venv\Scripts\python.exe scripts/get_design_details.py "DESIGN_ID" --pages --formats

list_folder_contents.py - List items in a specific folder

.venv\Scripts\python.exe scripts/list_folder_contents.py "FOLDER_ID"
.venv\Scripts\python.exe scripts/list_folder_contents.py "root" --types design folder
.venv\Scripts\python.exe scripts/list_folder_contents.py "uploads"

Export Scripts

export_design.py - Export a design to specified format

.venv\Scripts\python.exe scripts/export_design.py "DESIGN_ID" --format pdf
.venv\Scripts\python.exe scripts/export_design.py "DESIGN_ID" --format pptx --output output/exports
.venv\Scripts\python.exe scripts/export_design.py "DESIGN_ID" --format png --pages 1 2 3

download_export.py - Download a completed export by job ID

.venv\Scripts\python.exe scripts/download_export.py "EXPORT_JOB_ID"
.venv\Scripts\python.exe scripts/download_export.py "EXPORT_JOB_ID" --output output/myfile

batch_export.py - Export multiple designs at once

.venv\Scripts\python.exe scripts/batch_export.py --designs "ID1" "ID2" "ID3" --format pdf
.venv\Scripts\python.exe scripts/batch_export.py --designs "ID1" "ID2" --format pptx --output output/exports

Import Scripts

import_design.py - Import PPTX, PDF, AI, or PSD files into Canva

# Import a PPTX file
.venv\Scripts\python.exe scripts/import_design.py "presentation.pptx"

# Import with custom title
.venv\Scripts\python.exe scripts/import_design.py "presentation.pptx" --title "My Imported Presentation"

# Import a PDF
.venv\Scripts\python.exe scripts/import_design.py "document.pdf" --title "My PDF"

# Start import without waiting
.venv\Scripts\python.exe scripts/import_design.py "presentation.pptx" --no-wait

Supported import formats:
- .pptx - PowerPoint presentations
- .pdf - PDF documents
- .ai - Adobe Illustrator files
- .psd - Photoshop files

get_import_status.py - Check status of import job

.venv\Scripts\python.exe scripts/get_import_status.py "JOB_ID"
.venv\Scripts\python.exe scripts/get_import_status.py "JOB_ID" --wait

Asset Upload Scripts

upload_asset.py - Upload images/videos to Canva

# Upload an image
.venv\Scripts\python.exe scripts/upload_asset.py "image.png"

# Upload with custom name
.venv\Scripts\python.exe scripts/upload_asset.py "photo.jpg" --name "Product Photo"

# Upload a video
.venv\Scripts\python.exe scripts/upload_asset.py "video.mp4"

Supported upload formats:
- Images: .jpg, .jpeg, .png, .gif, .webp, .heic, .heif, .tiff, .tif (max 50MB)
- Videos: .mp4, .mov, .avi, .webm, .mkv, .m4v, .mpeg, .mpg (max 500MB)

Folder Management Scripts

create_folder.py - Create a new folder

.venv\Scripts\python.exe scripts/create_folder.py --name "My Project"
.venv\Scripts\python.exe scripts/create_folder.py --name "Subfolder" --parent "PARENT_FOLDER_ID"

move_items.py - Move items between folders

.venv\Scripts\python.exe scripts/move_items.py --items "ITEM_ID1" "ITEM_ID2" --folder "TARGET_FOLDER_ID"
.venv\Scripts\python.exe scripts/move_items.py --items "DESIGN_ID" --folder "root"

delete_folder.py - Delete a folder (moves to trash)

.venv\Scripts\python.exe scripts/delete_folder.py "FOLDER_ID" --confirm

Design Creation Scripts

create_design.py - Create a new blank design

# Create by preset type
.venv\Scripts\python.exe scripts/create_design.py --type presentation --title "My Presentation"
.venv\Scripts\python.exe scripts/create_design.py --type instagram_post

# Create with custom dimensions
.venv\Scripts\python.exe scripts/create_design.py --width 1920 --height 1080 --title "Custom Design"

# List available types
.venv\Scripts\python.exe scripts/create_design.py --list-types

Available design types:
- instagram_post, instagram_story
- facebook_post
- presentation
- doc
- whiteboard
- poster, flyer
- a4, letter

Asset Management Scripts

delete_asset.py - Delete an asset (moves to trash)

.venv\Scripts\python.exe scripts/delete_asset.py "ASSET_ID" --confirm

API Rate Limits

Be aware of Canva API rate limits:
- List operations: 100 requests/user
- Create/Update operations: 20-30 requests/user
- Export operations: 20 requests/user
- Import operations: 20 requests/minute

For bulk operations, scripts automatically implement delays between requests.

Usage Examples

Example 1: Explore Canva Account

# Check authentication
.venv\Scripts\python.exe scripts/auth_check.py

# List all designs
.venv\Scripts\python.exe scripts/list_designs.py

# List folder structure
.venv\Scripts\python.exe scripts/list_folders.py

Example 2: Export Presentation to PPTX

# Find the design
.venv\Scripts\python.exe scripts/list_designs.py --query "Q4 Report"

# Export it
.venv\Scripts\python.exe scripts/export_design.py "DESIGN_ID" --format pptx --output output/exports

Example 3: Import PPTX to Canva

# Import the file
.venv\Scripts\python.exe scripts/import_design.py "presentation.pptx" --title "Imported Presentation"

Example 4: Organize Designs into Folders

# Create a folder
.venv\Scripts\python.exe scripts/create_folder.py --name "2024 Projects"

# Move designs to the folder
.venv\Scripts\python.exe scripts/move_items.py --items "DESIGN_ID1" "DESIGN_ID2" --folder "NEW_FOLDER_ID"

Example 5: Upload Assets

# Upload images
.venv\Scripts\python.exe scripts/upload_asset.py "logo.png" --name "Company Logo"
.venv\Scripts\python.exe scripts/upload_asset.py "photo.jpg" --name "Product Photo"

Safety Guidelines

1. Never modify without confirmation - Always get explicit approval
2. Prefer copies over originals - For risky operations, suggest working on copies
3. Batch operations need extra care - Show sample of items before bulk changes
4. Export originals before deletion - If user wants to delete, export first
5. Log everything - All operations are logged to output folder
6. Rate limit awareness - Don't exceed API limits; scripts implement delays

Troubleshooting

Authentication Issues

.venv\Scripts\python.exe scripts/auth_check.py

If this fails, re-run OAuth flow or refresh tokens.

Design Not Found

• Check exact spelling and case
• Try listing all designs to find the correct name
• Designs may be in trash or shared with you

Export Failures

• Some formats require Canva Pro
• Very large designs may timeout
• Check design isn't corrupted

Import Failures

• Ensure file format is supported (.pptx, .pdf, .ai, .psd)
• Check file size limits
• Verify file isn't corrupted

Resources

• Canva Connect API Docs
• Canva Developer Portal
• API Rate Limits

Todo List Tracking (REQUIRED)

ALWAYS use TodoWrite to track progress for Canva operations:

[
  {"content": "Check API authentication", "status": "in_progress", "activeForm": "Checking authentication"},
  {"content": "List user's designs", "status": "pending", "activeForm": "Listing designs"},
  {"content": "Export requested design", "status": "pending", "activeForm": "Exporting design"},
  {"content": "Confirm completion", "status": "pending", "activeForm": "Confirming completion"}
]

File Outputs

All outputs are saved to the output/ folder:
- output/exports/ - Exported files (PDFs, images, PPTX, etc.)
- output/logs/ - Operation logs with timestamps
- output/auth/ - Authentication info