Передача и получение параметров в навыках

Skills не получают явные параметры, как традиционные функции; вместо этого они воспринимают входную информацию через контекст Claude.

Понимание этого механизма "неявной передачи параметров" — ключ к написанию практичных Skills.

Skills: Как получить параметры

Когда Claude читает Skill, весь контекст разговора становится параметрами Skill.

Это означает, что слова пользователя, загруженные файлы и записи истории разговора могут служить источниками входных данных для Skill.

Источники входных данных Пример Описание
Текущее сообщение пользователя "Помогите мне обработать этот PDF" Наиболее прямой вход
Загруженные файлы Пользователь загрузил report.pdf Передаётся через путь или содержимое
История разговора Ранее обсуждавшиеся форматы данных Доступно для ссылки в контексте
Системные переменные Текущая дата, путь к рабочему каталогу Автоматически воспринимается Claude

Объявление ожидаемого ввода в SKILL.md

В SKILL.md описания на естественном языке могут сообщать Claude, какую информацию извлекать из контекста.

Ниже приведён пример Skill для обработки CSV-файлов, демонстрирующий, как объявить ожидаемые входные данные в инструкциях:

Пример

---
name: csv-analyzer
description: Анализирует загруженные пользователем CSV-файлы и выводит статистические сводки. Запускается, когда пользователь упоминает CSV или анализ табличных данных.
---

# Анализатор CSV

## Требования к входным данным

Пользователь должен предоставить следующую информацию (полученную из контекста диалога):
- **Путь к файлу**: путь загруженного CSV-файла (находится в/mnt/user-data/uploads/）
- **Цель анализа**(необязательно): что пользователь хочет узнать, например"найти null-значения"、"статистическое распределение"
- **Формат вывода**(необязательно): таблица, график или текстовое резюме

Если приведённая выше информация неясна, заранее уточните её у пользователя перед выполнением.

"Требования к входным данным" в Skill написаны для самого Claude. Claude будет самостоятельно извлекать информацию из контекста на основе этой спецификации или запрашивать у пользователя уточнения, если информации недостаточно.

Получение структурированных параметров через скрипты

Когда Skill включает скрипты Python или Shell, параметры передаются через аргументы командной строки или стандартный ввод.

Это точно так же, как обработка параметров в обычных скриптах.

Пример

# Путь к файлу: scripts/analyze.py
import argparse
import pandas as pd

def main():
    # Определить аргументы командной строки
    parser = argparse.ArgumentParser(description="Скрипт анализа CSV-файла")
    parser.add_argument("file",        help="Обязательно: путь к CSV-файлу")
    parser.add_argument("--col",       help="Необязательно: укажите имя столбца для анализа")
    parser.add_argument("--limit", type=int, default=10,
                        help="Необязательно: максимальное количество строк для отображения, по умолчанию 10")
    args = parser.parse_args()

    # Прочитать файл
    df = pd.read_csv(args.file)

    # Фильтровать столбцы при необходимости
    if args.col:
        df = df[[args.col]]

    # Вывод статистической информации
    print(df.head(args.limit).to_string())
    print("\n--- Статистическая сводка ---)
    print(df.describe())

if __name__ == "__main__":
    main()

Как Claude вызывает этот скрипт в SKILL.md:

Пример

## Выполнить анализ

После получения пути к файлу выполните следующую команду:

```bash
python scripts/analyze.py <Путь к файлу> [--col <Имя столбца>] [--limit <Количество строк>]
```

Отобразите пользователю вывод командной строки и предоставьте текстовую интерпретацию.

Спецификации обработки параметра пути к файлу

Загруженные пользователем файлы единообразно располагаются по пути/mnt/user-data/uploads/.

В скриптах Skill всегда используйте абсолютные пути для доступа к файлам, чтобы избежать ошибок разрешения путей.

Пример

import os

# Правильно: используйте абсолютный путь
UPLOAD_DIR = "/mnt/user-data/uploads"
file_path = os.path.join(UPLOAD_DIR, "report.csv")

# Неправильно: использование относительного пути (приведёт к ошибке из-за разных рабочих каталогов)
# file_path = "uploads/report.csv"

# Проверить, существует ли файл
if not os.path.exists(file_path):
    print(f"Ошибка: файл не существует → {file_path}")
    exit(1)

Проверка параметров: проверка входных данных перед выполнением

Перед выполнением скрипты Skill всегда должны проверять, что ключевые параметры допустимы.

Это предотвращает сбои во время выполнения, вызванные отсутствующими параметрами или ошибками формата.

Пример

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

def validate_csv_input(file_path: str) -> bool:
    """Проверить, является ли входной CSV-файл допустимым"""

    # Проверить, указан ли путь к файлу
    if not file_path:
        print("Ошибка: путь к файлу не указан")
        return False

    # Проверить, существует ли файл
    if not os.path.exists(file_path):
        print(f"Ошибка: файл не существует → {file_path}")
        return False

    # Проверить расширение файла
    if not file_path.lower().endswith(".csv"):
        print(f"Ошибка: тип файла не поддерживается, ожидается .csv, фактически → {file_path}")
        return False

    # Проверка размера файла (предупреждение при превышении 100MB)
    size_mb = os.path.getsize(file_path) / (1024 * 1024)
    if size_mb > 100:
        print(f"Предупреждение: файл большой ({size_mb:.1f} MB), обработка может быть медленной")

    return True

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Использование: python validate_input.py <путь к файлу>")
        sys.exit(1)

    ok = validate_csv_input(sys.argv[1])
    sys.exit(0 if ok else 1)

Сообщения об ошибках валидации параметров должны чётко указывать, что ожидалось и что было фактически получено, чтобы Claude мог легко предоставить пользователю конкретные причины.

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