@agentforge-ai/cli 0.5.4 → 0.6.0

package/dist/default/skills/browser-automation/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: browser-automation
+description: Built-in browser automation skill for AgentForge agents. Navigate web pages, interact with elements, extract content, and take screenshots using Playwright.
+version: 1.0.0
+tags:
+  - web
+  - browser
+  - automation
+  - scraping
+---
+
+# Browser Automation
+
+**Built-in AgentForge Skill** — Automate web browsers to navigate, interact, extract data, and capture screenshots.
+
+## Overview
+
+The Browser Automation skill gives agents the ability to interact with web pages programmatically using Playwright. This is essential for:
+
+1. **Web scraping** — Extract text, data, and structured content from any website
+2. **Form filling** — Automate login flows, form submissions, and multi-step workflows
+3. **Visual verification** — Take screenshots for visual QA or documentation
+4. **Research** — Navigate and read web pages to gather information
+5. **Testing** — Verify web application behavior
+
+## Supported Actions
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `navigate` | Go to a URL | `url` (required) |
+| `click` | Click an element | `selector` (CSS selector) |
+| `type` | Type text into an input | `selector`, `text` |
+| `screenshot` | Capture the page | `fullPage` (optional) |
+| `snapshot` | Get accessibility tree | — |
+| `extractText` | Extract page text | `selector` (optional) |
+| `evaluate` | Run JavaScript | `js` (code string) |
+| `wait` | Wait for element/time | `selector` or `timeMs` |
+| `scroll` | Scroll the page | `direction`, `amount` |
+| `select` | Select dropdown option | `selector`, `value` |
+| `hover` | Hover over element | `selector` |
+| `goBack` | Navigate back | — |
+| `goForward` | Navigate forward | — |
+| `reload` | Reload the page | — |
+| `close` | Close the session | — |
+
+## How to Use
+
+### Setup
+
+```typescript
+import { createBrowserTool, MCPServer } from '@agentforge-ai/core';
+
+// Create browser tool with default config
+const { tool, shutdown } = createBrowserTool({ headless: true });
+
+// Register with MCP server
+const server = new MCPServer({ name: 'my-tools' });
+server.registerTool(tool);
+
+// Or use the convenience function
+import { registerBrowserTool } from '@agentforge-ai/core';
+const { shutdown: cleanup } = registerBrowserTool(server, { headless: true });
+```
+
+### Docker Sandbox Mode
+
+For secure, isolated browser execution (recommended for production):
+
+```typescript
+const { tool, shutdown } = createBrowserTool({
+  sandboxMode: true,
+  headless: true,
+});
+```
+
+This launches the browser inside a Docker container with:
+- Isolated network and filesystem
+- 2GB shared memory for stability
+- Automatic cleanup on shutdown
+
+### Direct Import
+
+```typescript
+import { createBrowserTool } from '@agentforge-ai/core/browser';
+```
+
+## Agent Instructions
+
+When a user asks you to interact with a web page:
+
+1. **Navigate** to the target URL first
+2. **Wait** for key elements to load before interacting
+3. Use **snapshot** to understand the page structure (accessibility tree)
+4. Use **extractText** to get readable content from the page
+5. Use **click** and **type** to interact with forms and buttons
+6. Use **screenshot** to capture visual state when needed
+7. Always **close** sessions when done to free resources
+
+### Tips for Reliable Automation
+
+- Prefer `#id` selectors over class-based selectors
+- Use `waitForSelector` before clicking or typing
+- For SPAs, wait after navigation for content to render
+- Use `extractText` with a selector to get specific section content
+- Take screenshots before and after critical actions for verification
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `headless` | boolean | `true` | Run browser without UI |
+| `defaultTimeout` | number | `30000` | Navigation timeout (ms) |
+| `browserType` | string | `'chromium'` | Browser engine |
+| `viewportWidth` | number | `1280` | Viewport width |
+| `viewportHeight` | number | `720` | Viewport height |
+| `userAgent` | string | — | Custom user agent |
+| `persistState` | boolean | `false` | Save cookies/state |
+| `statePath` | string | — | Path for state file |
+| `sandboxMode` | boolean | `false` | Docker isolation |
+| `maxSessions` | number | `5` | Max concurrent sessions |
+
+## Session Management
+
+Each session gets its own isolated browser context with separate cookies, storage, and state. Use `sessionId` to manage multiple concurrent browsing sessions:
+
+```typescript
+// Session A: logged into site X
+await tool.handler({ action: { kind: 'navigate', url: 'https://site-x.com' }, sessionId: 'session-a' });
+
+// Session B: logged into site Y (completely isolated)
+await tool.handler({ action: { kind: 'navigate', url: 'https://site-y.com' }, sessionId: 'session-b' });
+```
+
+## Prerequisites
+
+- **Playwright**: `npm install playwright && npx playwright install chromium`
+- **Docker** (optional): Required only for `sandboxMode`

