先跑一遍本地示例看输出目录——ip-as-logo-skill 的入门路径

装好 ip-as-logo-skill 之后，最省事的起点不是先把参数研究透，而是用一次最小的输入生成一张头像，然后立刻去看产物落在哪个目录、叫什么名字。这一步同时确认两件事：调用链是否真的通，以及产物默认写到哪里。只有这两件事确定了，再去考虑批量处理才是有意义的；如果连输出目录都没看过，批量跑完往往连文件在哪儿都不知道。

先跑一张头像的意义不在于拿到图，而在于确认三件事：Agent 实际调用的是哪个入口文件、依赖是否齐全、产物默认落到哪个目录。适用场景是刚装好 skill、还没决定要不要批量处理；动作上只做一次最小调用，再用目录列表核对命名、格式与尺寸；验证方式是同一输入能稳定落在同一路径。若输出目录指向不可写位置或临时目录，批量会先在权限上卡住，需要结合环境确认后再改配置。

按所用 Agent 的 skill 目录约定核对入口文件和依赖

不同 Agent 对 skill 的目录约定不一样，但对使用者来说要找的东西是固定的三样：入口、依赖、输出。先用一条命令把目录结构打出来，再对着下面这份占位符树去对号入座。名字全部用占位符，实际名称以你本地为准。

<skill_root>/                    # skill 所在目录，名称由你的 Agent 约定决定
├── <entry_file>                 # 【入口】Agent 实际读取或执行的文件
├── <manifest_or_readme>         # 调用方式与字段说明，常见为 SKILL.md / README 之类
├── <dependency_file>            # 【依赖】requirements / package / pyproject 之类
├── <scripts_or_src>/            # 实际逻辑代码
└── <output_dir>/                # 【输出】默认产物目录，可能被调用参数覆盖

需要确认的三个位置：入口要确认清楚「Agent 读的是描述文件，还是描述文件里指向的那个脚本」，两者常常不在同一层，路径写错时表现是 skill 能被识别但不执行；依赖要确认有没有依赖清单、运行时是否需要额外安装包或读取环境变量，缺依赖通常不在第一次调用时就报错，而是在跑到生成那一步才炸；输出要确认默认目录是相对路径还是绝对路径、相对谁解析，以及能否用参数改到别处。这三处确认完，再执行一次调用心里才有底。

用最小调用骨架生成第一张头像

第一次调用建议只给必填输入，其余全部保持默认，把变量控制到最少。字段名不要照抄任何未验证的名字，下面只是骨架，尖括号部分替换成你本地声明的实际字段。

# 通用调用骨架，字段名以你的 skill 实际声明为准
<input_ip>    = "<待转换的 IP 或标识>"     # 必填，决定生成图形的内容
<output_size> = <边长，像素>                # 可选，留空则用 skill 默认值
<output_dir>  = "<输出目录的绝对路径>"        # 建议第一次显式写死，方便核对

<run> <entry_file> \
  --<ip 字段>   "<input_ip>" \
  --<尺寸字段> "<output_size>" \
  --<输出字段> "<output_dir>"

每个字段填什么：IP 字段填这次要转换的那个地址或等价标识；尺寸字段如果 skill 支持就填一个你能一眼认出来的边长，方便后面核对，不支持就整行删掉；输出字段第一次不要省，显式写一个空目录的绝对路径，这样产物只会出现在一个地方。如果这个 skill 是由 Agent 用自然语言触发的，而不是命令行，把上面三个字段写成一句话即可，例如「用 <input_ip> 生成一张头像，保存到 <output_dir>」。不管哪种形式，第一次只跑一张，不要顺手加上批量或者循环。

在输出目录里核对文件名、格式与尺寸

调用返回成功不等于产物能用。生成之后先把这个目录列一遍，并把结果记下来，作为后面排查和批量的基线。

ls -l <output_dir>
find <output_dir> -maxdepth 1 -type f
file   <output_dir>/<生成的文件名>

要看的三个属性：命名规则，是固定名、IP 派生名还是时间戳名，是否可复现——如果同一个输入两次生成出两个名字，批量时就要考虑覆盖和去重；文件格式，不要只看扩展名，用 file 或读取文件头确认扩展名与实际编码一致，这是后面接其他流程时最容易出问题的地方；图像尺寸，用 identify 之类的工具或直接读图片头信息，确认输出是否等于你传入的边长，还是被 skill 内部规整过。工具不一定装了，没装就先看前两项，尺寸可以留到接入下游时再确认。

生成失败时按入口、依赖、输出路径三段排查

报错信息通常能直接指到三段中的一段，按下面顺序看，比反复重试有效。

入口段：观察 Agent 是否识别到了这个 skill、入口文件路径是否写错、执行时的工作目录是不是你以为的那个。典型报错是 command not found、No such file or directory、skill 未被加载或触发词没匹配上。
依赖段：观察依赖清单里的包是否都装上了、是否需要额外的运行环境或环境变量。典型报错是 ModuleNotFoundError、ImportError、找不到某个包、缺少凭据或配置项。
输出段：观察输出目录是否存在、当前用户是否有写权限、路径是否被当成相对路径解析到了别处。典型报错是 Permission denied、无法创建目录、写入中断。

有一段容易混：No such file or directory 在入口段和输出段都会出现。区分办法是看报错里给出的那个路径——指向的是入口文件所在目录，就归入口段；指向的是你传进去的输出目录，就归输出段。先把这三段排掉，再回头怀疑参数本身。