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

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. For example, the debug-zoom skill defined in 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, 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.

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, 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.

{
  "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.

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, determines whether a failure is reproducible or transient by replaying stored event IDs and timestamps.

# 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. 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, 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. 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.

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

Integrate the observability skill from 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}