package/dist/default/skills/browser-automation/config.json

@@ -0,0 +1,11 @@
+{
+  "name": "browser-automation",
+  "version": "1.0.0",
+  "description": "Built-in browser automation skill for AgentForge agents. Navigate web pages, interact with elements, extract content, and take screenshots using Playwright.",
+  "category": "web",
+  "author": "AgentForge",
+  "isBuiltIn": true,
+  "tools": ["browser"],
+  "dependencies": ["playwright"],
+  "agentInstructions": "You have access to the Browser Automation tool. Use it to navigate web pages, click elements, type text, extract page content, take screenshots, and wait for elements. Each session has isolated cookies and state. Always close sessions when done."
+}

package/dist/default/skills/browser-automation/index.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+
+/**
+ * browser-automation — Built-in AgentForge Skill
+ *
+ * Provides browser automation capabilities for agents using Playwright.
+ * Supports navigation, interaction, text extraction, screenshots, and more.
+ *
+ * This skill wraps the @agentforge-ai/core browser tool for use in the
+ * skills system. For direct programmatic access, use:
+ *
+ *   import { createBrowserTool } from '@agentforge-ai/core/browser';
+ */
+
+export const tools = [
+  {
+    name: 'browser',
+    description:
+      'Interact with web pages using browser automation. ' +
+      'Supports: navigate, click, type, screenshot, snapshot (accessibility tree), ' +
+      'evaluate JS, wait, scroll, select, hover, goBack, goForward, reload, close, extractText. ' +
+      'Each session has isolated cookies and state.',
+    inputSchema: z.object({
+      action: z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('navigate'), url: z.string().url() }),
+        z.object({ kind: z.literal('click'), selector: z.string() }),
+        z.object({
+          kind: z.literal('type'),
+          selector: z.string(),
+          text: z.string(),
+        }),
+        z.object({
+          kind: z.literal('screenshot'),
+          fullPage: z.boolean().optional(),
+        }),
+        z.object({ kind: z.literal('snapshot') }),
+        z.object({ kind: z.literal('evaluate'), js: z.string() }),
+        z.object({
+          kind: z.literal('wait'),
+          selector: z.string().optional(),
+          timeMs: z.number().optional(),
+        }),
+        z.object({
+          kind: z.literal('scroll'),
+          direction: z.enum(['up', 'down']),
+          amount: z.number().optional(),
+        }),
+        z.object({
+          kind: z.literal('select'),
+          selector: z.string(),
+          value: z.string(),
+        }),
+        z.object({ kind: z.literal('hover'), selector: z.string() }),
+        z.object({ kind: z.literal('goBack') }),
+        z.object({ kind: z.literal('goForward') }),
+        z.object({ kind: z.literal('reload') }),
+        z.object({ kind: z.literal('close') }),
+        z.object({
+          kind: z.literal('extractText'),
+          selector: z.string().optional(),
+        }),
+      ]),
+      sessionId: z.string().optional(),
+    }),
+    outputSchema: z.object({
+      success: z.boolean(),
+      action: z.string(),
+      data: z.union([z.string(), z.record(z.unknown())]).optional(),
+      screenshot: z.string().optional(),
+      error: z.string().optional(),
+      currentUrl: z.string().optional(),
+      pageTitle: z.string().optional(),
+      latencyMs: z.number(),
+    }),
+    handler: async (input: {
+      action: { kind: string; [key: string]: unknown };
+      sessionId?: string;
+    }) => {
+      // Dynamic import to avoid requiring Playwright at skill load time
+      const { createBrowserTool } = await import('@agentforge-ai/core');
+      const { tool, shutdown } = createBrowserTool({ headless: true });
+
+      try {
+        const result = await tool.handler(input as any);
+        return result;
+      } finally {
+        await shutdown();
+      }
+    },
+  },
+];
+
+export default { tools };

package/dist/default/skills/skill-creator/SKILL.md

@@ -1,3 +1,13 @@
+---
+name: skill-creator
+description: Built-in skill for creating, managing, and discovering AgentForge skills. Allows agents to generate new skills from natural language descriptions.
+version: 1.0.0
+tags:
+  - utility
+  - meta
+  - creation
+---
+
 # Skill Creator
 
 **Built-in AgentForge Skill** — Create, manage, and discover skills for your agents.
