create-agent-site-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Site-Specific Browser Skills

创建网站专用浏览器 Skill

Capture working browser workflows as independently runnable tasks in a reusable skill. Reuse existing verified workflows; explore missing steps in a live browser within the user's authorized scope.

将可正常运行的浏览器工作流封装为独立可运行的任务，并保存到可复用的 Skill 中。复用已经验证的工作流；对于缺失的步骤，可在用户授权范围内通过实时浏览器进行探索。

Choose Browser Controls

选择浏览器控制方式

Default to

kernel browsers playwright execute

and

kernel browsers computer

. Load kernel-cli for installation, authentication, and command syntax.

If the caller specifies another harness, use its commands and record that dependency in the generated skill:

agent-browser: Load kernel-agent-browser and follow its CDP attachment workflow, reusing the browser created below.
browser-harness: Load kernel-browser-harness when the calling agent uses its
```
BU_CDP_WS
```
/
```
BU_NAME
```
model.
Other harnesses: Pass the Kernel browser's
```
cdp_ws_url
```
to the selected harness.

Adapt the command examples below to the selected controls; retain the session and credential requirements.

默认使用

kernel browsers playwright execute

和

kernel browsers computer

。加载 kernel-cli，了解安装、身份验证和命令语法。

如果调用方指定了其他 harness，请使用该 harness 的命令，并在生成的 Skill 中记录相应依赖项：

agent-browser： 加载 kernel-agent-browser，并遵循其 CDP attachment workflow，复用下面创建的浏览器。
browser-harness： 当调用 Agent 使用其
```
BU_CDP_WS
```
/
```
BU_NAME
```
模型时，加载 kernel-browser-harness。
其他 harness： 将 Kernel browser 的
```
cdp_ws_url
```
传递给所选 harness。

根据所选控制方式调整以下命令示例；保留 session 和 credential 要求。

Discover the Workflows

发现工作流

1. Prepare a Browser

1. 准备浏览器

Keep profiles and vaults scoped to both site and user:

<site-name>-<user-id>

. Resolve the user ID from runtime input or session context; never hard-code it in the shared skill. Profiles contain authenticated cookies as well as storage.

For a site requiring login, create the profile and vault once, then reuse them. Keep both in the same Kernel project as the browser. Run the creation commands only for resources confirmed absent:

bash

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

将 profile 和 vault 的作用域限定为网站与用户的组合：

<site-name>-<user-id>

。从运行时输入或 session 上下文解析 user ID；绝不将 user ID 硬编码到共享 Skill 中。Profile 包含已认证的 Cookie 以及存储数据。

对于需要登录的网站，创建一次 profile 和 vault，随后重复使用它们。Profile、vault 与 browser 必须位于同一个 Kernel project 中。仅对已确认不存在的资源运行创建命令：

bash

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')


- Use a headful session (the default); computer-use and live view require it.
- Set `--stealth` and attach the vault at creation time; neither can be added later. Omit vault setup and `--vault` for sites that do not need login.
- Keep `--save-changes` to persist cookies and storage when the session ends. Allow enough discovery time with `--timeout 600` rather than the CLI's 60-second default.

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


- 使用 headful session（默认设置）；computer-use 和 live view 需要该模式。
- 创建时设置 `--stealth` 并挂载 vault；二者均无法在之后添加。对于不需要登录的网站，省略 vault 设置和 `--vault`。
- 保留 `--save-changes`，以便 session 结束时持久化 Cookie 和存储数据。使用 `--timeout 600` 为探索留出充足时间，而不是 CLI 默认的 60 秒。

2. Establish Login

2. 建立登录

Check whether the saved profile is already authenticated. If login is needed, use vault-backed credentials. Never request raw credentials or store them in the skill or

AGENTS.md

Inspect the login flow before defining its credential schema. Record credential fields, types, required/sensitive flags, login stages, and field-to-selector mappings; refine these as additional stages become visible.

bash

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

Reuse the user's existing credential item and its field names. If absent, define it from the discovered schema without values; adapt this username/password example:

bash

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

Share the returned private collection URL directly with the user. Never open it in the agent-controlled browser.

--wait 60

is a single bounded observation, not a retry — poll it while the item is pending and stop once it reaches a terminal state:

bash

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

, the fill action is available — fill by field name and selector, adapting the fields and sequence to the observed form. For any other terminal status, stop and reconcile before proceeding.

bash

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

Never read, print, screenshot, or return filled credential values. If the fill errors, times out, or returns a status other than

completed

, stop and reconcile before retrying or submitting.

After a completed fill, submit and verify the expected logged-in state:

bash

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();
'

If an existing session lacks stealth and bot detection blocks login, delete it and recreate it with stealth. If login remains blocked, get

browser_live_view_url

with

kernel browsers view "$SESSION" -o json

, ask the user to log in manually, and verify the resulting state.

检查已保存的 profile 是否已经完成身份验证。如果需要登录，使用 vault-backed credential。绝不请求原始 credential，也不要将其存储在 Skill 或

AGENTS.md

中。

先检查登录流程，再定义 credential schema。记录 credential 字段、类型、required/sensitive 标志、登录阶段以及字段到 selector 的映射；随着更多阶段被发现，持续完善这些信息。

bash

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

复用用户现有的 credential item 及其字段名称。如果该 item 不存在，则根据发现的 schema 定义一个不包含具体值的 credential item，并调整以下 username/password 示例：

bash

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

将返回的私有 collection URL 直接发给用户。绝不可以在 Agent 控制的浏览器中打开它。

--wait 60

是一次有界的观察，而不是重试：当 item 处于 pending 状态时持续轮询，一旦达到终态立即停止：

bash

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

