How to Debug Issues with Custom Skills: A Complete Troubleshooting Guide

Debug custom skills by validating metadata with quick_validate.py, adding explicit logging to Python scripts, and inspecting runtime tracebacks in a local sandbox.

Custom skills in the anthropics/skills repository are self-contained folders that Claude loads at runtime. When you need to debug issues with custom skills, problems can originate in metadata validation, Python execution, document processing, or external dependencies. This guide provides a systematic workflow to isolate and resolve these failures using the repository's built-in validators and logging patterns.

Common Debugging Areas for Custom Skills

Before diving into specific fixes, identify where your symptom originates. Custom skills typically fail in one of these five areas:

Area	Typical Symptom	Where to Look
Skill metadata	SKILL.md fails to load; skill is ignored	Front-matter validation in skills/skill-creator/scripts/quick_validate.py
Python scripts	Exceptions, wrong output, missing dependencies	Runtime traceback, added print/logging statements
Document validators (PDF, DOCX, PPTX, XLSX)	Corrupted file, missing assets, validation failures	validators/* modules under each document skill
Web-app testing	Playwright hangs, UI not found, screenshots empty	webapp-testing/SKILL.md and Playwright logs
MCP builder	Server crashes, missing connections	mcp-builder/reference/python_mcp_server.md logging helpers

Step-by-Step Workflow to Debug Custom Skills

Follow this sequence to isolate whether the problem lies in metadata, script execution, external tools, or the runtime environment.

Validate the SKILL.md Front-Matter

The repository ships a minimal validator in skills/skill-creator/scripts/quick_validate.py that checks required fields (name, description) and enforces naming conventions used by the Agent Skills spec.

Run the validator from the repository root:

python skills/skill-creator/scripts/quick_validate.py path/to/your/skill

What to expect:

• Success → Skill is valid! indicates well-formed metadata.
• Failure → The validator prints a clear error (e.g., missing name, illegal characters).

Source: [quick_validate.py](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/quick_validate.py).

Run the Skill's Own Validator

Many document-processing skills (PDF, DOCX, PPTX, XLSX) include a validate.py script that runs schema validators before heavy processing.

python skills/pdf/scripts/validate.py my-document.pdf

If the validator exits with a non-zero code, inspect the printed messages. They often point to missing dependencies or malformed inputs.

Source examples:

• PDF: [skills/pdf/scripts/validate.py](https://github.com/anthropics/skills/blob/main/skills/pdf/scripts/validate.py)
• DOCX: [skills/docx/scripts/validate.py](https://github.com/anthropics/skills/blob/main/skills/docx/scripts/validate.py)

Add Explicit Logging to Python Code

When a script raises an exception, the stack trace may be hidden inside Claude’s sandbox. Insert logging that writes to stdout (or to a file if you run the script locally) to capture what happened.

import logging

logging.basicConfig(level=logging.DEBUG, format="%(asctime)s %(levelname)s %(message)s")
logger = logging.getLogger(__name__)

def my_function(arg):
    logger.debug("Entered my_function with arg=%s", arg)
    # ... your logic ...

    logger.info("Completed processing")

MCP builder already provides helpers that prepend timestamps and severity levels (ctx.log_debug, ctx.log_info, etc.).

Source: [python_mcp_server.md](https://github.com/anthropics/skills/blob/main/skills/mcp-builder/reference/python_mcp_server.md).

Inspect Playwright Logs for Web-App Testing Skills

If your skill drives a UI with Playwright (see skills/webapp-testing), enable the built-in logger:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()
    page = context.new_page()
    page.on("console", lambda msg: print(f"[console] {msg.text}"))
    page.on("pageerror", lambda exc: print(f"[error] {exc}"))
    # …run your interactions…

Captured console messages, network errors, and screenshot files will appear in the skill’s logs/ folder (if you create one). The skill’s README (skills/webapp-testing/SKILL.md) lists standard debugging flags (--debug, --headless false).

Source: [webapp-testing/SKILL.md](https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md).

Use Reference Debug Sections in Document Skills

Many document-processing skills embed a "debug" heading that shows how to visualize intermediate structures:

• PDF – skills/pdf/reference.md explains how to dump the layout tree as an image (img.save("debug_layout.png")).
• DOCX / PPTX / XLSX – Validator modules (validators/base.py) expose a repair() method that prints a summary of fixes applied.

Sources:

• PDF debugging snippet: [pdf/reference.md line 327‑382](https://github.com/anthropics/skills/blob/main/skills/pdf/reference.md#L327-L382).
• Base validator implementation: [skills/pdf/scripts/office/validators/base.py](https://github.com/anthropics/skills/blob/main/skills/pdf/scripts/office/validators/base.py).

Re-Run the Skill in a Local Sandbox

Most skills can be executed directly from the command line (e.g., python script.py …). Doing so lets you see the full traceback and interactively step through the code with a debugger like pdb:

python -m pdb path/to/your/skill/scripts/your_script.py <args>

If the skill depends on external binaries (e.g., qpdf, pdftotext), verify they are on the PATH and check their version numbers (qpdf --version). Incompatible versions often cause silent failures.

Verify the Folder Structure

A custom skill should contain only the three top-level directories described in the template:

• scripts/ – executable code (Python, Bash, etc.)
• references/ – large docs that Claude reads but does not load into context
• assets/ – files that Claude copies into the final output (templates, fonts, images)

If you accidentally placed a heavy binary inside scripts/, Claude may refuse to load the skill because of size limits. Move such files to assets/ and re-run the validator.

Template source: [template/SKILL.md](https://github.com/anthropics/skills/blob/main/template/SKILL.md).

Practical Debugging Examples

Example 1 – Running the Built-In Validator

# From the repository root

python skills/skill-creator/scripts/quick_validate.py ./skills/pdf

# Expected output

# ✅ Skill 'pdf' initialized successfully …

Example 2 – Adding a Logger to a Custom Script

# skills/my-custom-skill/scripts/process.py

import logging, sys
logging.basicConfig(stream=sys.stdout, level=logging.DEBUG,
                    format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger(__name__)

def main(input_path):
    log.debug("Processing %s", input_path)
    # Your logic here

    log.info("Finished processing %s", input_path)

if __name__ == "__main__":
    main(sys.argv[1])

Run it locally to see the debug output:

python skills/my-custom-skill/scripts/process.py data/input.txt

Example 3 – Capturing Playwright Console Output

# skills/webapp-testing/scripts/run_test.py

from playwright.sync_api import sync_playwright

def run():
    with sync_playwright() as pw:
        browser = pw.chromium.launch(headless=False)  # turn off headless for visual debugging

        ctx = browser.new_context()
        page = ctx.new_page()

        page.on("console", lambda msg: print("[Console]", msg.text))
        page.on("pageerror", lambda exc: print("[Error]", exc))

        page.goto("https://example.com")
        # …interact with the page…

        page.screenshot(path="debug_screenshot.png")
        print("Saved screenshot to debug_screenshot.png")

if __name__ == "__main__":
    run()

Example 4 – Visualising PDF Layout for Debugging

# Inside a PDF script (see pdf/reference.md)

import pdfplumber
from pathlib import Path

pdf_path = Path("sample.pdf")
with pdfplumber.open(pdf_path) as pdf:
    page = pdf.pages[0]
    layout = page.to_image()
    layout.debug()                     # draws bounding boxes

    layout.save("debug_layout.png")    # writes the image to disk

print("Layout image saved as debug_layout.png")

Key Files for Debugging Custom Skills

File	Role	Link
skills/skill-creator/scripts/quick_validate.py	Minimal front-matter validator used for every custom skill	quick_validate.py
skills/skill-creator/scripts/init_skill.py	Generates a new skill from the template; includes a "run validator" tip	init_skill.py
skills/pdf/scripts/validate.py (and siblings for DOCX, PPTX, XLSX)	Executes document-specific validators; prints repair actions	pdf/validate.py
skills/pdf/scripts/office/validators/base.py	Base class for schema validators; contains repair() and validate() logic	base.py
skills/webapp-testing/SKILL.md	Describes the Playwright-based testing skill and its debug flags	webapp-testing SKILL.md
skills/mcp-builder/reference/python_mcp_server.md	Shows how to use ctx.log_debug/info/error in MCP builder scripts	python_mcp_server.md
template/SKILL.md	Official skill folder layout (scripts/, references/, assets/)	template SKILL.md
skills/pdf/reference.md (debug section)	Example of visual debugging for PDF layout extraction	pdf/reference.md debug section

Summary

• Validate metadata first using skills/skill-creator/scripts/quick_validate.py to catch front-matter errors before runtime.
• Add explicit logging to Python scripts using the standard logging module or MCP builder's ctx.log_debug helpers to expose hidden tracebacks.
• Run validators locally for document skills (PDF, DOCX, PPTX, XLSX) using their respective validate.py scripts to identify schema violations.
• Capture Playwright logs for web-app testing skills by attaching console and page error listeners before interactions.
• Verify folder structure against the template (scripts/, references/, assets/) to prevent size limit violations that prevent skill loading.

Frequently Asked Questions

Why is my custom skill not appearing in Claude's skill list?

If Claude ignores your skill, the SKILL.md front-matter likely fails validation. Run python skills/skill-creator/scripts/quick_validate.py path/to/your/skill to check for missing name or description fields, or illegal characters in the skill name. Also verify that heavy binaries are not placed in scripts/, as this can cause the skill to exceed size limits and fail to load.

How do I see the full error traceback when a skill script crashes inside Claude?

Claude's sandbox may hide full stack traces. To debug issues with custom skills effectively, add explicit logging that writes to stdout using Python's logging module, or run the script locally with python -m pdb path/to/script.py to step through execution interactively. For MCP builder skills, use ctx.log_debug() and ctx.log_error() helpers defined in skills/mcp-builder/reference/python_mcp_server.md.

What should I check when document processing skills fail on valid-looking files?

Document-oriented skills (PDF, DOCX, PPTX, XLSX) include specific validators that catch corrupted files or missing assets before processing. Run the appropriate validator script (e.g., python skills/pdf/scripts/validate.py my-document.pdf) to see detailed schema violations. For visual debugging of PDF layouts, use the layout.debug() and layout.save() methods shown in skills/pdf/reference.md to render bounding boxes as images.

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