136 lines
2.6 KiB
Markdown
136 lines
2.6 KiB
Markdown
---
|
|
name: agents
|
|
description: Agent instance management with personalities
|
|
metadata:
|
|
version: "1.0.0"
|
|
vibestack:
|
|
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
|
|
|
|
```bash
|
|
# List all personalities
|
|
GET /personalities
|
|
|
|
# Get personality details
|
|
GET /personalities/{name}
|
|
```
|
|
|
|
### Instances
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# List conversations
|
|
GET /conversations
|
|
|
|
# Get conversation messages
|
|
GET /conversations/{id}
|
|
```
|
|
|
|
## Personality Config
|
|
|
|
Optional `config.yaml` in personality folder:
|
|
|
|
```yaml
|
|
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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
curl -X POST http://localhost:8800/instances \
|
|
-d '{"personality":"frontend-dev","workspace":"/workspaces/app"}'
|
|
```
|