，则可以使用 fill 操作——按字段名和 selector 填写，并根据实际观察到的表单调整字段和顺序。对于任何其他终态，均应停止操作，先排查问题并恢复到一致状态，然后再继续。

bash

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

绝不读取、打印、截图或返回已填写的 credential 值。如果 fill 报错、超时，或返回的状态不是

completed

，应停止操作，先排查问题并恢复到一致状态，然后再重试或提交。

填充完成后，提交表单并验证预期的已登录状态：

bash

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();
'

如果现有 session 缺少 stealth，且 bot detection 阻止登录，请删除该 session，并使用 stealth 重新创建。如果登录仍被阻止，请通过

kernel browsers view "$SESSION" -o json

获取

browser_live_view_url

，请用户手动登录，然后验证最终状态。

3. Explore and Verify Each Task

3. 探索并验证每项任务

Keep each requested task independently runnable, with shared setup and login prerequisites where needed.

Navigate to the task's starting state and inspect the page.
Perform the task with the selected controls, confirming actual state changes after actions.
Record inputs, starting state, direct URLs, ordered commands, wait conditions, success checks, and observed failures or workarounds.
Test individual uncertain steps, then verify the complete sequence using the same commands the skill will document. Keep testing within the user's authorization and state any verification limits.

For Kernel's default controls:

Prefer role, label, or text locators; use CSS or XPath when the site's semantics are insufficient.
Use
```
return
```
for verification results and
```
-o json
```
when parsing them. Each
```
playwright execute
```
call has a fresh script context; the browser page persists.
Wait for an observed URL, visible state, response, or value that proves completion. Set explicit short timeouts, such as 5000 ms; use fixed waits only as a last resort. Avoid
```
networkidle
```
as the default success condition.
Use
```
page.frameLocator(...)
```
for iframe interactions, including cross-origin frames.

让每项请求的任务都可以独立运行，并在需要时共享设置和登录前置条件。

导航到任务的起始状态并检查页面。
使用所选控制方式执行任务，操作后确认页面实际发生了状态变化。
记录输入、起始状态、直接 URL、有序命令、等待条件、成功检查，以及观察到的失败情况或替代方案。
先单独测试存在不确定性的步骤，再使用 Skill 最终记录的命令验证完整序列。测试应始终处于用户授权范围内，并说明验证限制。

对于 Kernel 的默认控制方式：

优先使用 role、label 或 text locator；如果网站语义不足，则使用 CSS 或 XPath。
使用
```
return
```
返回验证结果，并在解析结果时使用
```
-o json
```
。每次
```
playwright execute
```
调用都有全新的 script context，但 browser page 会持续保留。
等待能够证明任务完成的已观察 URL、可见状态、response 或 value。设置明确的短超时，例如 5000 ms；固定等待仅作为最后手段。不要默认将
```
networkidle
```
用作成功条件。
使用
```
page.frameLocator(...)
```
与 iframe 交互，包括跨域 iframe。

Computer-Use Fallback

If Playwright cannot complete a step after 2–3 attempts, whether it errors, times out, or reports success without changing page state, use computer controls for that step. Check the outcome before retrying an action that may already have succeeded.

bash

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

Read coordinates from the screenshot and record the viewport size alongside them. Include intermediate drag waypoints so pointer sensors register movement. Keep each gesture entirely within DOM or computer controls; return to Playwright afterward where appropriate.

如果 Playwright 在尝试 2–3 次后仍无法完成某一步——无论是报错、超时，还是报告成功但页面状态未发生变化——则对该步骤改用 computer controls。在重试某个可能已经成功的操作前，先检查结果。

bash

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

从截图中读取坐标，并同时记录 viewport 尺寸。加入中间拖拽 waypoint，让指针传感器能够识别移动。每个操作必须完全限定在 DOM 或 computer controls 范围内；之后应在适当情况下切回 Playwright。

4. Write the Skill

4. 编写 Skill

Use the primary automation domain as the folder name:

<skills-directory>/<domain>/SKILL.md

. Resolve the registered skill directory from the target agent's instructions.

Adapt the template below using the verified commands and site-specific findings. Include the chosen controls, setup, login if needed, and cleanup. Keep generic CLI documentation in the linked dependency skill.

Save the discovered credential schema, field-to-selector mappings, login sequence, waits, and success checks in the shared skill. Replace site-specific placeholders with verified details, but keep user IDs, vault/item references, profile references, and account-specific URL components as runtime inputs or resolve them from the current user's context. Never hard-code the discovery user's values.

markdown

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

以主要自动化领域作为文件夹名称：

<skills-directory>/<domain>/SKILL.md

。从目标 Agent 的说明中解析已注册的 Skill 目录。

使用已验证的命令和特定网站的发现结果调整下面的模板。包含所选控制方式、设置、登录（如需要）和清理流程。通用 CLI 文档保留在链接的依赖 Skill 中。

将发现的 credential schema、字段到 selector 的映射、登录顺序、等待条件和成功检查保存到共享 Skill 中。用已验证的详情替换特定网站的占位符，但 user ID、vault/item 引用、profile 引用和账户特定的 URL 组件应保留为运行时输入，或从当前用户上下文解析。绝不硬编码发现流程所用用户的值。

markdown

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

<Site Name>

Setup

Login

<Task Name>

bash

undefined

bash

undefined

Tested commands, including necessary waits and verification.


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


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

Cleanup

Notes

undefined

undefined

5. Clean Up

5. 清理

Close any attached harness and delete the browser session created for discovery. Deletion finalizes profile persistence:

bash

kernel browsers delete "$SESSION"

关闭任何已挂载的 harness，并删除为发现流程创建的 browser session。删除操作会完成 profile 持久化：

bash

kernel browsers delete "$SESSION"