agents/SKILL.md

name, description, metadata

name	description	metadata
agents	Agent instance management with personalities	version vibestack 1.0.0 main false

Agents Skill

Manages Claude agent instances with different personalities.

Concepts

• Personality: Template (CLAUDE.md + context) defining an agent's "soul"
• Instance: Running Claude process with a personality
• Workspace: Directory where an instance does its work

Directory Structure

/personalities/           # Soul templates
├── orchestrator/
│   ├── CLAUDE.md         # System prompt / instructions
│   ├── config.yaml       # Optional: defaults
│   └── context/          # Reference docs
├── frontend-dev/
└── backend-dev/

/workspaces/              # Where work happens
├── project-a/
└── project-b/

Configuration

Variable	Description	Default
AGENTS_PORT	API port	8800
PERSONALITIES_DIR	Personalities location	/personalities
WORKSPACES_DIR	Workspaces location	/workspaces
AGENTS_DOMAIN	Domain for Caddy	(none)

API

Personalities

# List all personalities
GET /personalities

# Get personality details
GET /personalities/{name}

Instances

# Spawn new instance
POST /instances
{
  "personality": "frontend-dev",
  "workspace": "/workspaces/my-app",  # optional
  "name": "frontend-1"                 # optional, auto-generated
}

# List running instances
GET /instances

# Get instance details
GET /instances/{id}

# Kill instance
DELETE /instances/{id}

# Quick spawn with defaults
POST /spawn/{personality}

Conversations

# List conversations
GET /conversations

# Get conversation messages
GET /conversations/{id}

Personality Config

Optional config.yaml in personality folder:

name: frontend-dev
description: React/TypeScript specialist
default_workspace: /workspaces/frontend
model: claude-sonnet-4-20250514
max_turns: 20
max_instances: 3
lifecycle: on-demand  # or long-running
tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep

Storage

Auto-detects available storage:

1. PostgreSQL (if postgres skill present)
2. DuckDB (if duckdb skill present)
3. SQLite (fallback)

Instance Discovery

Instances can discover each other:

# From any instance
curl http://localhost:8800/instances

System prompt includes peer info at spawn time.

Example: Spawning from Claude

An orchestrator agent can spawn specialists:

curl -X POST http://localhost:8800/instances \
  -d '{"personality":"frontend-dev","workspace":"/workspaces/app"}'