用途:为在技能中打包可执行脚本提供规范,适用于需要重复使用同一段代码、要求确定性可靠性、需要复杂校验,或生成代码的 token 成本高于执行成本的场景。
主要能力与规范:
- 错误处理:显式处理错误而非直接抛给模型,例如捕获 FileNotFoundError 后创建文件,捕获 PermissionError 后打印错误并返回 None。
- 常量说明:每个魔法数字都要写明理由,如 TIMEOUT = 30 表示 HTTP 请求通常 30 秒完成,MAX_RETRIES = 3 表示多数失败在第二次重试后解决。
- 意图说明:在 SKILL.md 中明确脚本是执行还是仅作参考,例如“运行 scripts/analyze.py 提取 PDF 表单字段”或“参见 scripts/analyze.py 的提取算法(不要直接运行)”。
- 组织方式:技能目录包含 SKILL.md 与 scripts/,主入口 analyze.py、校验工具 validate.py、共享工具 helpers/formatting.py 与 parsing.py。
- 依赖声明:显式列出依赖,如 pip install pdfplumber python-docx,或 pip install -r scripts/requirements.txt。
- 退出码:使用一致约定,EXIT_SUCCESS = 0、EXIT_INVALID_INPUT = 1、EXIT_FILE_NOT_FOUND = 2、EXIT_PERMISSION_ERROR = 3。
- 输出格式:输出可解析的结构化结果,如用 json.dumps 输出 status、files_processed、errors。
- 幂等性:脚本应可安全重复运行,如 os.makedirs(path, exist_ok=True)、仅在内容变化时写入。
限制:资料未提供具体平台支持范围、版本要求或性能数据。