Skills 调试

Skill を書き終えた後、よく「トリガーされない」「実行エラー」「出力が正しくない」といった問題に遭遇します。

この記事では、これらの問題を調査・解決するための基本的な考え方と方法を紹介します。

デバッグの3つのよくある問題

问题类型 现象 优先排查点
未触发 Claude がまったく Skill を使用していない description の書き方、タスクの複雑さ
トリガーされたが実行エラー Skill は読み取られたが、スクリプトの実行に失敗しました スクリプトのパス、依存関係、パラメータ形式
トリガーされて実行されたが、結果が期待どおりではない 出力内容が期待と異なる SKILL.md の指示の明確さ

デバッグ問題その1: Skill がトリガーされない

これは最も一般的な問題です。調査手順は以下の通りです：

ステップ1: Skill ファイルが正しくロードされていることを確認する

实例

# Skill のディレクトリ構造が正しいか確認する
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フィールド名に余分なスペースを入れないでください。コロンの後にはスペースが1つ必要です。

ステップ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 "语法错误"
構文は正しい

デバッグ問題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)} 字节")  # 调试点 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 ステートメントは、正式な出力にデバッグ情報が混ざるのを避けます。

其他扩展