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/）
- **分析目标**（可选）：用户希望了解什么，如"找出空值"、"统计分布"
- **输出格式**（可选）：表格、图表或文字摘要
若上述信息未明确，主动向用户确认后再执行。
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()
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 <行数>]
```
将命令行输出展示给用户，并提供文字解读。
获取文件路径后，运行以下命令：
```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)
# 正确：使用绝对路径
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)
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 向用户反馈具体原因。