create-agent-site-skill

创建站点专属浏览器技能

将可运行的浏览器工作流记录为可独立运行、可重复使用的技能。复用已有的已验证工作流；对于缺失的步骤，可在用户授权范围内通过实时浏览器探索。

选择浏览器控制方式

默认使用 kernel browsers playwright execute 和 kernel browsers computer。有关安装、身份验证和命令语法，请加载 kernel-cli。

如果调用方指定了其他工具框架，请使用其命令，并在生成的技能中记录该依赖：

• agent-browser： 加载 kernel-agent-browser，并遵循其 CDP 附加工作流，复用下方创建的浏览器。
• browser-harness： 如果调用 Agent 使用其 BU_CDP_WS/BU_NAME 模型，请加载 kernel-browser-harness。
• 其他工具框架： 将 KERNEL 浏览器的 cdp_ws_url 传递给所选工具框架。

根据所选控制方式调整下方命令示例；保留会话和凭证要求。

探索工作流

1. 准备浏览器

配置文件和保管库都应限定到具体站点和用户：<site-name>-<user-id>。从运行时输入或会话上下文中解析用户 ID；绝不要在共享技能中将其硬编码。配置文件中包含已通过身份验证的 Cookie 和存储数据。

对于需要登录的站点，创建一次配置文件和保管库，然后重复使用。两者都应与浏览器位于同一个 KERNEL 项目中。仅在确认资源不存在时运行创建命令：

PROFILE_NAME="<site-name>-<user-id>"
VAULT_NAME="<site-name>-<user-id>"

# First-time setup only:
kernel profiles create --name "$PROFILE_NAME"
kernel vaults create --name "$VAULT_NAME"

# Each run:
SESSION=$(kernel browsers create --profile-name "$PROFILE_NAME" --save-changes --stealth --vault "$VAULT_NAME" --timeout 600 -o json | jq -r '.session_id')

• 使用有头会话（默认设置）；使用计算机和实时视图都需要有头会话。
• 创建时设置 --stealth 并附加保管库；之后无法再添加。对于不需要登录的站点，省略保管库设置和 --vault。
• 保留 --save-changes，以便在会话结束时持久化 Cookie 和存储数据。使用 --timeout 600 留出足够的探索时间，而不是 CLI 默认的 60 秒。

2. 建立登录状态

检查已保存的配置文件是否已经通过身份验证。如果需要登录，请使用由保管库提供的凭证。绝不要索取原始凭证，也不要将其存入技能或 AGENTS.md。

在定义凭证架构前先检查登录流程。记录凭证字段、类型、必填/敏感标记、登录阶段以及字段到选择器的映射；随着发现更多阶段，逐步完善这些信息。

kernel browsers playwright execute "$SESSION" 'await page.goto("<login-url>")'
kernel browsers computer screenshot "$SESSION" --to /tmp/login.png

复用用户现有的凭证条目及其字段名称。如果不存在，请根据已发现的架构定义凭证条目，但不要填写值；可参考并调整以下用户名/密码示例：

kernel vaults credentials create "$VAULT_NAME" <site-name>-login --spec-file - <<'JSON'
{
  "description": "<Site Name>",
  "fields": {
    "username": {"type": "text", "required": true, "sensitive": false},
    "password": {"type": "password", "required": true, "sensitive": true}
  }
}
JSON

直接将返回的私有集合 URL 分享给用户。绝不要在由 Agent 控制的浏览器中打开该 URL。--wait 60 只会进行一次有时限的状态观察，并非重试——在条目处于等待状态时轮询，并在其进入终态后停止：

STATUS="pending"
while [ "$STATUS" = "pending" ]; do
  ITEM=$(kernel vaults items get "$VAULT_NAME" <site-name>-login --wait 60 -o json)
  STATUS=$(jq -r '.state.status' <<<"$ITEM")
done

如果 $STATUS 为 ready，则可执行填充操作——按字段名称和选择器填充，并根据观察到的表单调整字段和顺序。如果进入任何其他终态，请停止并排查问题，然后再继续。

kernel vaults items invoke "$VAULT_NAME" <site-name>-login fill --spec-file - <<JSON
{
  "browser_id": "$SESSION",
  "page_url": "<login-url>",
  "fields": [
    {"field": "username", "selector": "input[name='username']"},
    {"field": "password", "selector": "input[name='password']"}
  ]
}
JSON

