Agent Eyes Skill

When to Apply

Apply this skill for UI tasks that need element-anchored precision (for example: “this button”, “当前这个区域”, breadcrumb path, DOM path, selected node).
Apply this skill when the user refers to “this element”, “当前选中的元素”, “这里”, “这个按钮”, “这个区域”, breadcrumb path, DOM path, or a visual target on the page.
Apply this skill when the task requires precise code modification and the target should be anchored to a selected element instead of guessed from text alone.
Apply this skill when the project may not yet have
```
@agent-eyes/agent-eyes
```
installed or may not yet have an
```
AGENTS.md
```
rule enforcing context-first behavior.
Do not apply this skill for tasks that can be completed from explicit file paths, code snippets, or clear textual requirements without selected-element context.

Apply Order

If
```
@agent-eyes/agent-eyes
```
is missing, install it first.
If installation was performed in this run, help the user finish minimal plugin configuration for their bundler.
If
```
AGENTS.md
```
is missing or lacks the Agent Eyes rule, create or update it.
If the task is element-anchored/ambiguous, request
```
GET /context/selected
```
before editing code.
If the response is
```
data: null
```
, the agent MUST continue with the default workflow and skip selected-context injection only.
The agent MUST NOT block execution or require element selection as a prerequisite; it may optionally suggest re-selection only when precision risk is high.

Quick Workflow

Check whether
```
@agent-eyes/agent-eyes
```
is installed.
If missing, help install and provide minimal setup guidance.
If installed during this run, actively help configure plugin entry in bundler config files.
Verify config looks effective (plugin imported + plugin applied in config).
Check whether the project already has
```
AGENTS.md
```
.
If missing, create it. If present, append or refine the Agent Eyes workflow rule.
Resolve service base URL.
Request selected-context endpoint only when the target is element-anchored or ambiguous.
If no active selection exists, continue normal code analysis/edit flow and treat context as unavailable.
Validate and normalize response fields.
Build a compact context block for the next agent request.

Check Plugin Installation

Detect package manager from lock files:
```
pnpm-lock.yaml
```
-> use
```
pnpm
```
```
yarn.lock
```
-> use
```
yarn
```
```
package-lock.json
```
-> use
```
npm
```
Check if
```
@agent-eyes/agent-eyes
```
exists in dependencies:
Inspect root
```
package.json
```
(
```
dependencies
```
and
```
devDependencies
```
).
If not found, install with the detected package manager:
```
pnpm add -D @agent-eyes/agent-eyes
```
```
yarn add -D @agent-eyes/agent-eyes
```
```
npm i -D @agent-eyes/agent-eyes
```
When replying to users, provide install commands on demand:
Default: only show one command that matches detected package manager.
If user asks for alternatives, then include
```
pnpm
```
/
```
yarn
```
/
```
npm
```
variants.
After install, do not stop at package installation:
Identify the active bundler/framework from project files (
```
vite.config.*
```
,
```
webpack.config.*
```
,
```
next.config.*
```
,
```
nuxt.config.*
```
, etc.).
Help the user update the real config file in-place (or give an exact patch) to include
```
codeInspectorPlugin(...)
```
.
Include minimal
```
bundler
```
+
```
showSwitch
```
+
```
agent.acp.command
```
fields in example config.
Confirm import + plugin registration both exist after edit.
If
```
package.json
```
cannot be found, ask user to confirm project root before installation.

Post-Install Configuration Requirement

Treat "install plugin" as incomplete until configuration is done.
If auto-edit is allowed, modify the detected config file directly and summarize changes.
If multiple candidate config files exist, prefer the one used by current scripts in
```
package.json
```
.
If bundler cannot be inferred, ask one short blocking question and provide 2-3 likely file candidates.
After config, instruct user to start/restart dev server and verify Agent Eyes switch appears.

Bundler Configuration Examples (On Demand)

