Build a Podcast Editing Agent

Connect the Codex app to Descript via MCP to edit podcasts with AI.

Introduction

30 Second Summary

Editing a podcast episode means hours of removing filler words, cleaning up audio quality, and exporting transcripts. What if you could hand all of that to an AI agent and just describe what you want in plain English?

In this project, you will build a structured AI podcast editing agent using the Codex app connected to Descript. You'll organize the agent with modular skills and a custom subagent so it can import episodes, clean audio, and export transcripts on command.

What You'll Build

A fully structured podcast editing agent powered by the Codex app, connected to Descript via Model Context Protocol (MCP), and organized using Codex's layered agent architecture of project guidance, skills, and subagents.

By the end of this project, you'll have:

  • The Codex app installed and connected to Descript via an MCP server, giving your agent access to podcast editing tools.
  • A root AGENTS.md file that defines your podcast editing conventions and tells Codex when to trigger each skill.
  • Three purpose-built skills for importing episodes, cleaning audio, and exporting transcripts, plus a custom subagent for batch processing multiple episodes.
  • Secret Mission: Create a highlight reel skill that generates 30-second clips from any episode and wire it into the pipeline as a post-edit step.

Are there any prerequisites?

You need a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan (which includes access to the Codex app) and a Descript account (free or paid). No prior experience with MCP or agent file structures is required.

Install the Codex App and Node.js

Before you can build the podcast editing agent, you need two foundational tools installed on your machine.

The Codex app is your AI command center where you'll interact with the agent through natural language. Node.js powers the MCP server that connects Codex to Descript. In this step, you'll install both tools and create the project folder where all your agent files will live.

In this step, get ready to:
  • Install the Codex app and sign in with your ChatGPT account.
  • Install and verify Node.js (version 18 or higher).
  • Create the project folder and open it in the Codex app.
Download and install the Codex app

The Codex app is a desktop interface for running AI agent threads. It reads project files, executes commands, and connects to external tools via MCP. You need a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan to use it.

  • Open your browser and navigate to the Codex download page.
  • Click the Windows download link to get the app from the Microsoft Store.
  • Install the app and wait for it to finish.

What about macOS?

The Codex app is also available on macOS. If you're on a Mac, download the macOS version from the same page. The rest of this project works identically on both platforms.

  • Press the Windows key to open your search bar.
  • Type Codex and press Enter to open the app.
  • Sign in with your ChatGPT account when prompted.

What is the Codex app?

The Codex app is OpenAI's desktop interface for working with AI coding agents. It lets you run multiple agent threads in parallel, review changes, and connect to external tools through MCP servers.

Think of it as a chat window where the AI can actually read your files and run commands on your machine, inside a secure sandbox.

Codex app won't start?

If you see a permissions error on first launch, try right-clicking the Codex app and selecting Run as administrator. This resolves most first-launch issues on Windows.

If your Windows username contains non-English characters, you may need to set CODEX_HOME to a path without special characters.

help me troubleshoot the Codex app not starting on Windows

Install and verify Node.js

Node.js is the JavaScript runtime that powers the Descript MCP server. The MCP server runs as a local process launched by Codex, and it requires Node.js version 18 or higher to work.

  • Check whether Node.js is already installed by opening PowerShell and running this command:
node --version

✔️ I see version 18 or higher

If you see a version number like v18.20.8 or v24.16.0, Node.js is ready. Move on to the next substep.

ⓧ I see an older version

If you see a version lower than v18 (like v16.x.x), you need to upgrade.

  • Go to https://nodejs.org/en/download in your browser.
  • Download the LTS installer for Windows.
  • Run the installer and accept the defaults. This replaces your existing Node.js version.
  • Close and reopen PowerShell, then run node --version again to confirm it now shows v18 or higher.

ⓧ Command not found

Node.js is not installed yet. Follow these steps to install it:

  • Go to https://nodejs.org/en/download in your browser.
  • Download the LTS installer for Windows (the .msi file).
  • Run the installer and accept all default options.
  • Close and reopen PowerShell after the install completes.
  • Run node --version to confirm it shows v18 or higher.

Still seeing 'command not found' after installing?

Make sure you closed and reopened PowerShell after installation. The new PATH entries only take effect in new terminal sessions.

help me fix Node.js not being recognized in PowerShell after installation

Create the project folder and open it in Codex

Every Codex project starts with a folder. Codex reads files from this folder and uses them to understand its role and available tools.

  • Move to your Desktop by running this command in PowerShell:
cd ~/Desktop
  • Create the project folder and move into it by running these commands:
mkdir podcast-agent
cd podcast-agent
  • Confirm the folder exists by running:
ls

You should see an empty directory listing (no files yet). This is expected.

  • Switch to the Codex app. If you closed it, press the Windows key, type Codex, and press Enter.
  • In the Codex app, select your podcast-agent folder as the project folder. It should be on your Desktop.
  • Make sure Local is selected as the thread mode (not Worktree or Cloud).
  • Send a test message to confirm everything works. Type something like: "What folder am I in?"

