| 1 | # Personal Squad — Skill Document |
| 2 | |
| 3 | ## What is a Personal Squad? |
| 4 | |
| 5 | 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. |
| 6 | |
| 7 | ## Directory Structure |
| 8 | |
| 9 | ``` |
| 10 | ~/.config/squad/personal-squad/ # Linux/macOS |
| 11 | %APPDATA%/squad/personal-squad/ # Windows |
| 12 | ├── agents/ |
| 13 | │ ├── {agent-name}/ |
| 14 | │ │ ├── charter.md |
| 15 | │ │ └── history.md |
| 16 | │ └── ... |
| 17 | └── config.json # Optional: personal squad config |
| 18 | ``` |
| 19 | |
| 20 | ## How It Works |
| 21 | |
| 22 | 1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory |
| 23 | 2. **Merge:** Personal agents are merged into the session cast alongside project agents |
| 24 | 3. **Ghost Protocol:** Personal agents can read project state but not write to it |
| 25 | 4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery |
| 26 | |
| 27 | ## Commands |
| 28 | |
| 29 | - `squad personal init` — Bootstrap a personal squad directory |
| 30 | - `squad personal list` — List your personal agents |
| 31 | - `squad personal add {name} --role {role}` — Add a personal agent |
| 32 | - `squad personal remove {name}` — Remove a personal agent |
| 33 | - `squad cast` — Show the current session cast (project + personal) |
| 34 | |
| 35 | ## Ghost Protocol |
| 36 | |
| 37 | See `templates/ghost-protocol.md` for the full rules. Key points: |
| 38 | - Personal agents advise; project agents execute |
| 39 | - No writes to project `.squad/` state |
| 40 | - Transparent origin tagging in logs |
| 41 | - Project agents take precedence on conflicts |
| 42 | |
| 43 | ## Configuration |
| 44 | |
| 45 | Optional `config.json` in the personal squad directory: |
| 46 | ```json |
| 47 | { |
| 48 | "defaultModel": "auto", |
| 49 | "ghostProtocol": true, |
| 50 | "agents": {} |
| 51 | } |
| 52 | ``` |
| 53 | |
| 54 | ## Environment Variables |
| 55 | |
| 56 | - `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery |
| 57 | - `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path |