ai-specialists

Original source / Raw SKILL.md

---
name: ai-specialists
description: Interact with AI Specialists via the AI Specialists Hub MCP endpoint. Use when the user asks about any of their AI specialists (e.g. Ruby, Peter, Benjamin, Marty), wants to read/write specialist documents, manage meal plans, check specialist workspaces, hire/dismiss specialists, or work with any MCP-connected specialist. Also use when the user mentions "specialist", "AI specialist", "MCP", or refers to a specialist by name.
---

# AI Specialists Hub - MCP Integration

## Connection

Call the MCP endpoint via HTTP POST. The endpoint URL is stored in TOOLS.md or provided by the user.

```bash
curl -s -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{...}}}'
```

**Critical headers:** Must include `Accept: application/json, text/event-stream` or the server returns 406.

**Response format:** SSE — parse with: `response.split('data: ')[1]` → JSON → `result.content[0].text`

## Available Tools

### Discovery & Management
| Tool | Required Params | Description |
|------|----------------|-------------|
| `list_specialists` | — | List all hired specialists |
| `list_specialist_types` | — | List available specialist types |
| `hire_specialist` | `type`, `name` | Hire a new specialist |
| `dismiss_specialist` | `specialist` | Remove a specialist |
| `import_specialist` | `url` | Import from GitHub URL |
| `get_specialist_overview` | `specialist` | Get specialist summary |

### Workspace Navigation
| Tool | Required Params | Description |
|------|----------------|-------------|
| `explore_specialist_tree` | `specialist` | Full folder/file tree |
| `list_specialist_folder` | `specialist`, `folder_path` | List folder contents |

### Document Operations
| Tool | Required Params | Description |
|------|----------------|-------------|
| `read_specialist_document` | `specialist`, `document_path` | Read one document |
| `read_specialist_documents` | `specialist`, `document_paths` (array) | Bulk read multiple docs |
| `update_specialist_document` | `specialist`, `document_path`, `content` | Create or update a doc |
| `delete_specialist_document` | `specialist`, `document_path` | Delete a document |

### Folder Operations
| Tool | Required Params | Description |
|------|----------------|-------------|
| `create_specialist_folder` | `specialist`, `folder_path` | Create folder (recursive) |
| `delete_specialist_folder` | `specialist`, `folder_path` | Delete folder and contents |

**Parameter note:** The specialist identifier is always the `id` field from `list_specialists`, not the display name. Use lowercase (e.g. `ruby`, `peter`, `benjamin`).

## Working with a Specialist

Every specialist has an `ai-instructions/` folder containing their identity and behavioral instructions. **Always read these first** when working with a specialist you haven't loaded yet:

```
ai-instructions/
├── core-instructions.md    # Who they are, what they do, how they behave
└── getting_started.md      # Initialization sequence, workspace structure
```

### Pattern: First interaction with a specialist

1. `list_specialists` → find the specialist id
2. `read_specialist_documents` → read `ai-instructions/core-instructions.md` and `ai-instructions/getting_started.md`
3. Understand their domain, workspace structure, and communication style
4. `explore_specialist_tree` → see their full workspace
5. Now you can work with their data informed by their context

### Pattern: Quick data retrieval

1. `explore_specialist_tree` → find the files you need
2. `read_specialist_documents` → bulk read (more efficient than individual reads)
3. Summarize for the user

### Pattern: Updating specialist data

1. Read the existing document first
2. Modify content as needed
3. `update_specialist_document` → write back (creates if new, overwrites if existing)
4. For new folders: `create_specialist_folder` first, then write documents into it

## User Signup (Agent-Initiated Onboarding)

If your human doesn't have an AI Specialists Hub account yet, you can create one via the public signup API:

```bash
curl -s -X POST "https://aispecialistshub.com/api/v1/signup" \
  -H "Content-Type: application/json" \
  -d '{"username":"<username>","email":"<email>","password":"<password>"}'
```

**Response (201):**
```json
{
  "username": "...",
  "mcpKey": "...",
  "accountStatus": "unverified",
  "specialistLimit": 2,
  "message": "..."
}
```

### ⚠️ CRITICAL: Credential Handoff

**You MUST provide all credentials to the human.** Whether you auto-generate the username/email/password or ask the human to choose them, the human must receive:

1. **Username** — for web dashboard login at aispecialistshub.com
2. **Email** — used for account verification
3. **Password** — for web dashboard login
4. **MCP key** — for connecting AI tools to their specialists

Never keep credentials from the human. They own the account. Present all four clearly after signup.

### Unverified Accounts

- Limited to **2 specialists** (default: Friday is auto-hired)
- Full MCP access — specialists work immediately
- Can log in to web dashboard with username/password
- Verify email for full access (more specialists)

### Signup Flow

