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

> Debug custom skills effectively. Learn to validate metadata, add logging, and inspect tracebacks in your local sandbox for quick troubleshooting.

- Repository: [Anthropic/skills](https://github.com/anthropics/skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Debug custom skills by validating metadata with [`quick_validate.py`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/SKILL.md) fails to load; skill is ignored | Front-matter validation in [`skills/skill-creator/scripts/quick_validate.py`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/webapp-testing/SKILL.md) and Playwright logs |
| **MCP builder** | Server crashes, missing connections | [`mcp-builder/reference/python_mcp_server.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/SKILL.md) Front-Matter

The repository ships a minimal validator in [`skills/skill-creator/scripts/quick_validate.py`](https://github.com/anthropics/skills/blob/main/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:

```bash
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/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`](https://github.com/anthropics/skills/blob/main/validate.py) script that runs schema validators before heavy processing.

```bash
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)](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)](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.

```python
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/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:

```python
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`](https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md)) lists standard debugging flags (`--debug`, `--headless false`).

*Source*: [[`webapp-testing/SKILL.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/validators/base.py)) expose a `repair()` method that prints a summary of fixes applied.

*Sources*:

- PDF debugging snippet: [[`pdf/reference.md`](https://github.com/anthropics/skills/blob/main/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)](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`:

```bash
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)](https://github.com/anthropics/skills/blob/main/template/SKILL.md).

## Practical Debugging Examples

### Example 1 – Running the Built-In Validator

```bash

# 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

```python

# 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:

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

```

### Example 3 – Capturing Playwright Console Output

```python

# 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

```python

# 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`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/quick_validate.py) | Minimal front-matter validator used for every custom skill | [quick_validate.py](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/quick_validate.py) |
| [`skills/skill-creator/scripts/init_skill.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py) | Generates a new skill from the template; includes a "run validator" tip | [init_skill.py](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/init_skill.py) |
| [`skills/pdf/scripts/validate.py`](https://github.com/anthropics/skills/blob/main/skills/pdf/scripts/validate.py) *(and siblings for DOCX, PPTX, XLSX)* | Executes document-specific validators; prints repair actions | [pdf/validate.py](https://github.com/anthropics/skills/blob/main/skills/pdf/scripts/validate.py) |
| [`skills/pdf/scripts/office/validators/base.py`](https://github.com/anthropics/skills/blob/main/skills/pdf/scripts/office/validators/base.py) | Base class for schema validators; contains `repair()` and `validate()` logic | [base.py](https://github.com/anthropics/skills/blob/main/skills/pdf/scripts/office/validators/base.py) |
| [`skills/webapp-testing/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md) | Describes the Playwright-based testing skill and its debug flags | [webapp-testing SKILL.md](https://github.com/anthropics/skills/blob/main/skills/webapp-testing/SKILL.md) |
| [`skills/mcp-builder/reference/python_mcp_server.md`](https://github.com/anthropics/skills/blob/main/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](https://github.com/anthropics/skills/blob/main/skills/mcp-builder/reference/python_mcp_server.md) |
| [`template/SKILL.md`](https://github.com/anthropics/skills/blob/main/template/SKILL.md) | Official skill folder layout (scripts/, references/, assets/) | [template SKILL.md](https://github.com/anthropics/skills/blob/main/template/SKILL.md) |
| [`skills/pdf/reference.md`](https://github.com/anthropics/skills/blob/main/skills/pdf/reference.md) (debug section) | Example of visual debugging for PDF layout extraction | [pdf/reference.md debug section](https://github.com/anthropics/skills/blob/main/skills/pdf/reference.md#L327-L382) |

## Summary

- **Validate metadata first** using [`skills/skill-creator/scripts/quick_validate.py`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/skills/pdf/reference.md) to render bounding boxes as images.