page-agent-skills

🤖 PageAgent Skills

Comprehensive AI skills for implementing Alibaba's PageAgent — the client-side GUI agent framework that enables natural language control of any web application.

Give any AI coding agent the ability to implement PageAgent on any website — zero hallucination, all sourced from official documentation.

📖 Main Skill Guide • 📘 API Reference • 🧩 Patterns & Recipes • 🔧 Troubleshooting

🌟 What is This?

This repository contains production-ready AI skills that teach any AI coding agent (Claude, GPT, Gemini, etc.) how to implement Alibaba's PageAgent on any website. The skills cover everything from installation to advanced patterns, with 62KB+ of documentation, code examples, and diagrams.

What is PageAgent?

PageAgent is a purely client-side web automation framework powered by LLMs. It converts natural language commands into DOM operations — running entirely within the webpage as JavaScript. No backend, no screenshots, no server needed.

✨ Features

🔄 The Re-act Loop

PageAgent operates through an iterative Re-act (Reasoning + Acting) loop powered by the MacroTool pattern — forcing the LLM to reflect before every action:

📁 Repository Structure

page-agent/
├── 📄 README.md                           # This file
├── 📄 LICENSE                             # MIT License
├── 📄 .gitignore                          # Git ignore rules
├── 📂 images/                             # README images
│   ├── hero_banner.png
│   ├── architecture_diagram.png
│   ├── features_showcase.png
│   └── react_loop.png
└── 📂 .claude/skills/page-agent/          # ⭐ The AI Skills
    ├── 📄 SKILL.md                        # Main skill guide (23KB)
    ├── 📄 REFERENCE.md                    # Complete API reference (12KB)
    ├── 📄 PATTERNS.md                     # 9 implementation patterns (15KB)
    ├── 📄 TROUBLESHOOTING.md              # Diagnostic guide (12KB)
    └── 📂 images/                         # Skill-embedded images
        ├── hero_banner.png
        ├── architecture_diagram.png
        ├── features_showcase.png
        └── react_loop.png

📖 Skill Files Overview

SKILL.md — Main Guide (23KB)

The comprehensive skill guide covering:

• Architecture — Re-act loop, MacroTool pattern, package hierarchy
• Quick Start — NPM, CDN, Chrome Extension installation
• LLM Models — 10+ tested models with configuration for each provider
• Custom Tools — Zod schemas, page filters, runtime registration
• Custom Instructions — System-level and per-page dynamic instructions
• Data Masking — transformPageContent for sensitive data protection
• PageController — DOM extraction, element targeting, viewport expansion
• Headless Mode — PageAgentCore for custom UIs
• Security — Interaction allowlists, backend proxy, execute_javascript removal
• Deployment — Decision guide for NPM vs CDN vs Extension

REFERENCE.md — API Reference (12KB)

Complete API documentation:

• PageAgent class — Constructor, config, methods, properties
• PageAgentCore class — Headless agent, events, execution results
• PageController class — DOM extraction, actions, BrowserState interface
• LLM Configuration — Model patches, customFetch, proxy patterns
• Tool System — tool() helper, built-in tools, registration methods
• Events — statuschange, historychange, activity event types
• Types — All TypeScript interfaces and enums

PATTERNS.md — Implementation Patterns (15KB)

9 battle-tested patterns:

Plus anti-patterns to avoid (API key exposure, vague instructions, missing data masking).

TROUBLESHOOTING.md — Diagnostics (12KB)

Issue-specific guidance:

• Model Response Errors — Format issues, provider compatibility
• Low Success Rate — Step-by-step diagnosis, instruction optimization
• Element Targeting — Missing elements, viewport scope, whitelisting
• API Errors — HTTP 400/401/403/429/500 solutions
• Agent Loops — Stuck agent, state detection, impossible actions
• Security — API key exposure, data leakage, unsafe actions
• Performance — Token optimization, DOM size reduction
• Framework Issues — React SPA, Shadow DOM, iframes
• Debug Checklist — 12-point verification checklist

🚀 Quick Start

Prerequisites

• Any AI coding agent that supports skills (e.g., Claude with .claude/skills/)
• A web project where you want to implement PageAgent

Using the Skills

1. Copy the .claude/skills/page-agent/ directory into your project's .claude/skills/ folder

2. Ask your AI agent to implement PageAgent:

   "Add a natural language AI assistant to my React web app using PageAgent.
   It should help users navigate the dashboard and fill out forms."
   

3. The AI agent will automatically use the skill to:

   • Install page-agent via NPM
   • Configure the LLM provider securely (backend proxy)
   • Add custom tools for your domain
   • Set up proper instructions and data masking
   • Handle all edge cases documented in the skill

🔧 Supported LLM Models

💡 Example: Minimal Integration

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
  model: 'gpt-4.1-mini',
  baseURL: '/api/llm-proxy',  // Backend proxy for API key security
  apiKey: '',
  language: 'en-US',
  instructions: {
    system: 'You are a helpful assistant for this website.',
  },
})

// Show the built-in chat panel
agent.panel.show()

// Or execute programmatically
const result = await agent.execute('Click the Settings button and enable dark mode')
console.log(result.success, result.data)

📚 Sources

These skills were created from exhaustive research of:

• DeepWiki — 50+ content chunks covering architecture, internals, and source code analysis
• Official Documentation — All 15 documentation pages (overview, quick start, limitations, troubleshooting, custom tools, data masking, custom instructions, models, chrome extension, third-party agent, PageAgent API, PageAgentCore API, PageController API, custom UI, security permissions)
• GitHub Repository — Source code references for type definitions and implementation details

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

The PageAgent framework itself is developed by Alibaba and is also MIT licensed.

Built with ❤️ for AI coding agents everywhere

Making web automation accessible through comprehensive, hallucination-free documentation.