If user asks for "how to configure", provide the example matching their actual bundler/framework.
Do not dump all examples by default. Return one best-match snippet first, plus alternatives only when requested.
Load examples from references/bundler-examples.md.
Prefer reading only the relevant section in that file to keep context small.
All snippets should include minimal Agent Eyes config:
```
bundler
```
```
showSwitch: true
```
```
agent.acp.command
```

Ensure AGENTS.md Exists

Look for
```
AGENTS.md
```
in the current project root first.
If it does not exist, create
```
AGENTS.md
```
with the Agent Eyes workflow template from references/agents-template.md.
If it exists, preserve user content and append a short Agent Eyes section rather than replacing the whole file.
The inserted rule must require:
checking
```
@agent-eyes/agent-eyes
```
installation
fetching
```
GET /context/selected
```
before element-anchored/ambiguous UI modification
when
```
data: null
```
, continue with default workflow; skip selected-context injection only
do not force re-selection; only suggest it when precision risk is high

Resolve Base URL

Prefer an explicit value from user/tool input.

If not provided, prefer environment (

AGENT_EYES_BASE_URL

CODE_INSPECTOR_BASE_URL

If still missing, read current project
```
.code-inspector/record.json
```
and use its
```
port
```
.
Fallback to
```
http://127.0.0.1:5678
```
.
Keep path configurable; do not hardcode if caller provides a different endpoint.

Request Context Endpoint

Prefer
```
GET /context/selected
```
for read-only context retrieval.
If API requires POST, send an empty JSON body
```
{}
```
unless caller specifies filters.
Set
```
Accept: application/json
```
.
Use a short timeout (3-5 seconds) and report endpoint + timeout on failure.
Treat
```
data: null
```
as "there is no current selection". Do not reuse stale context from earlier requests; continue with default workflow without context injection.
For endpoint details and payload schema, read references/context-api.md.

Normalize Response

Accept either
```
data
```
wrapper or flat object.
Prefer multi-selection fields first:
```
activeSelectionId
```
```
selections
```
/
```
contexts
```
```
data.active
```
and
```
data.selections
```
Normalize into this shape:
```
activeSelectionId
```
: string
```
active
```
: object | null
```
contexts
```
: object[]
```
selections
```
: object[] (same as
```
contexts
```
)
For each context item, normalize:
```
filePath
```
: string
```
line
```
: number
```
column
```
: number
```
elementName
```
: string
```
dom.tagName
```
: string
```
dom.className
```
: string
```
dom.textContent
```
: string (truncate to 200 chars)
```
domPath
```
: string[]
If
```
domPath
```
is an object array, map with
```
label || name
```
.
If multi-selection fields are missing, fallback to single-selection fields from
```
data
```
or root object.
If required fields are missing, return a clear error listing missing keys.

Build Prompt Block

Use this template for downstream agent requests:

text

There are {selectionCount} selected DOM contexts. Consider all of them together.

{activePrefix}Selection #{index}
Source: {filePath}:{line}:{column}
Element: <{elementName} ...>
DOM: {tagName}, className: {className}, text: {textContent}
Path: {domPathJoined}

Request Example

bash

curl -sS "${BASE_URL}/context/selected" \
  -H "Accept: application/json"

Failure Handling

If request fails, provide:
attempted URL
status code or network error
one concrete retry action (check server port, endpoint path, CORS, or auth header)
If the endpoint returns
```
data: null
```
, do not block the workflow; continue with default workflow and skip selected-context injection.
If context is stale, re-request immediately before sending code-modification prompt.

Notes

Keep this skill focused on plugin readiness + context retrieval + normalization.
Do not mix this skill with full code-edit workflows unless the user asks.
Prefer making the
```
AGENTS.md
```
rule persistent so future agent turns follow it even if this skill is not re-triggered.

agent-eyes

NPX Install

Tags

SKILL.md Content

Agent Eyes Skill

When to Apply

Apply Order

Quick Workflow

Check Plugin Installation

Post-Install Configuration Requirement

Bundler Configuration Examples (On Demand)

Ensure AGENTS.md Exists

Resolve Base URL

Request Context Endpoint

Normalize Response

Build Prompt Block

Request Example

Failure Handling

Notes