# How to Debug Skill Execution in Your OpenAI Plugin: 8 Proven Methods

> Debug skill execution in your OpenAI plugin with 8 proven methods. Learn to enable debug flags, use checklists, and inspect logs to quickly isolate and fix failures.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-23

---

**To debug skill execution in your plugin, enable the debug flag in your skill configuration, follow the RUNBOOK.md pre-flight checklist, and inspect runtime artifacts in the `logs/` directory to isolate failures.**

Debugging skill execution in the `openai/plugins` repository requires a systematic workflow that leverages standardized metadata files and strict logging conventions. Whether you are troubleshooting a Zoom integration or a Vercel deployment workflow, the repository provides consistent patterns for local debugging, artifact inspection, and production observability. This guide covers the exact file paths, environment variables, and code patterns used to diagnose skill failures according to the source code.

## Local Development and SKILL.md Definitions

Every skill in the repository is defined by a **SKILL.md** file that declares the entry point, required parameters, and execution context. To debug skill execution locally, run the skill using the script referenced in its SKILL.md definition—typically a Python or Node.js file.

### Entry Points and Local Runtime

The skill's entry point is specified in the metadata of [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md). For example, the debug-zoom skill defined in [`plugins/zoom/skills/debug-zoom/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/debug-zoom/SKILL.md) provides a local execution endpoint that replicates the production environment for isolated testing.

### Console Logging Conventions

The repository enforces strict observability hooks. According to the source conventions documented in [`plugins/vercel/skills/workflow/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/workflow/SKILL.md), every step function must include `console.log` statements at entry and exit points. This guarantees that execution flow appears in the plugin's console output.

```python
def run_skill(context):
    print("[DEBUG] Enter run_skill with context:", context)
    # ... skill logic ...

    print("[DEBUG] Exit run_skill with result:", result)
    return result

```

## Pre-Flight Diagnostics with RUNBOOK.md

Before investigating complex failures, consult the skill's **RUNBOOK.md** file. This document enumerates common failure modes—including missing credentials, API scope issues, and network errors—and provides quick verification commands.

The debug-zoom skill includes [`plugins/zoom/skills/debug-zoom/RUNBOOK.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/debug-zoom/RUNBOOK.md), which serves as a pre-flight checklist to eliminate configuration errors before you attempt deep debugging of HTTP payloads or execution logic.

## Enable Debug Logging Flags

Many skills expose a debug configuration flag that routes verbose logs to the console and, for web-based skills, to the browser DevTools console.

### Configuration File Method

Set `"debug": true` in the skill's JSON configuration to enable verbose output. This pattern is implemented in [`plugins/zoom/skills/meeting-sdk/web/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/meeting-sdk/web/SKILL.md).

```json
{
  "debug": true,
  "api_key": "<YOUR_API_KEY>"
}

```

### Environment Variable Method

For Zoom-specific skills, set the `ZM_RTMS_LOG_LEVEL` environment variable to `debug` before running the skill locally. This convention is defined in [`plugins/zoom/skills/rtms/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rtms/SKILL.md).

```bash
export ZM_RTMS_LOG_LEVEL=debug
plugin run debug-zoom --debug

```

## Inspect Runtime Artifacts in the logs Directory

Skills that interact with external services persist request/response payloads to the `logs/` directory. Examine files such as `nextflow_execute.log`, `snakemake_execute.log`, or `zoom-debug.log` to see the exact HTTP payloads and API responses exchanged during execution.

This artifact inspection is critical for verifying that OAuth tokens, request headers, and payload structures match the expectations defined in your SKILL.md.

## Use Replay Endpoints for Transient Failures

The debug-zoom skill and similar debugging utilities provide a **replay** endpoint that re-executes the last successful request payload. This isolation technique, referenced in [`plugins/zoom/skills/webhooks/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/webhooks/SKILL.md), determines whether a failure is reproducible or transient by replaying stored event IDs and timestamps.

```yaml

# Example: Enabling debug mode for a Zoom skill (debug-zoom)

name: debug-zoom
description: Use when debugging issues.

# /debug-zoom $ARGUMENTS

```

## Implement Production Observability

For production-grade debugging, integrate the **observability** skill defined in [`plugins/vercel/skills/observability/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/observability/SKILL.md). This skill injects structured logging, OpenTelemetry traces, and log drains into your plugin, allowing you to trace a skill's execution across multiple distributed services.

When combined with the logging requirements in [`plugins/vercel/skills/workflow/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/workflow/SKILL.md), this integration provides complete audit trails from skill invocation through external API completion.

## Summary

- Run skills locally using their SKILL.md definitions to replicate production behavior before deploying.
- Follow the RUNBOOK.md pre-flight checklist to eliminate common credential and configuration errors.
- Enable debug flags or environment variables like `ZM_RTMS_LOG_LEVEL` to capture verbose console output.
- Inspect the `logs/` directory for HTTP request/response payloads stored by external service integrations.
- Use replay endpoints to isolate transient failures from reproducible logic errors.
- Integrate the observability skill for structured logging and cross-service tracing in production environments.

## Frequently Asked Questions

### How do I enable debug mode for a Zoom skill?

Set the environment variable `ZM_RTMS_LOG_LEVEL=debug` before running the skill locally, or set `"debug": true` in the skill's JSON configuration file as implemented in [`plugins/zoom/skills/meeting-sdk/web/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/meeting-sdk/web/SKILL.md). This routes verbose SDK logs to your console and browser DevTools.

### Where are skill execution logs stored?

Runtime artifacts and HTTP payloads are persisted in the `logs/` directory with filenames such as `zoom-debug.log`, `nextflow_execute.log`, or `snakemake_execute.log`. These files contain the exact request/response data exchanged with external APIs like Zoom or Twilio.

### What is the purpose of RUNBOOK.md in skill debugging?

RUNBOOK.md provides a pre-flight checklist of common failure modes—such as missing OAuth scopes, invalid API keys, or network timeouts—and quick verification commands to resolve configuration issues before you investigate code logic. The debug-zoom skill's runbook is located at [`plugins/zoom/skills/debug-zoom/RUNBOOK.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/debug-zoom/RUNBOOK.md).

### How can I trace skill execution across multiple services in production?

Integrate the observability skill from [`plugins/vercel/skills/observability/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/observability/SKILL.md) to inject structured logging and OpenTelemetry traces into your plugin. This enables you to follow a skill's execution path across distributed systems and correlate logs from multiple services.