@@ -7,264 +17,93 @@
 The Skill Creator is a default skill that ships with every AgentForge project. It allows you to:
 
 1. **Create new skills** from natural language descriptions
-2. **Browse example skills** to understand the skill format
-3. **Validate skills** before installing them
-4. **Generate skill code** using your connected LLM
-
-## Usage
-
-### Via CLI
-
-```bash
-# Create a new skill interactively
-agentforge skills create
-
-# Ask the agent to create a skill
-agentforge chat my-agent
-> Create a skill that can fetch weather data for any city
-
-# List available example skills
-agentforge skills search examples
-```
-
-### Via Dashboard
-
-Navigate to **Skills** in the sidebar, then click **"Create Skill"** to use the visual skill builder.
+2. **Browse available skills** in the AgentForge registry
+3. **Validate skills** to ensure they follow the Agent Skills Specification
 
-### Via Agent Chat
+## How to Create a Skill
 
-When chatting with an agent that has the Skill Creator tool enabled, simply ask:
+When a user asks you to create a skill:
 
-> "Create a skill that can [description of what you want]"
+1. Ask for the skill name (kebab-case), description, and tags
+2. Generate the SKILL.md with proper frontmatter and instructions
+3. Create supporting files in references/ and scripts/ directories
+4. Save to the workspace/skills/ directory
 
-The agent will generate the skill definition, validate it, and offer to install it.
+### Skill Structure
 
-## Skill Format
-
-Every AgentForge skill is a directory with the following structure:
+Every AgentForge skill follows the Agent Skills Specification:
 
 ```
 skills/
   my-skill/
-    SKILL.md          # Documentation and instructions
-    index.ts          # Main skill entry point
-    config.json       # Skill metadata and configuration
+    SKILL.md          # Instructions and metadata (frontmatter)
+    references/       # Supporting documentation (optional)
+    scripts/          # Executable scripts (optional)
+    assets/           # Images and other files (optional)
 ```
 
-### config.json
+### SKILL.md Format
 
-```json
-{
-  "name": "my-skill",
-  "version": "1.0.0",
-  "description": "What this skill does",
-  "category": "utility",
-  "author": "Your Name",
-  "tools": ["tool-name-1", "tool-name-2"],
-  "dependencies": [],
-  "agentInstructions": "Additional instructions for agents using this skill"
-}
-```
+```markdown
+---
+name: my-skill
+description: What this skill does
+version: 1.0.0
+tags:
+  - category1
+  - category2
+---
 
-### index.ts
+# My Skill
 
-```typescript
-import { z } from 'zod';
+Instructions for the agent on how to use this skill.
 
-export const tools = [
-  {
-    name: 'my-tool',
-    description: 'What this tool does',
-    inputSchema: z.object({
-      param1: z.string().describe('Description of param1'),
-    }),
-    outputSchema: z.object({
-      result: z.string(),
-    }),
-    handler: async (input: { param1: string }) => {
-      // Your tool logic here
-      return { result: `Processed: ${input.param1}` };
-    },
-  },
-];
-
-export default { tools };
+## Steps
+1. Step one
+2. Step two
 ```
 
-## Example Skills
-
-### 1. Web Search Skill
+## CLI Commands
 
-```typescript
-// skills/web-search/index.ts
-import { z } from 'zod';
-
-export const tools = [
-  {
-    name: 'web-search',
-    description: 'Search the web for information',
-    inputSchema: z.object({
-      query: z.string().describe('Search query'),
-      maxResults: z.number().optional().default(5),
-    }),
-    outputSchema: z.object({
-      results: z.array(z.object({
-        title: z.string(),
-        url: z.string(),
-        snippet: z.string(),
-      })),
-    }),
-    handler: async (input) => {
-      // Implement with your preferred search API
-      const response = await fetch(
-        `https://api.search.example/search?q=${encodeURIComponent(input.query)}&limit=${input.maxResults}`
-      );
-      const data = await response.json();
-      return { results: data.results };
-    },
-  },
-];
-```
-
-### 2. Calculator Skill
-
-```typescript
-// skills/calculator/index.ts
-import { z } from 'zod';
-
-export const tools = [
-  {
-    name: 'calculate',
-    description: 'Evaluate a mathematical expression',
-    inputSchema: z.object({
-      expression: z.string().describe('Math expression to evaluate (e.g., "2 + 2 * 3")'),
-    }),
-    outputSchema: z.object({
-      result: z.number(),
-      expression: z.string(),
-    }),
-    handler: async (input) => {
-      const result = Function('"use strict"; return (' + input.expression + ')')();
-      return { result: Number(result), expression: input.expression };
-    },
-  },
-];
-```
-
-### 3. File Reader Skill
-
-```typescript
-// skills/file-reader/index.ts
-import { z } from 'zod';
-import { readFile } from 'fs/promises';
-
-export const tools = [
-  {
-    name: 'read-file',
-    description: 'Read the contents of a file',
-    inputSchema: z.object({
-      path: z.string().describe('Path to the file'),
-      encoding: z.string().optional().default('utf-8'),
-    }),
-    outputSchema: z.object({
-      content: z.string(),
-      size: z.number(),
-    }),
-    handler: async (input) => {
-      const content = await readFile(input.path, input.encoding as BufferEncoding);
-      return { content, size: content.length };
-    },
-  },
-];
-```
+```bash
+# Create a new skill interactively
+agentforge skills create
 