Codex should respond with the path to your podcast-agent folder. This confirms the app is connected and reading from the right location.

What does Local mode mean?

When you select Local, Codex runs commands directly in your project folder on your machine. This is what you want for this project since you'll be creating files and running MCP servers locally.

The other modes (Worktree and Cloud) isolate changes in separate Git branches or remote environments. You don't need those here.

Codex not responding to your test message?

Make sure you're signed in with a ChatGPT account that has an active Plus, Pro, Business, Edu, or Enterprise subscription. Codex requires one of these plans.

If the app hangs or shows an error, try closing and reopening it. The sandbox setup can occasionally require a restart on first use.

help me get the Codex app responding to messages

Your environment is ready. Next up, you'll connect the Codex app to Descript via MCP so your agent can control podcast editing through natural language.

Set Up Descript MCP Connection

Your project folder is ready and the Codex app knows where to look. The next goal is giving Codex the ability to control Descript, your podcast editing tool, directly through natural language.

You'll connect the two using Model Context Protocol (MCP), which lets AI tools communicate with external services through a standardized interface. To make this work, you need an API token from Descript and a configuration file that tells Codex how to launch the MCP server.

In this step, get ready to:
  • Create a Descript API token for authenticating requests.
  • Store the token as a persistent environment variable on Windows.
  • Configure the MCP server in Codex and verify the connection.
Create a Descript API token

Descript uses API tokens to authenticate requests from external tools. Each token is tied to a specific Drive, so Codex can only access projects on the Drive you choose.

  • Open Descript (the desktop app or web app at web.descript.com).
  • Open Settings by pressing Ctrl+, (desktop) or clicking the settings gear icon (web).
  • Select API tokens from the sidebar.
  • Click Create token.
  • Enter Codex Agent as the token name.
  • Select the Drive you want Codex to access from the dropdown.
  • Click Create token.
  • Copy the token immediately and paste it somewhere safe (a temporary text file or password manager).

Copy your token now

You will not be able to view this token again after closing the dialog. If you lose it, you will need to generate a new one.

What is an API token?

An API token is a unique key that authenticates your requests. It works like a password that lets external tools talk to Descript on your behalf.

Each token is scoped to one Drive, so if you work across multiple Drives, you would need separate tokens for each.

Store the token as a persistent environment variable

The MCP server needs your token to authenticate with Descript. Instead of hardcoding the token in a config file, you'll store it as a Windows environment variable that Codex can forward to the server process at runtime.

  • Open PowerShell by pressing the Windows key, typing PowerShell, and pressing Enter.
  • Set the environment variable by running this command (replace your-token-here with the token you just copied):
[System.Environment]::SetEnvironmentVariable("DESCRIPT_API_TOKEN", "your-token-here", "User")

What does this command do?

This stores DESCRIPT_API_TOKEN as a persistent User-level environment variable on Windows. It survives reboots and is available to any process you launch.

The "User" scope means only your account can read it. Programs started before you set this variable will not see it until they are restarted.

  • Close and reopen the Codex app so it picks up the new environment variable.

Token not working later?

Make sure you replaced your-token-here with your actual token value (no extra spaces or quotes around the value beyond what the command already provides).

If you closed the token dialog before copying, go back to Descript Settings > API tokens, delete the old token, and create a new one.

Help me troubleshoot my Descript API token environment variable on Windows.

Configure the MCP server and verify the connection

Codex uses a file called config.toml to know which MCP servers to launch. You'll add an entry for the Descript MCP server so Codex can start it automatically whenever you open a thread.

  • In the Codex app, open Settings.
  • Click Integrations & MCP.
  • Click the link to open config.toml. This opens the file at ~/.codex/config.toml in your default text editor.
  • Add the Descript MCP server configuration by pasting the following at the end of the file:
[mcp_servers.descript]
command = "npx"
args = ["@t-campbell18/descript-mcp"]
env_vars = ["DESCRIPT_API_TOKEN"]
tool_timeout_sec = 300

What does this configuration do?

  • command = "npx" tells Codex to launch the server using npx, which downloads and runs the package on the fly.
  • args specifies the npm package @t-campbell18/descript-mcp that implements the Descript MCP server.
  • env_vars = ["DESCRIPT_API_TOKEN"] forwards your environment variable to the server process so it can authenticate with Descript.
  • tool_timeout_sec = 300 gives each tool call up to 5 minutes to complete. Descript jobs (importing media, running edits) can take 30 seconds to several minutes, so the default 60-second timeout would cut them off.
  • Save config.toml and close the text editor.
  • Close and reopen the Codex app to load the new MCP server configuration.
  • Open a new thread in the Codex app (make sure your podcast-agent project is selected).
  • Type the following message and send it:
