Preface

There are recurring needs like organizing meeting minutes from recorded audio, creating transcripts for podcasts, or extracting subtitles from video footage. The usual pain points lie in the workflow: you first need to find a transcription API, write a calling script, and then handle speaker diarization, output formatting, and chunking long audio files. You have to repeat this whole process for every new project.

OpenAI has included the transcribe skill in its curated Agent Skills directory. It documents when to use transcription, which model to choose by default, and how to run a workflow with speaker labeling in SKILL.md, and provides a reusable CLI. After an Agent reads this skill, it can call the OpenAI Transcription API following a fixed procedure, reducing the cost of ad-hoc script writing.

This article is organized based on the official skill’s documentation and API instructions, explaining what it is, how to install and use it, and the limitations to note during usage.

What It Is

The transcribe is an Agent Skill maintained officially by OpenAI (directory name transcribe, display name in UI: Audio Transcribe). Its source code is located at:
https://github.com/openai/skills/tree/main/skills/.curated/transcribe

Its positioning is clear: use OpenAI’s audio transcription capabilities to convert audio (and video containers with audio tracks) into text; perform speaker diarization when needed, and support providing reference audio clips for known speakers. The skill explicitly recommends using the built-in scripts/transcribe_diarize.py first, to ensure reproducible results and verifiable steps.

This type of skill follows the universal SKILL.md format, and can be installed and enabled in tools that support the Agent Skills standard, such as Codex CLI, Cursor, and Claude Code, following their respective directory conventions.

Core Features and Highlights

Combined with SKILL.md, references/api.md and the supporting CLI, the verified capabilities are as follows.

  1. Default Fast Transcription
    The default model is gpt-4o-mini-transcribe, and the default output format is plain text (--response-format text), which is suitable for getting a readable draft first.

  2. Optional Speaker Diarization
    When you need to label “who is speaking”, switch to the gpt-4o-transcribe-diarize model and set the response format to diarized_json. The official documentation states that this model is designed for conversational scenarios, and will associate speech segments with different speakers.

  3. Known Speaker Prompting (Up to 4 People)
    You can pass reference samples via --known-speaker "Name=Reference Audio Path", which will be submitted internally as a data URL. This is ideal for scenarios with relatively fixed speakers, such as interviews or regular meetings.

  4. Long Audio Chunking Strategy
    When the audio exceeds approximately 30 seconds, the skill requires retaining --chunking-strategy auto, which lets the server perform loudness normalization, then split the audio using Voice Activity Detection (VAD) before transcription.

  5. Output and Validation Conventions
    Supports text / json / diarized_json formats. The Agent workflow will validate transcription quality, speaker labels, and segment boundaries; use --out-dir when processing multiple files to avoid overwriting each other. When evaluating within the skill repository, outputs should be saved to output/transcribe/.

  6. Dependencies and API Key
    You need to install the openai Python SDK before running, and set the OPENAI_API_KEY environment variable. The skill requires that if the API key is missing, users should configure it locally on their own, and never paste the full key in the conversation.

Installation and Activation

Codex CLI

Curated skills can be installed by name via the built-in $skill-installer. Install transcribe in Codex:

$skill-installer transcribe

You can also install it via the GitHub directory path:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/transcribe

Restart Codex after installation to activate the new skill. The default user-level path is $CODEX_HOME/skills (or ~/.codex/skills if not set).

The skill documentation recommends setting the CLI path once:

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export TRANSCRIBE_CLI="$CODEX_HOME/skills/transcribe/scripts/transcribe_diarize.py"

Install dependencies (prefer uv):

uv pip install openai

If you don’t have uv:

python3 -m pip install openai

Export your API key (configure it in your local shell, do not paste it in chat):

export OPENAI_API_KEY="your-api-key"

Cursor

Cursor will automatically discover skills in the following directories: project-level .cursor/skills/, .agents/skills/; user-level ~/.cursor/skills/, ~/.agents/skills/. To maintain compatibility with other tools, it will also load .claude/skills/, .codex/skills/ and their corresponding user directories.

Place the official transcribe directory (including SKILL.md, scripts/, references/, etc.) in a path like:

.cursor/skills/transcribe/SKILL.md