绝不要读取、打印、截屏或返回填入的凭证值。如果填充操作报错、超时，或返回的状态不是 completed，请停止并排查问题，然后再提交。fill 不会提交，因此可以安全重试。重试前务必检查页面，且绝不要在自动循环中重试。

填充成功后，提交并验证预期的登录状态：

kernel browsers playwright execute "$SESSION" -o json '
  await Promise.all([
    page.waitForURL("<logged-in-url-pattern>", { timeout: 5000 }),
    page.getByRole("button", { name: "Sign in" }).click()
  ]);
  return page.url();
'

如果现有会话未启用 stealth，且机器人检测阻止登录，请删除该会话并启用 stealth 重新创建。如果登录仍受阻，请使用 kernel browsers view "$SESSION" -o json 获取 browser_live_view_url，请用户手动登录，并验证登录后的状态。

3. 探索并验证每项任务

确保每项请求的任务都能独立运行；必要时注明共享设置和登录前提。

1. 导航到任务的起始状态并检查页面。
2. 使用选定的控件执行任务，并在操作后确认状态确实发生变化。
3. 记录输入、起始状态、直接 URL、按顺序排列的命令、等待条件、成功检查，以及观察到的失败或变通方法。
4. 单独测试不确定的步骤，然后使用技能文档中将记录的相同命令验证完整流程。测试必须在用户授权范围内，并说明验证限制。

对于 KERNEL 的默认控件：

• 优先使用角色、标签或文本定位器；如果网站语义不足，则使用 CSS 或 XPath。
• 使用 return 返回验证结果，并在解析结果时使用 -o json。每次 playwright execute 调用都会创建新的脚本上下文；浏览器页面会持续保留。
• 等待能证明操作已完成的 URL、可见状态、响应或值。设置明确的短超时时间，例如 5000 ms；仅在最后不得已时使用固定等待时间。不要默认使用 networkidle 作为成功条件。
• 对 iframe 交互（包括跨域 iframe），使用 page.frameLocator(...)。

计算机操作备用方案

如果 Playwright 尝试 2–3 次后仍无法完成某个步骤，无论是报错、超时，还是报告成功但页面状态没有变化，都应使用计算机控件完成该步骤。重试可能已成功的操作前，先检查结果。

kernel browsers computer screenshot "$SESSION" --to /tmp/state.png
kernel browsers computer drag-mouse "$SESSION" --point 100,200 --point 250,200 --point 400,200 --button left
kernel browsers computer click-mouse "$SESSION" --x 250 --y 60
kernel browsers computer type "$SESSION" --text "some text"
kernel browsers computer press-key "$SESSION" --key Return

根据截图读取坐标，并同时记录视口大小。包含中间拖动路径点，确保指针传感器能够检测到移动。每个手势都必须完全通过 DOM 控件或计算机控件完成；适当时再切回 Playwright。

4. 编写技能

使用主要自动化域作为文件夹名称：<skills-directory>/<domain>/SKILL.md。根据目标 Agent 的说明，确定已注册的技能目录。

根据已验证的命令和网站特定发现调整以下模板。注明所选控件、设置、登录（如需要）和清理步骤。通用 CLI 文档应放在链接的依赖技能中。

在共享技能中记录发现的凭据架构、字段到选择器的映射、登录流程、等待条件和成功检查。将网站特定占位内容替换为已验证的详细信息，但将用户 ID、保管库／条目引用、配置文件引用和账户专属 URL 组成部分保留为运行时输入，或从当前用户的上下文中解析。绝不要硬编码发现用户的值。

---
name: <descriptive-name>
description: <What the skill does and when to use it.>
---

# <Site Name>

## Setup

<Required tools and skill dependencies, runtime inputs, and tested session setup.>

## Login

<How to check existing authentication; tested vault-backed login and manual fallback if needed.>

## <Task Name>

<Required inputs and starting state.>

```bash
# Tested commands, including necessary waits and verification.
```

<Expected outcome and any task-specific recovery instructions. Repeat for each independent task.>

## Cleanup

<Commands to close the selected harness and delete the Kernel session.>

## Notes

<Observed quirks and workarounds; coordinate/viewport requirements where applicable.>

5. 清理

关闭所有已连接的测试框架，并删除为探索创建的浏览器会话。删除操作会最终确定配置文件的持久化状态：

kernel browsers delete "$SESSION"