Agent Skills 从入门到工程化（四）：Skill 的输入输出应该怎么设计？

Skill 输入输出设计决定了 Agent 能不能正确调用也决定了调用结果能不能继续使用。很多工具调用失败并不是模型太差而是参数设计太模糊、返回结果不可解析。输入要结构化不要把所有内容塞进一个input字段。结构化输入可以减少歧义。不推荐{input:帮我搜索最近一周 AI Agent 的新闻返回 5 条}推荐{query:AI Agent 新闻,time_range:past_week,max_results:5}结构化参数更容易校验、记录日志和复用。区分必填和可选Skill 应该明确哪些参数必须提供哪些可以默认。例如天气查询{required:[city,date],optional:[unit]}如果缺少 cityAgent 应该追问用户或者根据用户位置推断而不是强行调用。使用枚举和值域限制如果参数只能取固定值就应该使用枚举。{time_range:{type:string,enum:[past_day,past_week,past_month,any]}}如果是数字要设置范围。例如max_results可以限制在 1 到 10。输出要统一结构推荐所有 Skill 使用统一输出结构{status:success | failed | empty_result | partial_success,data:{},error:null,metadata:{}}统一结构能让 Agent 和 Workflow 方便判断下一步。status 要明确不要让 Agent 从一段自然语言里猜调用是否成功。状态应该显式表达success成功 failed失败 empty_result无结果 partial_success部分成功 need_clarification需要补充信息 permission_denied权限不足这样 Agent 可以决定继续、重试、追问或终止。error 要可处理错误不能只写“出错了”应该包含错误类型和是否可重试。{error:{type:timeout,message:外部服务请求超时,retryable:true}}常见错误类型包括missing_parameter、invalid_parameter、timeout、permission_denied、empty_result、external_api_error。metadata 方便排查metadata 可以记录耗时、版本、request_id、provider 等信息。{metadata:{latency_ms:832,skill_version:1.1.0,request_id:abc123}}这些信息不一定展示给用户但对排查和监控很重要。面试中怎么回答可以这样回答输入方面我会使用结构化 schema明确必填参数、可选参数、类型、默认值、枚举和值域避免只有一个 input 字段。输出方面我会统一返回 status、data、error、metadata。status 让 Agent 知道调用状态data 放正常结果error 放错误类型和是否可重试metadata 放耗时、版本、request_id 等信息。这样 Agent 可以根据结果决定继续推理、重试、追问用户或终止任务。小结这篇文章的核心是Skill 的输入输出应该怎么设计不是一个孤立概念而是 Agent 工程化中必须讲清楚、设计清楚、验证清楚的一部分。下一篇继续讨论如何写好 Skill 的名称和描述。