---
sidebar_position: 2
title: "@zibby/skills"
---

# @zibby/skills

> Looking for skill-specific docs and examples? See [Skills reference](../skills/index.md).

Built-in skill definitions for Zibby's test automation framework.

```bash
npm install @zibby/skills
```

> Installed automatically as a dependency of `@zibby/cli`.

## What Are Skills?

A **skill** is a declarative description of an MCP (Model Context Protocol) server and the tools it exposes. Skills are the bridge between your agent nodes and external capabilities like browser automation, Jira, GitHub, Slack, and test memory.

Skills are **agent-agnostic** — the same skill definition works across Cursor, Claude, and Codex. The framework resolves the skill into the right MCP configuration for whichever agent is active.

## Built-in Skills

| Skill ID | MCP Server | Tools Provided |
|---|---|---|
| `browser` | `@zibby/mcp-browser` / `@playwright/mcp` | Browser navigation, clicking, typing, snapshots, video |
| `memory` | `@zibby/mcp-memory` | Test history, selector stability, page model, save insights |
| `jira` | `@zibby/mcp-jira` | Read/write Jira tickets |
| `github` | GitHub MCP server | Repository access, PR creation |
| `slack` | Slack MCP server | Send notifications, post results |

## Using Skills in Nodes

Declare skills in a node definition:

```javascript
import { SKILLS } from '@zibby/core';

export const executeLiveNode = {
  name: 'execute_live',
  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
  prompt: (state) => `Execute the test: ${state.testSpec}`,
  outputSchema: ExecutionSchema,
};
```

When the agent runs:
1. The framework reads the node's `skills` array
2. For each skill, calls `skill.resolve()` to get the MCP server config
3. Injects the resolved MCP server into the agent's environment
4. Appends the skill's `promptFragment` to the prompt (if defined)
5. Runs skill middleware (if defined)

## Skill Anatomy

Every skill has this shape:

```javascript
{
  id: 'browser',                           // Unique identifier
  type: 'mcp',                             // 'mcp' or 'function'
  serverName: 'playwright',                // MCP server name
  allowedTools: ['mcp__playwright__*'],     // Tool patterns for Claude SDK
  cursorKey: 'playwright-official',         // Key in ~/.cursor/mcp.json
  sessionEnvKey: 'ZIBBY_SESSION_INFO',     // Env var with session path
  envKeys: [],                             // Required env vars
  description: 'Playwright Browser MCP',

  // Prompt text appended to every node that uses this skill
  promptFragment: 'Execute using browser tools...',

  // Returns MCP server config { command, args, env }
  resolve({ sessionPath, workspace }) {
    return {
      command: 'node',
      args: ['/path/to/mcp-server.js', '--output-dir', sessionPath],
    };
  },

  // Optional: middleware factory (called once per graph run)
  async middleware() {
    return async (nodeName, next, stateValues, state) => {
      // Pre-node logic (e.g., load test history)
      const result = await next();
      // Post-node logic (e.g., persist insights)
      return result;
    };
  },

  // Tool schemas for compile-time validation
  tools: [
    { name: 'tool_name', description: '...', input_schema: { ... } }
  ],
}
```

## Creating Custom Skills

### MCP Skill (wraps an external MCP server)

```javascript
import { skill } from '@zibby/skills';

export const linear = skill('linear', {
  description: 'Linear issue tracker',
  serverName: 'linear',
  allowedTools: ['mcp__linear__*'],
  envKeys: ['LINEAR_API_KEY'],
  resolve() {
    if (!process.env.LINEAR_API_KEY) return null;
    return {
      command: 'npx',
      args: ['-y', '@anthropic/linear-mcp-server'],
      env: { LINEAR_API_KEY: process.env.LINEAR_API_KEY },
    };
  },
});
```

Use it in a node:

```javascript
graph.addNode('create_issue', {
  name: 'create_issue',
  skills: ['linear'],
  prompt: (state) => `Create a Linear issue for: ${state.bugReport}`,
  outputSchema: IssueSchema,
});
```

### Function Skill (single tool, auto-bridged to MCP)

For simple tools that don't need a full MCP server:

```javascript
import { skill } from '@zibby/skills';

export const calculator = skill('calculator', {
  description: 'Perform arithmetic calculations',
  input: {
    expression: 'string',
  },
  handler: async ({ expression }) => {
    const result = eval(expression); // simplified example
    return { result: String(result) };
  },
});
```

The framework automatically spawns a lightweight MCP bridge server for function skills at runtime.

### Skill with Middleware

Middleware runs before and after every node that uses the skill:

```javascript
import { skill } from '@zibby/skills';

export const audit = skill('audit', {
  description: 'Audit logging',
  resolve() { return null; }, // No MCP server needed
  async middleware() {
    return async (nodeName, next, stateValues, state) => {
      console.log(`[audit] Node ${nodeName} starting`);
      const startTime = Date.now();
      const result = await next();
      console.log(`[audit] Node ${nodeName} completed in ${Date.now() - startTime}ms`);
      return result;
    };
  },
});
```

## Browser Skill Details

The browser skill resolves to `@zibby/mcp-browser` if installed, otherwise falls back to `@playwright/mcp`:

```javascript
// Resolution priority:
// 1. MCP_BROWSER_PATH env var
// 2. @zibby/mcp-browser (enhanced: stable IDs, event recording)
// 3. @playwright/mcp (community fallback)
```

Default configuration:
- Video resolution: 1280x720
- Viewport: 1280x720
- Output directory: session path or `test-results/`

## Memory Skill Details

The memory skill provides five tools:

| Tool | Description |
|---|---|
| `memory_get_test_history` | Query recent test runs with pass/fail results |
| `memory_get_selectors` | Query known selectors with stability metrics |
| `memory_get_page_model` | Query page structure — elements, roles, selectors |
| `memory_get_navigation` | Query known page-to-page transitions |
| `memory_save_insight` | Save observations for future runs (selector tips, timing, workarounds) |

The memory skill also includes middleware that automatically loads relevant test history before node execution.

## Exports

```javascript
import { SKILLS } from '@zibby/skills';
// SKILLS.BROWSER, SKILLS.JIRA, SKILLS.GITHUB, SKILLS.SLACK, SKILLS.MEMORY

import { browserSkill, jiraSkill, githubSkill, slackSkill, memorySkill } from '@zibby/skills';

import { skill, functionSkill } from '@zibby/skills';

// Re-exported from @zibby/core
import { registerSkill, getSkill, hasSkill, getAllSkills, listSkillIds } from '@zibby/skills';
```