用 Skill 在聊天中展示表单
把声明式表单随插件交付:本页说明清单登记和打包。若只需要独立 skill 的聊天表单,从声明式业务表单教程开始。
完成后:在聊天中触发 Skill,看到声明的表单。
前置条件:按本页具体步骤准备所需文件与工具;学习路线中的上一页不自动构成依赖。
本页内容
01选择交付方式
插件是接入业务 Operation 的交付方式;独立 skill 可以直接导入并使用 chat 提交,不要求创建插件。
先创建独立业务表单02前置条件与文件位置
先完成默认脚手架构建安装。在项目中新建 skills/intake/ 目录。这里使用单步 chat 提交,不调用业务写操作。若要直接运行现成版本,可用 declarative-intake 案例。
打开完整可运行案例03声明 Skill 目录
在 extension.json 顶层合并 skills 数组。它列出包含 SKILL.md 的目录,不是 YAML 文件路径。保留已有 operations 和 contributes。
"skills": ["skills/intake"]04编写 Skill
description 说明什么时候使用;正文说明如何使用工具与等待用户。amble-form-ref 将 Skill 关联到包内模板,path 相对当前 SKILL.md 所在目录。它不是任意 Markdown 链接。
---
name: team-intake
description: Collect a team plan with a form in chat.
---
When the user wants to submit a team plan, call forms_list.
Select team-intake from this extension, then call forms_present.
Wait for the user to fill and confirm the form.
Do not claim a business record has been created.
```amble-form-ref
path: intake.yaml
```05定义表单
保存以下完整文件。字段 name 是模板内的稳定标识;required 要求输入;submit.kind: chat 将确认后的内容发送到当前聊天,不创建后端记录。
version: 1
id: team-intake
title: Team plan
description: Review your information before sending.
fields:
- name: title
type: text
label: Plan name
required: true
maxLength: 120
- name: people
type: number
label: Participants
integer: true
minimum: 1
maximum: 100
required: true
- name: confirmed
type: checkbox
label: I have checked this information
required: true
submit:
kind: chat
label: Confirm and send06把 Skill 与 YAML 一起打包
在 build.cjs 的异步函数中、output 创建之后加入下列复制语句。保持目录结构;只复制 SKILL.md 会造成模板不可发现。然后重新构建、校验、打包并安装。
await fs.cp(path.join(root, 'skills'),
path.join(output, 'skills'), { recursive: true });07在聊天中验收
新建对话并请求「使用 team-intake 表单收集团队计划」。模型需支持工具调用。预期:Agent 发现模板 → 宿主展示表单 → 空必填项阻止提交 → 用户确认后内容进入聊天。若没出现,先查已安装包的 skills 路径和模板引用,再查扩展启用/信任与模型工具调用。
08下一步:连接业务操作
forms_list / forms_present 属于 Agent 工具,不能在后端 import 一个 forms API 来调用。需要持久化业务记录时,使用声明式 operation 提交并实现幂等与恢复。
实现多步业务表单检查结果与排错
在聊天中触发 Skill,看到声明的表单。
按本页的验证步骤核对实际结果。涉及业务服务时,分别检查界面提交、工具回执与服务端记录。
打开错误代码与排错 →