Отладка навыков

После написания навыка вы часто сталкиваетесь с такими проблемами, как «не срабатывает», «ошибка выполнения» или «неверный вывод».

В этой статье описываются основные подходы и методы устранения этих проблем.

Три распространённых типа проблем отладки

Тип проблемы Симптом Проверка приоритета
Не срабатывает Claude вообще не использует навык формулировка описания, сложность задачи
Сработал, но произошла ошибка выполнения Навык считывается, но скрипт не запускается Путь к скрипту, зависимости, формат параметров
Сработал и выполнился, но результат не соответствует ожиданиям Содержимое вывода отличается от ожиданий Ясность инструкций в SKILL.md

Проблема отладки 1: навык не срабатывает

Это самая распространённая проблема. Шаги по устранению неполадок следующие:

Шаг 1: убедитесь, что файл навыка загружен правильно

Пример

# Проверьте правильность структуры каталога навыка
ls -la my-skill/

# Убедитесь, что SKILL.md существует и не пуст
wc -l my-skill/SKILL.md
-rw-r--r-- 1 user user  842 May 18 10:00 SKILL.md

Шаг 2: Проверьте формат YAML Frontmatter

Неправильное форматирование frontmatter может помешать распознаванию Skill.

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

# My Skill
...

frontmatter должен---начинаться и заканчиваться с,nameиdescriptionИмена полей не должны содержать лишних пробелов, и после двоеточия должен быть один пробел.

Шаг 3: Используйте более сложные тестовые промпты

Простые задачи (например, "прочитать этот файл") могут не активировать Skill.

Измените тестовый промпт на сложный запрос с несколькими шагами и чёткими требованиями к формату вывода.

Промпты, которые с меньшей вероятностью сработают Промпты, которые с большей вероятностью сработают
"Проанализируй этот файл" "Проанализируй эти данные о продажах в формате CSV, определи помесячные тенденции роста и создай сводную статистическую表"
"Создай PPT" "На основе этого отчёта создай презентацию для представления продукта на 10 страниц с диаграммами и резюме"

Проблема 2 при отладке: Ошибки выполнения скрипта

Когда скрипт завершается с ошибкой, сообщение об ошибке появляется в выводе командной строки.

В сеансе Claude вы можете напрямую попросить Claude запустить скрипт и просмотреть вывод:

Пример

# Запустите скрипт вручную и проверьте вывод ошибок
python scripts/process.py /mnt/user-data/uploads/test.csv

# Добавьте параметр -v (verbose) для просмотра подробных логов (если скрипт это поддерживает)
python scripts/process.py /mnt/user-data/uploads/test.csv --verbose

Распространённые типы ошибок и способы их исправления

Сообщение об ошибке Причина Исправить
ModuleNotFoundError: No module named 'pandas' Зависимость не установлена Запуститеpip install pandas --break-system-packages
FileNotFoundError: [Errno 2] Неверный путь к файлу Проверьте, находится ли файл в/mnt/user-data/uploads/
PermissionError: [Errno 13] Нет разрешения на запись Измените цель вывода на/mnt/user-data/outputs/
SyntaxError Синтаксическая ошибка в скрипте использоватьpython -m py_compile 脚本名.pyПроверить

Быстрая проверка синтаксиса

Пример

# Проверка синтаксиса скрипта Python (не выполняется, только проверяет синтаксис)
python -m py_compile scripts/process.py && echo "Синтаксис верен" || echo "Синтаксическая ошибка"

# Проверка синтаксиса Shell-скрипта
bash -n scripts/run.sh && echo "Синтаксис верен" || echo "Синтаксическая ошибка"
Grammatically correct.

Проблема отладки 3: вывод не соответствует ожиданиям

Этот тип проблемы обычно возникает из-за неясных или неоднозначных инструкций в SKILL.md.

Метод устранения неполадок: постепенное сужение

Временно добавьте в SKILL.md инструкции по отладочному выводу, чтобы наблюдать за пониманием Claude на каждом шаге:

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

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

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

Типичные проблемы неоднозначности инструкций

Расплывчатые формулировки Чёткие формулировки
"Выведите результаты после завершения обработки" "Сохраните результаты в каталог /mnt/user-data/outputs/ и отобразите путь к файлу в диалоге"
"Проанализируйте данные" "Вычислите среднее, медиану и стандартное отклонение для каждого столбца и выведите их в формате таблицы Markdown"
"Сгенерируйте отчёт" "Создать HTML-файл, содержащий абзац с резюме, таблицу данных и заключение, и сохранить его в выходной каталог"

Использование print для отладки внутри скрипта

Добавление операторов print в ключевых точках скрипта — самый прямой способ устранения проблем с потоком выполнения.

Пример

# Путь к файлу: scripts/debug_example.py
import sys

def process_file(file_path: str):
    print(f"[DEBUG] Начало обработки файла: {file_path}")  # Точка отладки 1

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

    print(f"[DEBUG] Файл успешно прочитан, размер: {len(content)} bytes")  # Точка отладки 2

    lines = content.split("\n")
    print(f"[DEBUG] Всего строк: {len(lines)}")  # Точка отладки 3

    # Фактическая логика обработки
    result = [line.strip() for line in lines if line.strip()]
    print(f"[DEBUG] Допустимые строки после обработки: {len(result)}")  # Точка отладки 4

    return result

if __name__ == "__main__":
    output = process_file(sys.argv[1])
    print("\n"--- Результат обработки ---")
    for line in output[:5]:  # Отобразить только первые 5 строк
        print(line)
[DEBUG] 开始处理文件：/mnt/user-data/uploads/sample.txt
[DEBUG] 文件读取成功，大小：1024 字节
[DEBUG] 总行数：32
[DEBUG] 处理后有效行数：28

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

После завершения отладки не забудьте удалить[DEBUG]инструкции print, начинающиеся с [DEBUG], чтобы отладочная информация не примешивалась к формальному выводу.

Другие расширения