What Descript tools do you have access to?

Codex should respond with a list of available Descript tools such as import_media, run_agent, list_jobs, and others. This confirms the MCP connection is working.

Codex doesn't list any Descript tools?

Make sure you saved config.toml and fully restarted the Codex app (close the window, reopen).

Verify the environment variable is set by opening a new PowerShell window and running $env:DESCRIPT_API_TOKEN. If it returns nothing, re-run the SetEnvironmentVariable command from earlier and restart the Codex app again.

Also confirm that Node.js is accessible by running node --version in a terminal. The npx command depends on Node.js being in your system path.

Help me troubleshoot my Descript MCP connection in the Codex app.

✔️ Awesome, I've got everything!

Great. Double check you saved config.toml and the connection is active.

ⓧ I'd like to double check the full code

Here is what your ~/.codex/config.toml should contain (it may have other entries above the Descript block):

[mcp_servers.descript]
command = "npx"
args = ["@t-campbell18/descript-mcp"]
env_vars = ["DESCRIPT_API_TOKEN"]
tool_timeout_sec = 300

Codex now has full access to Descript's editing tools through MCP. In the next step, you'll create the AGENTS.md file that tells Codex when and how to use these tools.

Create the AGENTS.md Project Guidance

Your Codex app can now talk to Descript through MCP. The connection is live, but Codex doesn't yet know how to use it for podcast editing.

That's where AGENTS.md comes in. This is a project-level instruction file that Codex reads before every task. It defines the project's purpose, lists the available skills, and tells Codex when to trigger each one. You'll also add a project-scoped config file to pin the model.

In this step, get ready to:
  • Create an AGENTS.md file with project guidance and mandatory skill triggers.
  • Add a project-scoped .codex/config.toml to set the default model.
Create the AGENTS.md instruction file

Codex automatically reads any AGENTS.md file in a project's root directory before responding to prompts. Think of it as a permanent briefing document for the agent.

  • Create a new file called AGENTS.md in the root of your podcast-agent folder with the following content:
# Podcast Editing Workspace

This project is a podcast and video transcript editing workspace. All media operations go through the Descript MCP server.

## Project structure

- Skills live in `.agents/skills/` (import-episode, clean-audio, export-transcript)
- Subagents live in `.codex/agents/` (batch-editor for multi-episode work)
- Project config lives in `.codex/config.toml`

## Mandatory skill usage

- Use `$import-episode` when importing any audio or video media into Descript.
- Use `$clean-audio` when editing audio quality (filler words, Studio Sound, captions).
- Use `$export-transcript` when the user asks for a transcript in any format.
- For batch operations involving 2+ episodes, delegate to the `batch_editor` subagent.

## Guidelines

- Always wait for each Descript job to complete before starting the next step.
- Report the Descript project URL after every import so the user can review in the web UI.
- If a job fails, report the error details and suggest retrying or checking the media URL.
- Process episodes sequentially to respect Descript API rate limits.

What does this file do?

The Project structure section tells Codex where to find skills, subagents, and config. This helps it navigate your file system without guessing.

The Mandatory skill usage section forces Codex to use specific skills for specific tasks. When you later create the $import-episode skill, Codex will automatically invoke it any time you ask to import media.

