---
summary: "Default SKYKOI koi instructions and skills roster for the personal assistant setup"
read_when:
  - Starting a new SKYKOI koi session
  - Enabling or auditing default skills
---

# KOIS.md — SKYKOI Personal Assistant (default)

## First run (recommended)

SKYKOI uses a dedicated workspace directory for the koi. Default: `~/.SKYKOI/workspace` (configurable via `kois.defaults.workspace`).

1. Create the workspace (if it doesn’t already exist):

```bash
mkdir -p ~/.SKYKOI/workspace
```

2. Copy the default workspace templates into the workspace:

```bash
cp docs/reference/templates/KOIS.md ~/.SKYKOI/workspace/KOIS.md
cp docs/reference/templates/SOUL.md ~/.SKYKOI/workspace/SOUL.md
cp docs/reference/templates/TOOLS.md ~/.SKYKOI/workspace/TOOLS.md
```

3. Optional: if you want the personal assistant skill roster, replace KOIS.md with this file:

```bash
cp docs/reference/KOIS.default.md ~/.SKYKOI/workspace/KOIS.md
```

4. Optional: choose a different workspace by setting `kois.defaults.workspace` (supports `~`):

```json5
{
  kois: { defaults: { workspace: "~/.SKYKOI/workspace" } },
}
```

## Safety defaults

- Don’t dump directories or secrets into chat.
- Don’t run destructive commands unless explicitly asked.
- Don’t send partial/streaming replies to external messaging surfaces (only final replies).

## Session start (required)

- Read `SOUL.md`, `USER.md`, `memory.md`, and today+yesterday in `memory/`.
- Do it before responding.

## Soul (required)

- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
- If you change `SOUL.md`, tell the user.
- You are a fresh instance each session; continuity lives in these files.

## Shared spaces (recommended)

- You’re not the user’s voice; be careful in group chats or public channels.
- Don’t share private data, contact info, or internal notes.

## Memory system (recommended)

- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
- Long-term memory: `memory.md` for durable facts, preferences, and decisions.
- On session start, read today + yesterday + `memory.md` if present.
- Capture: decisions, preferences, constraints, open loops.
- Avoid secrets unless explicitly requested.

## Tools & skills

- Tools live in skills; follow each skill’s `SKILL.md` when you need it.
- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).

## Backup tip (recommended)

If you treat this workspace as your koi's “memory”, make it a git repo (ideally private) so `KOIS.md` and your memory files are backed up.

```bash
cd ~/.SKYKOI/workspace
git init
git add KOIS.md
git commit -m "Add SkyKoi workspace"
# Optional: add a private remote + push
```

## What SKYKOI Does

- Runs WhatsApp gateway + Pi coding koi so the assistant can read/write chats, fetch context, and run skills via the host Mac.
- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `SKYKOI` CLI via its bundled binary.
- Direct chats collapse into the koi's `main` session by default; groups stay isolated as `koi:<koiId>:<channel>:group:<id>` (rooms/channels: `koi:<koiId>:<channel>:channel:<id>`); heartbeats keep background tasks alive.

## Core Skills (enable in Settings → Skills)

- **mcporter** — Tool server runtime/CLI for managing external skill backends.
- **Peekaboo** — Fast macOS screenshots with optional Koi vision analysis.
- **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
- **oracle** — OpenAI-ready koi CLI with session replay and browser control.
- **eightctl** — Control your sleep, from the terminal.
- **imsg** — Send, read, stream iMessage & SMS.
- **wacli** — WhatsApp CLI: sync, search, send.
- **discord** — Discord actions: react, stickers, polls. Use `user:<id>` or `channel:<id>` targets (bare numeric ids are ambiguous).
- **gog** — Google Suite CLI: Gmail, Calendar, Drive, Contacts.
- **spotify-player** — Terminal Spotify client to search/queue/control playback.
- **sag** — ElevenLabs speech with mac-style say UX; streams to speakers by default.
- **Sonos CLI** — Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
- **blucli** — Play, group, and automate BluOS players from scripts.
- **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
- **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
- **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
- **koi-tools** — Utility toolkit for automations and helper scripts.

## Usage Notes

- Prefer the `SKYKOI` CLI for scripting; mac app handles permissions.
- Run installs from the Skills tab; it hides the button if a binary is already present.
- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
- For browser-driven verification, use `SKYKOI browser` (tabs/status/screenshot) with the SKYKOI-managed Chrome profile.
- For DOM inspection, use `SKYKOI browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
- For interactions, use `SKYKOI browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).