Skills 参数传递与接收

Skills 不像传统函数那样接收显式参数，它通过 Claude 的上下文来感知输入信息。

理解这种"隐式参数传递"机制，是写出实用 Skill 的关键。

---

Skills 如何获取参数

当 Claude 读取一个 Skill 后，整个对话上下文就是这个 Skill 的参数。

这意味着用户说的话、上传的文件、历史对话记录，都可以成为 Skill 的输入来源。

输入来源	示例	说明
用户当前消息	"帮我处理这份 PDF"	最直接的输入
上传的文件	用户上传了 report.pdf	通过路径或内容传入
历史对话	之前讨论过的数据格式	上下文中可引用
系统变量	当前日期、工作目录路径	Claude 自动感知

---

在 SKILL.md 中声明期望输入

SKILL.md 中可以通过自然语言描述，告诉 Claude 需要从上下文中提取哪些信息。

以下是一个处理 CSV 文件的 Skill 示例，演示如何在指令中声明输入预期：

实例

---

name: csv-analyzer

description: 分析用户上传的 CSV 文件，输出统计摘要。当用户提到 CSV、表格数据分析时触发。

---

# CSV 分析器

## 输入要求

用户应提供以下信息（从对话上下文中获取）：

- **文件路径**：已上传 CSV 文件的路径（位于 /mnt/user-data/uploads/）

- **分析目标**（可选）：用户希望了解什么，如"找出空值"、"统计分布"

- **输出格式**（可选）：表格、图表或文字摘要

若上述信息未明确，主动向用户确认后再执行。

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 向用户反馈具体原因。

AI 思考中...

VS Code 创建与使用 Skill

Skills 触发机制