Skills Debugging

After writing a Skill, you often encounter issues such as "not triggered," "execution error," or "incorrect output."

This article introduces the basic approaches and methods for troubleshooting these issues.

Three Common Types of Debugging Problems

Problem Type Symptom Priority Check
Not triggered Claude does not use the Skill at all description wording, task complexity
Triggered but execution error The Skill is read, but the script fails to run Script path, dependencies, parameter format
Triggered and executed, but the result does not match expectations Output content differs from expectations Clarity of instructions in SKILL.md

Debugging Problem 1: Skill Not Triggered

This is the most common problem. The troubleshooting steps are as follows:

Step 1: Confirm the Skill File Is Loaded Correctly

Example

# Check whether the Skill directory structure is correct
ls -la my-skill/

# Confirm SKILL.md exists and is not empty
wc -l my-skill/SKILL.md
-rw-r--r-- 1 user user  842 May 18 10:00 SKILL.md

Step 2: Check the YAML Frontmatter Format

Incorrect frontmatter formatting can prevent the Skill from being recognized.

---
name: my-skill
description: 这是一个示例 Skill，处理用户上传的文本文件。
---

# My Skill
...

frontmatter must---start and end with,nameanddescriptionField names must not have extra spaces, and there must be one space after the colon.

Step 3: Use More Complex Test Prompts

Simple tasks (such as "read this file") may not trigger the Skill.

Change the test prompt to a complex request with multiple steps and clear output format requirements.

Prompts that are less likely to trigger Prompts that are more likely to trigger
"Analyze this file" "Analyze this sales data CSV, identify monthly growth trends, and generate a statistical summary table"
"Generate a PPT" "Based on this report, create a 10-page product introduction presentation with charts and a summary"

Debugging Problem 2: Script Execution Errors

When a script errors out, the error message appears in the command-line output.

In a Claude session, you can directly ask Claude to run the script and view the output:

Example

# Manually run the script and check the error output
python scripts/process.py /mnt/user-data/uploads/test.csv

# Add the -v (verbose) parameter to view detailed logs (if the script supports it)
python scripts/process.py /mnt/user-data/uploads/test.csv --verbose

Common Error Types and Fixes

Error Message Cause Fix
ModuleNotFoundError: No module named 'pandas' Dependency not installed Runpip install pandas --break-system-packages
FileNotFoundError: [Errno 2] Incorrect file path Check whether the file is in/mnt/user-data/uploads/
PermissionError: [Errno 13] No write permission Change the output target to/mnt/user-data/outputs/
SyntaxError Script syntax error usepython -m py_compile 脚本名.pyCheck

Quick Syntax Check

Example

# Check Python script syntax (does not execute, only validates syntax)
python -m py_compile scripts/process.py && echo "Syntax is correct" || echo "Syntax error"

# Check Shell script syntax
bash -n scripts/run.sh && echo "Syntax is correct" || echo "Syntax error"
Grammatically correct.

Debugging Problem 3: Output Does Not Match Expectations

This type of problem usually stems from unclear or ambiguous instructions in SKILL.md.

Troubleshooting Method: Narrow Down Step by Step

Temporarily add debug output instructions to SKILL.md to observe Claude's understanding at each step:

## 调试模式（开发时使用，发布前删除）

执行前，先输出以下信息供确认：
1. 识别到的输入文件路径
2. 用户期望的输出格式
3. 计划执行的步骤列表

等待用户确认后再继续执行。

Common Instruction Ambiguity Issues

Vague Wording Clear Wording
"Output the results after processing is complete" "Save the results to the /mnt/user-data/outputs/ directory and display the file path in the conversation"
"Analyze the data" "Calculate the mean, median, and standard deviation of each column, and output them in Markdown table format"
"Generate a report" "Generate an HTML file containing a summary paragraph, data table, and conclusion, and save it to the output directory"

Using print for In-Script Debugging

Adding print statements at key points in the script is the most direct way to troubleshoot execution flow issues.

Example

# File path: scripts/debug_example.py
import sys

def process_file(file_path: str):
    print(f"[DEBUG] Starting to process file: {file_path}")  # Debug point 1

    with open(file_path, "r", encoding="utf-8") as f:
        content = f.read()

    print(f"[DEBUG] File read successfully, size: {len(content)} bytes")  # Debug point 2

    lines = content.split("\n")
    print(f"[DEBUG] Total lines: {len(lines)}")  # Debug point 3

    # Actual processing logic
    result = [line.strip() for line in lines if line.strip()]
    print(f"[DEBUG] Valid lines after processing: {len(result)}")  # Debug point 4

    return result

if __name__ == "__main__":
    output = process_file(sys.argv[1])
    print("\n"--- Processing result ---")
    for line in output[:5]:  # Display only the first 5 lines
        print(line)
[DEBUG] 开始处理文件：/mnt/user-data/uploads/sample.txt
[DEBUG] 文件读取成功，大小：1024 字节
[DEBUG] 总行数：32
[DEBUG] 处理后有效行数：28

--- 处理结果 ---
第一行内容
第二行内容
...

After debugging is complete, remember to delete[DEBUG]the print statements starting with [DEBUG], to avoid debug information being mixed into the formal output.

Other Extensions