npm package: @mcp-b/char-skill
Description: Claude Code skill for setting up Char - AI agent platform with WebMCP browser automation tools and embedded chat widgets
Author: WebMCP
Latest version: 3.0.0

# Char Setup Assistant - Claude Code Skill

A production-ready Claude Code skill that guides you through setting up Char - an AI agent platform with WebMCP browser automation tools and embedded chat widgets.

[![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](skills/char-setup/CHANGELOG.md)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## What This Skill Does

Helps you integrate Char AI agents into websites with:
- **WebMCP Tools** - Browser automation (click, fill forms, navigate, screenshot)
- **Embedded Agent Widget** - Drop-in chat UI powered by `@mcp-b/char`
- **Visual Integration** - Automatic theme matching with your website's design
- **Stateless Mode** - Quick setup using your own Anthropic API key (no backend needed)

## Features

✨ **Automated Setup**
- Creates demo pages or adds to existing websites
- Auto-detects and matches your website's design (colors, fonts, spacing)
- Takes before/after screenshots for verification
- Generates matching theme configuration

🎨 **Visual Integration**
- Extracts color palette from your page
- Matches fonts and typography
- Applies consistent border radius
- Ensures accessibility (WCAG contrast ratios)

🛠️ **Developer Experience**
- Quick reference cheat sheet
- Success criteria checklist
- Automated prerequisite verification
- 10 copy-paste ready recipes
- Comprehensive troubleshooting guide

🔧 **Progressive Disclosure**
- Core setup: ~260 lines, loads instantly
- Detailed docs: Loaded only when needed
- 37.5% token usage reduction vs. v1.0

## Quick Start

### 1. Installation

See [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed installation instructions.

**Quick install:**
```bash
# Copy to your Claude Code skills folder
cp -r packages/claude-code-skill-char-setup/skills/char-setup ~/.claude/skills/

# Or install to your project
mkdir -p .claude/skills
cp -r packages/claude-code-skill-char-setup/skills/char-setup .claude/skills/
```

### 2. Verify Prerequisites

```bash
cd packages/claude-code-skill-char-setup/skills/char-setup
node scripts/verify-setup.js

# Optional: Check API key format
node scripts/verify-setup.js --check-api-key sk-ant-...
```

Expected output:
```
✓ Node.js 24.11.1 (>= 14.0.0)
✓ Google Chrome 120 found (>= 90)
✓ Demo template found
✓ Network connectivity to api.anthropic.com
✓ All required checks passed!
```

### 3. Use the Skill

Just ask Claude:

> "Set up Char on my website and match my page's design"

or

> "Create a Char demo page"

The skill will:
1. ✅ Create or modify your HTML page
2. ✅ Extract your page's design (colors, fonts)
3. ✅ Generate matching theme configuration
4. ✅ Add the embedded agent widget
5. ✅ Take verification screenshots
6. ✅ Open the page in your browser

## What You Need

### Required
- **Anthropic API Key** - Get one at https://console.anthropic.com/settings/keys
- **Chrome, Edge, or Chromium 90+** - Required for WebMCP tools
- **Node.js 14+** - For verification script

### Optional (Recommended)
- **Chrome DevTools MCP Server** - For automated browser testing and visual integration
  ```bash
  claude mcp add --transport stdio chrome-devtools -- \
    npx -y @mcp-b/chrome-devtools-mcp
  ```
- **WebMCP Docs MCP** - For documentation lookup (usually pre-installed)

## Documentation

### Getting Started
- **[Installation Guide](docs/INSTALLATION.md)** - Detailed installation instructions
- **[Agent Integration Guide](docs/AGENT_INTEGRATION.md)** - Using the skill in agents
- **[Quick Reference](skills/char-setup/SKILL.md#quick-reference)** - Command cheat sheet
- **[Recipes](skills/char-setup/references/RECIPES.md)** - 10 copy-paste ready patterns

### Configuration
- **[Customization Guide](skills/char-setup/references/CUSTOMIZATION.md)** - Complete theming reference
- **[Visual Integration](skills/char-setup/references/VISUAL_INTEGRATION.md)** - Design matching best practices

### Reference
- **[WebMCP Tools](skills/char-setup/references/WEBMCP_REFERENCE.md)** - Complete tool documentation
- **[Troubleshooting](skills/char-setup/references/TROUBLESHOOTING.md)** - Common issues and solutions

### Advanced
- **[Production Deployment](skills/char-setup/references/PRODUCTION.md)** - Stateful backend setup

### Development
- **[Changelog](skills/char-setup/CHANGELOG.md)** - Version history
- **[Contributing](skills/char-setup/CONTRIBUTING.md)** - How to improve this skill

## File Structure

```
packages/claude-code-skill-char-setup/
├── README.md                           # This file
├── docs/
│   ├── INSTALLATION.md                 # Installation guide
│   └── AGENT_INTEGRATION.md            # Agent integration guide
└── skills/
    └── char-setup/
        ├── SKILL.md                    # Main skill instructions (~260 lines)
        ├── CHANGELOG.md                # Version history
        ├── CONTRIBUTING.md             # Contribution guide
        ├── references/
        │   ├── CUSTOMIZATION.md        # Theme configuration
        │   ├── VISUAL_INTEGRATION.md   # Design integration
        │   ├── WEBMCP_REFERENCE.md     # Tool documentation
        │   ├── TROUBLESHOOTING.md      # Common issues
        │   ├── PRODUCTION.md           # Production deployment
        │   └── RECIPES.md              # Common patterns
        ├── assets/
        │   ├── templates/
        │   │   └── demo.html           # Demo page template
        │   └── scripts/
        │       └── extract-page-styles.js  # Style extraction
        └── scripts/
            └── verify-setup.js         # Prerequisite verification
```

## Example Usage

### Basic Demo Page

```
User: Create a Char demo page

Skill: Creating demo page with:
       - Contact form (name, email, message)
       - Interactive counter
       - Char embedded AI agent widget

       Where should I save it?

User: ./demo.html

Skill: [Creates page, verifies prerequisites]
       What's your Anthropic API key?

User: sk-ant-api03-xxxxx

Skill: [Injects API key, opens in browser]
       ✅ Demo created!
       💡 Try saying: "Fill out the contact form with test data"
```

### Visual Integration (with Chrome DevTools MCP)

```
User: Set up Char on my index.html and match my page's design

Skill: 📸 Taking baseline screenshot...
       🎨 Extracting page styles...
          - Primary: #667eea (purple gradient)
          - Background: #ffffff
          - Font: -apple-system, BlinkMacSystemFont, 'Segoe UI'
          - Radius: 8px

       ⚙️  Generating matching theme configuration...
       ✨ Adding Char widget with custom theme...
       📸 Taking verification screenshots...
          ✅ char-integration-collapsed.png
          ✅ char-integration-expanded.png
          ✅ char-integration-mobile.png

       👀 Visual integration complete!
       Char seamlessly matches your page design.
```

### Add to Existing Page

```
User: Add Char to my landing page at ./public/index.html

Skill: Reading your page...
       I'll add the Char widget before </body>.
       What's your Anthropic API key?

User: sk-ant-xxxxx

Skill: [Adds widget, preserves existing code]
       ✅ Done! Opening in browser...
```

## WebMCP Tools Available

Once set up, your embedded agent can:

| Tool | What It Does |
|------|--------------|
| `click` | Click buttons, links, elements |
| `fill` | Fill form inputs |
| `navigate` | Navigate to URLs |
| `take_snapshot` | Capture page text content |
| `take_screenshot` | Capture visual screenshot |
| `evaluate_script` | Run JavaScript on page |
| `hover` | Hover over elements |
| `press_key` | Keyboard input |

See [WEBMCP_REFERENCE.md](skills/char-setup/references/WEBMCP_REFERENCE.md) for complete documentation.

## Stateless vs Production

### Stateless Mode (This Skill)
- ✅ Quick setup with your API key
- ✅ Perfect for development/testing
- ✅ No backend infrastructure
- ✅ Full WebMCP tool support
- ✅ Visual design matching
- ❌ No user thread persistence
- ❌ Costs on your API account

### Production Mode
- ✅ Stateful backend with Durable Objects
- ✅ Per-user thread persistence
- ✅ Organization dashboard
- ✅ Usage analytics
- ✅ Managed infrastructure
- ⏳ Requires Cloudflare Workers setup

See [PRODUCTION.md](skills/char-setup/references/PRODUCTION.md) for production deployment.

## MCP Integration

This skill adapts based on available MCP servers:

### With Chrome DevTools MCP ✅ (Recommended)

**Automated workflow:**
- Takes screenshots before/after
- Extracts page design automatically
- Generates matching theme
- Verifies visual integration
- Tests WebMCP tools functionality

**Install:**
```bash
claude mcp add --transport stdio chrome-devtools -- \
  npx -y @mcp-b/chrome-devtools-mcp
```

### Without Chrome DevTools MCP ℹ️

**Manual workflow:**
- Creates demo page
- Injects API key
- Provides manual testing instructions
- Recommends installing Chrome DevTools MCP

### WebMCP Docs MCP (Optional)

For documentation lookup during setup:
```bash
# Usually pre-installed, verify with:
/mcp
# Look for: mcp__docs__SearchWebMcpDocumentation
```

## Success Criteria

After setup, you should see:

✅ **Page loads successfully**
- HTML file opens in browser without errors

✅ **Widget appears**
- Chat pill visible in bottom-center or bottom-right

✅ **Console confirms initialization**
```
✅ Char embedded agent initialized!
💡 Try saying: "Fill out the contact form with test data"
```

✅ **Agent responds**
- Click the pill, type a message, get a response

✅ **WebMCP tools work**
- Agent can interact with page elements (click, fill forms)

If any check fails, see [TROUBLESHOOTING.md](skills/char-setup/references/TROUBLESHOOTING.md).

## Development

### Testing Locally

1. **Symlink to your skills directory:**
   ```bash
   ln -s $(pwd)/packages/claude-code-skill-char-setup/skills/char-setup ~/.claude/skills/char-setup-dev
   ```

2. **Restart Claude Code**

3. **Test:**
   ```
   "Use the char-setup skill to create a demo page"
   ```

### Running Verification

```bash
cd packages/claude-code-skill-char-setup/skills/char-setup
node scripts/verify-setup.js
```

### Modifying the Demo Template

Edit [assets/templates/demo.html](skills/char-setup/assets/templates/demo.html) to customize the demo page.

The template uses CSS variables for easy style extraction:
```css
:root {
  --brand-primary: #667eea;
  --brand-secondary: #764ba2;
  --bg-main: white;
  --border-radius-base: 8px;
  --font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI';
}
```

## Contributing

We welcome contributions! See [CONTRIBUTING.md](skills/char-setup/CONTRIBUTING.md) for:
- Bug report templates
- Feature request guidelines
- Pull request process
- Testing requirements
- Code style guidelines

## Changelog

See [CHANGELOG.md](skills/char-setup/CHANGELOG.md) for version history.

**Latest:** v2.0.0 (2026-01-07)
- Progressive disclosure optimization (37.5% token reduction)
- Visual integration workflow
- Quick reference and success criteria
- Automated verification script
- 10 copy-paste ready recipes
- Contributing guide

## License

MIT

## Links

- **WebMCP Documentation**: https://webmcp.ai/docs
- **Char Package**: [@mcp-b/char](https://www.npmjs.com/package/@mcp-b/char)
- **Claude Code**: https://code.claude.com
- **Anthropic Console**: https://console.anthropic.com

## Related Skills

- `playwright-skill` - Full Playwright browser automation
- `webapp-testing` - Anthropic's webapp testing skill
- `dev-browser` - Browser automation for agents

## Support

For issues or questions:
1. Check [TROUBLESHOOTING.md](skills/char-setup/references/TROUBLESHOOTING.md)
2. Review [WEBMCP_REFERENCE.md](skills/char-setup/references/WEBMCP_REFERENCE.md)
3. See [RECIPES.md](skills/char-setup/references/RECIPES.md) for common patterns
4. File an issue: https://github.com/WebMCP-org/char-ai-saas/issues

---

**Made with ❤️ by the WebMCP team**