The Guidelines section prevents common mistakes like starting a new job before the previous one finishes, or forgetting to share the project URL with you.

  • Save AGENTS.md.
  • In the Codex app, open a new thread and type: "What skills are available in this project?" Codex should reference the three skills listed in your AGENTS.md (even though you haven't created them yet).

Codex not recognizing your AGENTS.md?

Make sure the file is named exactly AGENTS.md (all caps, with the .md extension) and sits in the root of the podcast-agent folder, not inside a subfolder.

Confirm that the Codex app still has your podcast-agent folder selected as the active project. If it reverted, re-select the folder.

Help me figure out why Codex isn't reading my AGENTS.md file.

✔️ Awesome, I've got everything!

Great. Make sure you've saved AGENTS.md before moving on.

ⓧ I'd like to double check the full code

Here's the complete AGENTS.md file for comparison:

# Podcast Editing Workspace

This project is a podcast and video transcript editing workspace. All media operations go through the Descript MCP server.

## Project structure

- Skills live in `.agents/skills/` (import-episode, clean-audio, export-transcript)
- Subagents live in `.codex/agents/` (batch-editor for multi-episode work)
- Project config lives in `.codex/config.toml`

## Mandatory skill usage

- Use `$import-episode` when importing any audio or video media into Descript.
- Use `$clean-audio` when editing audio quality (filler words, Studio Sound, captions).
- Use `$export-transcript` when the user asks for a transcript in any format.
- For batch operations involving 2+ episodes, delegate to the `batch_editor` subagent.

## Guidelines

- Always wait for each Descript job to complete before starting the next step.
- Report the Descript project URL after every import so the user can review in the web UI.
- If a job fails, report the error details and suggest retrying or checking the media URL.
- Process episodes sequentially to respect Descript API rate limits.
Add a project-level model config

Codex uses a global config.toml at ~/.codex/config.toml for user-level settings (like your MCP servers). A project-scoped .codex/config.toml inside your project folder overrides the model for this workspace only.

  • Create a .codex folder inside podcast-agent and add a config.toml file by running these commands in PowerShell:
mkdir .codex
New-Item -Path .codex/config.toml -ItemType File
  • Open .codex/config.toml in a text editor and paste in the following content:
model = "gpt-5.5"

What does this config do?

This sets gpt-5.5 as the default model for all Codex interactions within the podcast-agent project. It does not affect your MCP connection or any other projects.

  • Save .codex/config.toml.
  • Confirm the file exists by running:
ls .codex

You should see config.toml listed in the output.

Don't see the .codex folder?

Make sure your PowerShell working directory is inside podcast-agent. Run pwd to check. If you're in the wrong folder, navigate there first with cd.

On Windows, folders starting with a dot are sometimes hidden in File Explorer. They still work normally in the terminal.

Help me create the .codex/config.toml file in my project folder.

✔️ Awesome, I've got everything!

Great. Make sure both files are saved before continuing.

ⓧ I'd like to double check the full code

Here's the complete .codex/config.toml file:

model = "gpt-5.5"

Your agent now has a clear set of operating instructions. Next up, you'll build the first skill that AGENTS.md references: the import episode workflow.

Build the Import Episode Skill

Your AGENTS.md tells Codex what skills exist and when to use them. Now it's time to build the first of those skills so Codex has actual instructions to follow.

Skills are modular instruction files stored in .agents/skills/. Each skill lives in its own folder and contains a SKILL.md file with YAML frontmatter (so Codex can discover it) and step-by-step instructions (so Codex knows how to execute it). In this step, you'll build the $import-episode skill that handles bringing media into Descript.

In this step, get ready to:
  • Create the .agents/skills/import-episode/ directory structure.
  • Write the SKILL.md file with frontmatter and body instructions.
  • Test the skill by importing a demo video through the Codex app.
Create the skills directory and frontmatter

Codex discovers skills by scanning the .agents/skills/ directory for folders that contain a SKILL.md file. The frontmatter at the top of that file tells Codex the skill's name and when to trigger it.

  • Create the nested directory structure by running this command in PowerShell (make sure you're inside the podcast-agent folder):
mkdir .agents/skills/import-episode
  • Confirm the directory was created by running:
ls .agents/skills/import-episode

You should see an empty directory listed with no errors.

  • Create the SKILL.md file inside that directory by running:
New-Item -Path .agents/skills/import-episode/SKILL.md -ItemType File
  • Open SKILL.md in your text editor and paste in this frontmatter:
---
name: import-episode
description: Import audio or video media into a new Descript project with automatic transcription.
---

What is frontmatter?

Frontmatter is the YAML block between the --- delimiters at the top of a Markdown file. Codex reads this metadata to learn the skill's name and a short description of what it does.

The name field is how you invoke the skill ($import-episode). The description field helps Codex decide whether this skill applies to the current request.

  • Save the file.

Directory creation failed?

Make sure your PowerShell terminal is inside the podcast-agent folder. Run pwd to check your current location. If you're somewhere else, run cd followed by the path to your podcast-agent folder on the Desktop.

Help me troubleshoot this issue

Write the skill body

The body of a SKILL.md file contains the actual instructions Codex follows when the skill is triggered. You'll write clear, numbered steps that tell Codex exactly how to use the import_media MCP tool.

  • In .agents/skills/import-episode/SKILL.md, add the following body content below the frontmatter:

# Import Episode

Use this skill when the user wants to bring new audio or video media into Descript for editing.

## Steps

1. Ask the user for the media URL and a project name (if not already provided).
2. Use the `import_media` MCP tool with the media URL and project name.
3. The tool auto-polls until the import and transcription complete.
4. Report back to the user:
   - The project name
   - The project URL (format: `https://web.descript.com/PROJECT_ID`)
   - The media duration
   - Confirmation that transcription is ready

## Notes

- Media URLs must be publicly accessible or pre-signed.
- Descript's test video is available at: `https://test-files.descriptapi.com/demo-video.mp4`
- Import jobs typically take 30-90 seconds depending on file size.
- If the import fails, check that the URL is accessible and supports HTTP Range requests.

What does this skill instruct Codex to do?

The Steps section is what Codex follows like a checklist. It gathers inputs, calls the import_media MCP tool (which connects to the Descript API), waits for the job to finish via auto-polling, and then reports back with useful details.

The Notes section gives Codex extra context for troubleshooting. If a URL fails, Codex knows to suggest checking accessibility instead of retrying blindly.

  • Save SKILL.md.

Formatting looks off?

Make sure there is exactly one blank line between the closing --- of the frontmatter and the # Import Episode heading. Missing this blank line can cause Codex to misread the frontmatter boundary.

Help me fix my SKILL.md formatting

✔️ Awesome, I've got everything!

Great. Double check you've saved the file before moving on.

ⓧ I'd like to double check the full code

Here's the complete SKILL.md file. Make sure yours matches exactly:

---
name: import-episode
description: Import audio or video media into a new Descript project with automatic transcription.
---

# Import Episode

Use this skill when the user wants to bring new audio or video media into Descript for editing.

## Steps

1. Ask the user for the media URL and a project name (if not already provided).
2. Use the `import_media` MCP tool with the media URL and project name.
3. The tool auto-polls until the import and transcription complete.
4. Report back to the user:
   - The project name
   - The project URL (format: `https://web.descript.com/PROJECT_ID`)
   - The media duration
   - Confirmation that transcription is ready

## Notes

- Media URLs must be publicly accessible or pre-signed.
- Descript's test video is available at: `https://test-files.descriptapi.com/demo-video.mp4`
- Import jobs typically take 30-90 seconds depending on file size.
- If the import fails, check that the URL is accessible and supports HTTP Range requests.
Test the skill in the Codex app

The skill file is in place. Now you'll verify that the Codex app discovers it and follows the instructions when you invoke $import-episode.

  • Switch back to the Codex app with your podcast-agent project open.
  • Open a new thread by clicking the + button or starting a new conversation.
  • Type the following prompt and send it:
Use $import-episode to bring in https://test-files.descriptapi.com/demo-video.mp4 as 'Podcast Agent Demo'
  • Watch as Codex discovers the skill and follows each step: requesting confirmation, calling import_media, waiting for the job to complete, and reporting back with a project URL.

What should I see?

Codex should reference the $import-episode skill, call the import_media tool with the demo video URL, and then report the project name, a Descript project URL, the media duration, and confirmation that transcription is ready. The import typically takes 30-90 seconds.

Codex not finding the skill?

Make sure your SKILL.md is saved at exactly .agents/skills/import-episode/SKILL.md relative to the project root. The folder name must match import-episode (with a hyphen, not an underscore).

Also confirm the frontmatter delimiters are exactly --- (three dashes) on their own lines with no extra spaces.

Help me troubleshoot why Codex can't find my skill

Your first skill is live and tested. Next up, you'll build two more skills for cleaning audio and exporting transcripts, giving your agent a complete editing pipeline.

Build the Clean Audio and Export Skills

Your import skill brought a demo episode into Descript with a single natural language prompt. Now it's time to give Codex the ability to actually edit that audio and pull a clean transcript out of it.

You'll create two more skills that handle the core editing workflow. The $clean-audio skill removes filler words, applies Studio Sound, and adds captions. The $export-transcript skill exports a polished transcript in multiple formats.

In this step, get ready to:
  • Create a clean-audio skill that uses Descript's agent editing to polish audio quality.
  • Create an export-transcript skill that pulls transcripts in Markdown, plain text, HTML, RTF, or DOCX.
  • Test the full pipeline by chaining both skills on your demo episode.
Create the clean-audio skill

Descript's API supports agent-based editing where you pass a natural language prompt describing what to do. The run_agent MCP tool wraps this capability. Your clean-audio skill will tell Codex exactly what prompt to send and how to handle partial requests.

  • Create the skill directory by running this command in your terminal (make sure you're inside the podcast-agent folder):
mkdir .agents/skills/clean-audio
  • Confirm the folder exists by running:
ls .agents/skills

You should see both import-episode and clean-audio listed.

  • Create a file called SKILL.md inside the .agents/skills/clean-audio/ directory and paste this content:
---
name: clean-audio
description: Remove filler words and apply Studio Sound to improve audio quality in a Descript project. Optionally adds captions.
---

# Clean Audio

Use this skill when the user wants to clean up a podcast or video's audio quality.

## Steps

1. Confirm you have the project_id from a previous import (or ask the user).
2. Use the `run_agent` MCP tool with this prompt:
   "Remove all filler words from the transcript. Apply Studio Sound to improve audio quality. Add captions."
3. Wait for the job to complete (auto-polls with exponential backoff).
4. Report what was accomplished:
   - Filler words removed
   - Studio Sound applied
   - Captions added
   - AI credits used (from job result)

## Customization

The user may request partial operations:
- "Just remove filler words" - omit Studio Sound and captions from the prompt
- "Add captions only" - omit filler word removal and Studio Sound
- "No captions" - remove captions from the prompt

Adjust the `run_agent` prompt accordingly.

What does this skill do?

The frontmatter (name and description) tells Codex when this skill is relevant. When you type $clean-audio or ask to "clean up the audio", Codex matches the request to this skill.

The Steps section gives Codex a repeatable recipe. It uses the run_agent MCP tool to send a natural language editing prompt to Descript's API. The Customization section teaches Codex how to adapt the prompt when the user only wants some of the operations.

  • Save SKILL.md.
  • Verify the file is in place by running:
ls .agents/skills/clean-audio

You should see SKILL.md listed in the output.

Don't see the file?

Make sure you created the directory with the exact path .agents/skills/clean-audio/ (note the leading dot on .agents). Check that the file is named exactly SKILL.md with all caps.

Help me troubleshoot my clean-audio skill file not appearing in the correct directory.

Create the export-transcript skill

Once audio is cleaned, the next logical step is pulling a written transcript. Descript supports exporting in multiple formats. Your export skill will default to Markdown with speaker labels and let the user override the format.

  • Create the skill directory by running:
mkdir .agents/skills/export-transcript
  • Create a file called SKILL.md inside .agents/skills/export-transcript/ and paste this content:
---
name: export-transcript
description: Export a clean transcript from a Descript project in the user's preferred format (Markdown, plain text, HTML, RTF, or DOCX).
---

# Export Transcript

Use this skill when the user wants a written transcript of their edited media.

## Steps

1. Confirm the project_id and desired format. Default to Markdown with speaker labels.
2. Use the Descript API transcript export (the MCP server may handle this via `run_agent` or a direct export tool if available).
3. Present the transcript content to the user.
4. Offer to save it as a file in the project directory.

## Supported formats

| Format | Use case |
|--------|----------|
| markdown | Blog posts, show notes, documentation |
| txt | Simple plain text, captions |
| html | Web publishing |
| rtf | Word processing |
| docx | Microsoft Word documents |

## Default options

- Speaker labels: show on speaker change
- Timecodes: off (unless requested)
- Markers: off (unless requested)

What does this skill do?

The Supported formats table gives Codex a menu of output types. When a user asks for "a transcript for my blog", Codex can match that to the markdown format without the user needing to know the exact keyword.

The Default options section prevents Codex from guessing. It always includes speaker labels and leaves timecodes off unless explicitly requested.

  • Save SKILL.md.
  • Verify your full skills directory by running:
ls .agents/skills

You should see three folders listed: clean-audio, export-transcript, and import-episode.

Missing one of the skill folders?

Double-check that you ran mkdir from inside the podcast-agent folder (not from a parent or child directory). If a folder is missing, create it again with the exact path.

Help me fix my skills directory structure.

✔️ Awesome, I've got everything!

Great. Make sure both files are saved before moving on to the pipeline test.

ⓧ I'd like to double check the full code

Here is the complete clean-audio/SKILL.md:

---
name: clean-audio
description: Remove filler words and apply Studio Sound to improve audio quality in a Descript project. Optionally adds captions.
---

# Clean Audio

Use this skill when the user wants to clean up a podcast or video's audio quality.

## Steps

1. Confirm you have the project_id from a previous import (or ask the user).
2. Use the `run_agent` MCP tool with this prompt:
   "Remove all filler words from the transcript. Apply Studio Sound to improve audio quality. Add captions."
3. Wait for the job to complete (auto-polls with exponential backoff).
4. Report what was accomplished:
   - Filler words removed
   - Studio Sound applied
   - Captions added
   - AI credits used (from job result)

## Customization

The user may request partial operations:
- "Just remove filler words" - omit Studio Sound and captions from the prompt
- "Add captions only" - omit filler word removal and Studio Sound
- "No captions" - remove captions from the prompt

Adjust the `run_agent` prompt accordingly.

And here is the complete export-transcript/SKILL.md:

---
name: export-transcript
description: Export a clean transcript from a Descript project in the user's preferred format (Markdown, plain text, HTML, RTF, or DOCX).
---

# Export Transcript

Use this skill when the user wants a written transcript of their edited media.

## Steps

1. Confirm the project_id and desired format. Default to Markdown with speaker labels.
2. Use the Descript API transcript export (the MCP server may handle this via `run_agent` or a direct export tool if available).
3. Present the transcript content to the user.
4. Offer to save it as a file in the project directory.

## Supported formats

| Format | Use case |
|--------|----------|
| markdown | Blog posts, show notes, documentation |
| txt | Simple plain text, captions |
| html | Web publishing |
| rtf | Word processing |
| docx | Microsoft Word documents |

## Default options

- Speaker labels: show on speaker change
- Timecodes: off (unless requested)
- Markers: off (unless requested)
Test the full pipeline

The real power of skills is chaining them. Your AGENTS.md already tells Codex when to use each skill. Now you'll test whether Codex can chain $clean-audio and $export-transcript in sequence on the demo episode you imported earlier.

  • Switch back to the Codex app with your podcast-agent project open.
  • Open a new thread by clicking the + button or starting a new conversation.
  • Type this prompt and send it:
Run $clean-audio on the Podcast Agent Demo project, then $export-transcript in Markdown format.

What should I see?

Codex should recognize both skill names and execute them in order. First it will use the run_agent MCP tool to clean the audio (removing filler words, applying Studio Sound, adding captions). Then it will export the transcript in Markdown format with speaker labels.

Each job may take 30 seconds to a few minutes depending on the media length. The MCP server auto-polls with exponential backoff so you do not need to manually check status.

  • Wait for Codex to finish both operations. Confirm that Codex reports filler words removed, Studio Sound applied, and captions added from the clean-audio step.
  • Confirm that Codex presents a Markdown transcript with speaker labels from the export step.

Codex not recognizing the skill names?

Make sure the name field in each SKILL.md frontmatter matches exactly what you type in the prompt. The skill name clean-audio is triggered by $clean-audio in your message.

Also verify that your project folder structure is correct. The skill files must live at .agents/skills/clean-audio/SKILL.md and .agents/skills/export-transcript/SKILL.md relative to the project root.

Help me debug why Codex isn't finding my skills.

You now have a three-skill editing pipeline that can import, clean, and export any podcast episode through natural language. Next up, you'll create a custom subagent that can batch-process multiple episodes at once.

Create a Batch Editor Subagent

Your three skills handle individual episodes cleanly, but what about processing an entire batch of episodes at once? Doing them one by one means repeating the same prompts over and over.

Codex supports custom subagents that specialize in a single task. In this step, you'll create a batch_editor subagent that processes multiple episodes sequentially through the full editing pipeline without you having to babysit each one.

In this step, get ready to:
  • Create the batch-editor.toml subagent definition file.
  • Configure the subagent's processing instructions.
  • Test batch processing by delegating multiple episodes to the subagent.
Create the batch editor subagent file

Codex discovers custom subagents by reading TOML files inside the .codex/agents/ directory. Each file defines a single subagent with its own name, model, and instructions.

  • Create the agents subdirectory inside your existing .codex folder by running this command in PowerShell:
mkdir .codex/agents
  • Create a new file called batch-editor.toml inside .codex/agents/ and add the following metadata:
name = "batch_editor"
description = "Processes multiple podcast episodes sequentially through the full editing pipeline. Use when 2+ episodes need the same treatment."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

What does this configuration do?

  • name is the identifier Codex uses when spawning or referring to this subagent.
  • description tells Codex when this subagent is appropriate to use.
  • model = "gpt-5.4-mini" selects a faster, lower-cost model ideal for repetitive batch work that favors speed over depth.
  • model_reasoning_effort = "medium" keeps reasoning balanced. The batch editor follows a fixed pipeline, so it doesn't need high reasoning effort.

Why a subagent instead of just prompting skills directly?

Skills are reusable instructions, but you still need to prompt them one at a time. A subagent is a specialized worker that Codex delegates to.

The main Codex thread stays free while the batch_editor handles the repetitive work. This separation keeps your primary thread focused on decisions and the subagent focused on execution.

You won't see a change yet. The next chunk completes the file with the actual processing instructions.

Write the developer instructions

The developer_instructions field is the core behavior definition for your subagent. It tells the batch editor exactly how to process each episode and what to report when finished.

  • Add the following developer_instructions field below the model_reasoning_effort line in batch-editor.toml:
developer_instructions = """
You are a batch podcast editor. Process episodes one at a time through the full pipeline.

For each episode:
1. Import the media using the import_media tool
2. Wait for import to complete
3. Run audio cleanup (remove filler words, apply Studio Sound, add captions) using run_agent
4. Wait for editing to complete
5. Record the project URL and move to the next episode

Track progress as a numbered list. After all episodes are processed, report:
- Total episodes processed
- All project URLs
- Any failures with error details

Process sequentially to respect rate limits. Do not attempt parallel imports.
"""

What does this code do?

  • The triple-quote """ syntax in TOML allows multi-line strings.
  • The numbered steps give the subagent a strict per-episode pipeline: import, wait, clean, wait, record.
  • The reporting section ensures you get a summary of all project URLs and any errors at the end.
  • The sequential constraint prevents hitting Descript API rate limits by processing one episode at a time.
  • Save batch-editor.toml.
  • Confirm the file exists by running:
ls .codex/agents/

You should see batch-editor.toml listed in the output.

Don't see the file?

  • Make sure you created the agents directory inside .codex/ (not at the project root).
  • Check that you saved the file with the .toml extension, not .txt.
  • The correct path from your project root is .codex/agents/batch-editor.toml.

Still stuck? Help me find why my batch-editor.toml isn't showing up in .codex/agents/

✔️ Awesome, I've got everything!

Great. Make sure you've saved batch-editor.toml before moving on.

ⓧ I'd like to double check the full code

Here's the complete batch-editor.toml file:

name = "batch_editor"
description = "Processes multiple podcast episodes sequentially through the full editing pipeline. Use when 2+ episodes need the same treatment."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"

developer_instructions = """
You are a batch podcast editor. Process episodes one at a time through the full pipeline.

For each episode:
1. Import the media using the import_media tool
2. Wait for import to complete
3. Run audio cleanup (remove filler words, apply Studio Sound, add captions) using run_agent
4. Wait for editing to complete
5. Record the project URL and move to the next episode

Track progress as a numbered list. After all episodes are processed, report:
- Total episodes processed
- All project URLs
- Any failures with error details

Process sequentially to respect rate limits. Do not attempt parallel imports.
"""
Test the batch editor subagent

Codex doesn't spawn subagents automatically. You need to explicitly ask it to delegate work to a named subagent.

  • Open a new thread in the Codex app.
  • Type this prompt and press Enter:
Spawn the batch_editor agent to process these 3 episodes: Episode 1, Episode 2, Episode 3. Use the demo video URL for all three.

What should I see?

Codex reads the batch_editor name from your prompt and matches it to the name field in batch-editor.toml. It spawns a dedicated subagent thread that follows your developer_instructions.

You should see the subagent begin processing episodes sequentially: importing each one using the demo video URL, then running audio cleanup. The subagent reports a numbered progress list and finishes with all project URLs.

Watch as Codex delegates to the specialized batch editor and processes the three episodes one at a time.

Codex not recognizing the subagent?

  • Make sure the file is at .codex/agents/batch-editor.toml relative to your project root.
  • Verify the name field in the file reads exactly batch_editor (with an underscore, not a hyphen).
  • Your project must be trusted by Codex for it to load .codex/ layers. If you see a trust warning, accept it to allow project-scoped config.

Need more help? Why isn't Codex finding my batch_editor subagent?

Secret mission

Build a Highlight Reel Skill

Your editing pipeline imports, cleans, and exports. But what about promotion? Create a fourth skill that generates a 30-second highlight clip from any edited episode, complete with prompt templates for different contexts. Then wire it into your AGENTS.md so Codex always offers it after editing.

Clean Up Your Resources

Clean Up Your Resources

This project runs locally and uses your existing ChatGPT plan for the Codex app. Descript API usage draws from your plan's AI credits and media minutes. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

  • podcast-agent project folder on your Desktop.
  • DESCRIPT_API_TOKEN environment variable (persistent, User scope).
  • Descript MCP server entry in ~/.codex/config.toml.
  • Descript API token ("Codex Agent") in your Descript account.
  • Descript test projects created during the pipeline runs.

Keep everything running

No action needed. Choose this if you plan to keep building on the podcast agent or editing more episodes.

  • Your podcast-agent folder, environment variable, and MCP config stay in place.
  • Your Descript API token remains active and tied to your Drive.
  • The Codex app and Node.js remain installed and available for other projects.

Pause - I'll come back to this later

Remove the environment variable and MCP config to free up the connection, but keep your project files for later.

  • Remove the Descript API token environment variable by running this in PowerShell:
[System.Environment]::SetEnvironmentVariable("DESCRIPT_API_TOKEN", $null, "User")
  • Open ~/.codex/config.toml and remove the entire [mcp_servers.descript] section. Save the file.
  • Your podcast-agent folder stays on your Desktop for when you want to resume.
  • When you come back, re-create the environment variable and re-add the MCP config entry.

Delete - I don't want to use this again

Remove all project resources and start fresh. Follow each step below.

  • Delete the project folder by running this in PowerShell:
Remove-Item -Recurse -Force ~\Desktop\podcast-agent
  • Remove the Descript API token environment variable:
[System.Environment]::SetEnvironmentVariable("DESCRIPT_API_TOKEN", $null, "User")
  • Open ~/.codex/config.toml and remove the entire [mcp_servers.descript] section. Save the file.
  • Revoke the API token in Descript. Open the Descript app, press Ctrl + , to open Settings, select API tokens from the sidebar, and delete the "Codex Agent" token.
  • Delete the test projects you created in Descript. Open your Descript Drive, locate the projects (e.g. "Podcast Agent Demo"), and delete them from the project list.

Nice Work!

Nice Work!

Nice work! You've built a fully structured podcast editing agent powered by the Codex app, connected to Descript via MCP, and organized using Codex's layered agent architecture.

You've learned how to:

  • Connected the Codex app to Descript via MCP and built a root AGENTS.md with mandatory skill triggers.
  • Built three modular skills ($import-episode, $clean-audio, $export-transcript) in .agents/skills/ for reusable podcast editing workflows.
  • Created a custom batch_editor subagent in .codex/agents/ that delegates multi-episode processing to a specialized worker.
  • Created a $highlight-reel skill with reference prompt templates and wired it into the AGENTS.md as a mandatory post-edit step.

Ready to quiz yourself?