-### 4. JSON Transformer Skill
+# Install a skill from the registry
+agentforge skills install <name>
 
-```typescript
-// skills/json-transformer/index.ts
-import { z } from 'zod';
+# List installed skills
+agentforge skills list
 
-export const tools = [
-  {
-    name: 'transform-json',
-    description: 'Transform JSON data using a jq-like expression',
-    inputSchema: z.object({
-      data: z.string().describe('JSON string to transform'),
-      path: z.string().describe('Dot-notation path to extract (e.g., "users.0.name")'),
-    }),
-    outputSchema: z.object({
-      result: z.any(),
-    }),
-    handler: async (input) => {
-      const obj = JSON.parse(input.data);
-      const parts = input.path.split('.');
-      let current: any = obj;
-      for (const part of parts) {
-        current = current?.[part] ?? current?.[Number(part)];
-      }
-      return { result: current };
-    },
-  },
-];
-```
+# Browse the registry
+agentforge skills list --registry
 
-### 5. HTTP Request Skill
+# Search for skills
+agentforge skills search <query>
 
-```typescript
-// skills/http-request/index.ts
-import { z } from 'zod';
+# Get skill details
+agentforge skills info <name>
 
-export const tools = [
-  {
-    name: 'http-request',
-    description: 'Make an HTTP request to any URL',
-    inputSchema: z.object({
-      url: z.string().url().describe('URL to request'),
-      method: z.enum(['GET', 'POST', 'PUT', 'DELETE']).default('GET'),
-      headers: z.record(z.string()).optional(),
-      body: z.string().optional(),
-    }),
-    outputSchema: z.object({
-      status: z.number(),
-      body: z.string(),
-      headers: z.record(z.string()),
-    }),
-    handler: async (input) => {
-      const response = await fetch(input.url, {
-        method: input.method,
-        headers: input.headers,
-        body: input.body,
-      });
-      const body = await response.text();
-      const headers: Record<string, string> = {};
-      response.headers.forEach((v, k) => { headers[k] = v; });
-      return { status: response.status, body, headers };
-    },
-  },
-];
+# Remove a skill
+agentforge skills remove <name>
 ```
 
-## Creating Skills with AI
-
-When you ask an agent to create a skill, the Skill Creator tool will:
-
-1. **Parse your request** — Understand what the skill should do
-2. **Generate the code** — Create `index.ts` with proper Zod schemas
-3. **Create metadata** — Generate `config.json` with name, description, category
-4. **Write documentation** — Generate `SKILL.md` with usage instructions
-5. **Validate** — Ensure the skill compiles and schemas are correct
-6. **Install** — Save to your `skills/` directory and register with Convex
-
 ## Categories
 
-Skills are organized by category:
+Skills are organized by tags:
 
-| Category | Description | Examples |
-|----------|-------------|---------|
-| `utility` | General-purpose tools | Calculator, JSON transformer |
+| Tag | Description | Examples |
+|-----|-------------|---------|
 | `web` | Web interaction | HTTP requests, web search, scraping |
-| `file` | File operations | Read, write, transform files |
+| `files` | File operations | Read, write, organize files |
 | `data` | Data processing | CSV parsing, data analysis |
-| `integration` | External services | Slack, GitHub, email |
-| `ai` | AI-powered tools | Summarization, translation |
-| `custom` | User-defined | Anything else |
+| `development` | Dev tools | Code review, git workflow, linting |
+| `api` | API interaction | REST testing, API integration |
+| `utility` | General-purpose | Calculator, text processing |
+
+## Guidelines
+
+- Skills are instruction-based — they teach agents HOW to do things
+- The Mastra Workspace provides the tools (filesystem, sandbox, search)
+- Skills provide the knowledge and procedures
+- Follow the Agent Skills Specification for compatibility