Or the user-level directory:

~/.cursor/skills/transcribe/SKILL.md

After that, you can manually invoke it via the / search for transcribe in an Agent conversation. When a user explicitly asks to transcribe a recording, extract speech text, or add speaker labels to an interview or meeting, the Agent may also automatically select it based on the skill description.

Claude Code

You can place the skill in the project-level .claude/skills/transcribe/ or user-level ~/.claude/skills/transcribe/ following the same SKILL.md package structure. Refer to the current Claude Code documentation for specific triggering methods.

Note: The README of the openai/skills repository notes that this directory repository tends to be archived, and current Codex skill/plugin examples are more recommended to refer to OpenAI Plugins related documentation; but the content of the transcribe skill described in this article is still based on the SKILL.md and scripts under this curated path.

Typical Usage Examples

The following commands are from the official skill documentation or the supporting CLI’s agreed parameters.

1. Quick Transcription of a Single File to Plain Text

python3 "$TRANSCRIBE_CLI" \
  path/to/audio.wav \
  --out transcript.txt

When no additional model is specified, the default gpt-4o-mini-transcribe and text format will be used.

2. Explicitly Specify Plain Text Output

python3 "$TRANSCRIBE_CLI" \
  interview.mp3 \
  --response-format text \
  --out interview.txt

3. Meeting Recording: Speaker Diarization + Known Speakers

python3 "$TRANSCRIBE_CLI" \
  meeting.m4a \
  --model gpt-4o-transcribe-diarize \
  --known-speaker "Alice=refs/alice.wav" \
  --known-speaker "Bob=refs/bob.wav" \
  --response-format diarized_json \
  --out-dir output/transcribe/meeting

You can provide up to 4 known speakers; diarized_json must be used with gpt-4o-transcribe-diarize.

4. Trigger Example for Agents

In Agents that support this skill, you can directly state the file and target, for example:

Please transcribe ./recordings/standup.m4a into text; if multiple speakers can be identified, add speaker labels.

Or:

Transcribe this interview audio, use the reference audio refs/host.wav and refs/guest.wav for known speakers, and output diarized_json.

The Agent should follow the skill workflow: collect the path and format → confirm the OPENAI_API_KEY → call the bundled CLI → check text quality, speaker labels, and segment boundaries → make targeted adjustments if needed.

Applicable Scenarios and Notes

Suitable Scenarios

  • Converting meeting or standup recordings into meeting minute drafts
  • Creating transcripts for podcasts or interviews, with segmented output by speaker
  • Extracting speech content from mp4/webm and other audio-containing video files, as a pre-processing step for subtitles or summarization
  • Wanting Agents to follow fixed decision rules (use the mini model by default; switch to the diarize model for speaker labeling) instead of writing call parameters from scratch every time

Limitations to Clarify Before Use (from Official References and CLI)

  1. The maximum file size for a single request is 25 MB; the CLI will alert you if this limit is exceeded.
  2. Supported input formats are as officially listed: mp3, mp4, mpeg, mpga, m4a, wav, webm.
  3. The gpt-4o-transcribe-diarize model does not support prompts; the CLI will reject the --prompt parameter when this model is detected.
  4. Audio longer than approximately 30 seconds should use chunking_strategy=auto (the CLI uses auto by default).
  5. You must configure a valid OPENAI_API_KEY, and calls will incur fees from the OpenAI Transcription API; refer to the OpenAI model and billing page for specific pricing.
  6. It is recommended to manually review the transcription results for proper nouns, overlapping speech, and segments in noisy environments; the skill itself will also prompt you to validate the output before finalizing it.

Summary

The transcribe skill packages the common usage patterns of the OpenAI Transcription API into a workflow that can be discovered by Agents: use gpt-4o-mini-transcribe by default for fast output, switch to gpt-4o-transcribe-diarize and diarized_json when speaker labeling is needed, and use the bundled CLI to ensure consistent parameters and output paths. For developers who often process meeting recordings, podcasts, or video voiceovers, installing it in the skills directory of Codex / Cursor / Claude Code is more convenient than writing API requests from scratch every time.

Official address: https://github.com/openai/skills/tree/main/skills/.curated/transcribe