personal-squad

---
name: "personal-squad"
description: "User-level AI agents that travel with you across projects"
domain: "configuration"
confidence: "medium"
source: "manual"
---

# Personal Squad — Skill Document

## What is a Personal Squad?

A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session.

## Directory Structure

```
~/Library/Application Support/squad/personal-squad/    # macOS
~/.config/squad/personal-squad/                        # Linux
%APPDATA%/squad/personal-squad/                        # Windows
├── agents/
│   ├── {agent-name}/
│   │   ├── charter.md
│   │   └── history.md
│   └── ...
└── config.json                    # Optional: personal squad config
```

## How It Works

1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory
2. **Merge:** Personal agents are merged into the session cast alongside project agents
3. **Ghost Protocol:** Personal agents can read project state but not write to it
4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery

## Commands

- `squad personal init` — Bootstrap a personal squad directory
- `squad personal list` — List your personal agents
- `squad personal add {name} --role {role}` — Add a personal agent
- `squad personal remove {name}` — Remove a personal agent
- `squad cast` — Show the current session cast (project + personal)

## Ghost Protocol

See `templates/ghost-protocol.md` for the full rules. Key points:
- Personal agents advise; project agents execute
- No writes to project `.squad/` state
- Transparent origin tagging in logs
- Project agents take precedence on conflicts

## Configuration

Optional `config.json` in the personal squad directory:
```json
{
  "defaultModel": "auto",
  "ghostProtocol": true,
  "agents": {}
}
```

## Environment Variables

- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery
- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path