1. Confirm the human wants an AI Specialists Hub account
2. Collect or generate: username, email, password
3. Call `POST /api/v1/signup`
4. **Give the human ALL credentials** (username, email, password, MCP key)
5. Store the MCP endpoint URL in your config: `https://aispecialistshub.com/api/v1/mcp/<username>/<mcpKey>`
6. Start using specialists via MCP

## Configuration

Store the MCP endpoint URL in TOOLS.md:

```markdown
### AI Specialists Hub
- MCP endpoint: https://aispecialistshub.com/api/v1/mcp/<user>/<key>
```

See `references/specialists-guide.md` for details on specialist workspace conventions.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/specialists-guide.md

```markdown
# AI Specialists - Workspace Conventions

## Specialist Workspace Structure

Each specialist has a structured workspace tailored to their domain. Common patterns:

```
specialist/
├── ai-instructions/          # ALWAYS present
│   ├── core-instructions.md  # Identity, capabilities, communication style
│   └── getting_started.md    # Init sequence, workspace map, protocols
├── preferences/              # User preferences relevant to this domain
├── [domain-folders]/         # Domain-specific content
└── README.md                 # Optional overview
```

## Known Specialist Types

These are types available on AI Specialists Hub. Each user hires instances with custom names:

- **Friday-Personal-Planning** — Personal planning, family stewardship, scheduling
- **peter-product-manager** — Product management, strategic work organization
- **marty-moltbook** — Social media management for Moltbook AI agent network
- **creator** — Interactive workshop for creating new AI specialists
- **dnd-character-development** — D&D character building
- **game-collection-manager** — Board/video game collection tracking
- **github-import** — Specialists imported from GitHub repos (e.g. recipe planners, custom specialists)

## Workspace Patterns by Domain

### Meal Planner (e.g. Ruby)
```
meal-planner/YYYY/MM-month/    # Monthly folders with weekly plans and event plans
recipes/                        # Categorized recipe collection
shopping/                       # Shopping lists, pantry, store preferences
cooking-notes/                  # Tips, substitutions, lessons learned
preferences/                    # Dietary restrictions, cooking style, household info
```

Date convention: `meal-planner/2026/01-january/week-jan-1.md`

### Product Manager (e.g. Peter)
Tracks projects, decisions, strategic context. Read their `ai-instructions/` for specifics.

### Personal Planner (e.g. Benjamin)
Family planning, budgets, goals. Read their `ai-instructions/` for specifics.

## Tips

- **Bulk reads are cheaper** — Use `read_specialist_documents` with an array instead of multiple single reads
- **Trees are free** — `explore_specialist_tree` gives you the full layout in one call
- **Create folders first** — Before writing docs to a new path, create the folder
- **Specialists don't talk to each other** — You (the agent) are the bridge between specialists
- **Respect their style** — Each specialist has a defined communication style in their instructions. When writing to their workspace, match their conventions.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "erikashby",
  "slug": "ai-specialists",
  "displayName": "Ai Specialists",
  "latest": {
    "version": "1.1.0",
    "publishedAt": 1771687811516,
    "commit": "https://github.com/openclaw/skills/commit/6065c7184b981cd7f7ad122c841301a606a5c83e"
  },
  "history": [
    {
      "version": "1.0.0",
      "publishedAt": 1771553224570,
      "commit": "https://github.com/openclaw/skills/commit/b9d5478cac2addd21034e551286cf1db06f1e546"
    }
  ]
}

```

### scripts/mcp-call.sh

```bash
#!/bin/bash
# MCP tool call helper
# Usage: mcp-call.sh <endpoint-url> <tool-name> '<json-arguments>'
# Example: mcp-call.sh https://aispecialistshub.com/api/v1/mcp/user/key list_specialists '{}'

set -euo pipefail

URL="${1:?Usage: mcp-call.sh <endpoint-url> <tool-name> '<json-arguments>'}"
TOOL="${2:?Missing tool name}"
ARGS="${3:-\{\}}"

# Build payload via python to avoid shell escaping issues
PAYLOAD=$(python3 -c "
import json, sys
print(json.dumps({
    'jsonrpc': '2.0',
    'id': 1,
    'method': 'tools/call',
    'params': {
        'name': sys.argv[1],
        'arguments': json.loads(sys.argv[2])
    }
}))
" "$TOOL" "$ARGS")

RESPONSE=$(curl -s -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d "$PAYLOAD")

# Parse SSE response
echo "$RESPONSE" | python3 -c "
import sys, json
raw = sys.stdin.read()
try:
    data = raw.split('data: ')[1]
    result = json.loads(data)
    if 'error' in result:
        print(json.dumps(result['error'], indent=2))
        sys.exit(1)
    for content in result['result']['content']:
        print(content['text'])
except (IndexError, json.JSONDecodeError, KeyError) as e:
    print(f'Parse error: {e}', file=sys.stderr)
    print(raw, file=sys.stderr)
    sys.exit(1)
"

```