@agentwebskills/web-skills

A browser skill execution engine for AI agents. Define skills in AgentSkills.io format and execute them in the browser — HTTP requests, DOM interactions, and semantic element targeting.

Install

npm install @agentwebskills/web-skills

Quick start

Define a skill in a SKILL.md file with embedded JSON:

---
name: github-skill
description: Create GitHub issues via the GitHub API.
---

# GitHub Skill

## createGithubIssue

Create a GitHub issue in a repository.

Parameters:
- owner (string): Repository owner
- repo (string): Repository name
- title (string): Issue title
- token (string): GitHub personal access token

```json
{
  "name": "createGithubIssue",
  "type": "http",
  "parameters": {
    "owner": "string",
    "repo": "string",
    "title": "string",
    "token": "string"
  },
  "request": {
    "method": "POST",
    "url": "https://api.github.com/repos/{owner}/{repo}/issues",
    "headers": {
      "Authorization": "Bearer {token}"
    },
    "body": {
      "title": "{title}"
    }
  }
}
```

Build the skill bundle:

npx web-skills build ./my-skill

This produces scripts/skill-bundle.js — a self-contained IIFE that can be injected into any browser page via Playwright or similar. Once injected, skills are available at window.webSkill:

const result = await window.webSkill.execute("createGithubIssue", {
  owner: "myorg",
  repo: "myrepo",
  title: "Bug report",
  token: "ghp_..."
})

Creating a skill

A skill follows the AgentSkills.io format:

my-skill/
├── SKILL.md              # Metadata + instructions + JSON definitions
└── scripts/
    └── skill-bundle.js   # Generated by `npx web-skills build`

The SKILL.md must include:

• A ## How to execute section that tells the agent to use the browser (prevents curl execution)
• A Target URL for each function — where the agent should navigate before calling it
  • about:blank for HTTP-only skills (API calls work from any page)
  • The actual site URL for DOM/semantic skills (e.g. https://www.paknsave.co.nz/login)

Each JSON definition can include an optional target_url field for programmatic access.

See examples/github-skill/SKILL.md for a complete example.

Skill types

http — API requests

Make HTTP requests with interpolated parameters in URLs, headers, and body.

{
  "name": "fetchUser",
  "type": "http",
  "target_url": "about:blank",
  "parameters": { "id": "string" },
  "request": {
    "method": "GET",
    "url": "https://api.example.com/users/{id}"
  }
}

dom — DOM interactions

Click, type, wait, select, and extract data using CSS selectors.

{
  "name": "login",
  "type": "dom",
  "target_url": "https://example.com/login",
  "parameters": { "email": "string", "password": "string" },
  "steps": [
    { "action": "type", "selector": "#email", "value": "{email}" },
    { "action": "type", "selector": "#password", "value": "{password}" },
    { "action": "click", "selector": "#login-button" }
  ]
}

semantic_dom — Semantic element targeting

Target elements by description instead of CSS selectors. Uses ARIA labels and text content to find elements.

{
  "name": "addToCart",
  "type": "semantic_dom",
  "target_url": "https://example.com/products",
  "parameters": { "product": "string" },
  "steps": [
    { "action": "click", "description": "Add to cart button for {product}" }
  ]
}

API

SkillEngine.fromMarkdown(md: string): SkillEngine

Create an engine from a SKILL.md file. Parses all JSON code blocks as skill definitions.

new SkillEngine({ skills, executors? })

Create an engine from raw skill definition objects. Optionally pass custom executors.

engine.execute(name: string, args?: Record<string, unknown>): Promise<ExecutionResult>

Execute a skill by name with the given arguments.

engine.getSkillNames(): string[]

List all registered skill names.

engine.registerExecutor(type: string, executor: Executor)

Register a custom executor for a new skill type.

Development

npm run build       # Build with tsup
npm test            # Run tests
npm run typecheck   # Type-check without emitting

License

MIT