| name | gaia-custom-instructions |
| description | How per-integration custom instructions work — reading them, updating them, and when to persist a user's preference (e.g. "for Slack focus on |
| target | executor |
Per-Integration Custom Instructions
Every connected integration can carry a block of custom instructions — standing
guidance for how the user wants that service used (focus channels, default
projects, conventions). This is the per-integration equivalent of a project's
README: durable, scoped to one integration, honored on every future task.
Where they live
- Source of truth: the user's account (one record per integration).
- Surfaced to the matching subagent automatically every turn, as a
"CUSTOM INSTRUCTIONS FOR " block — the slack subagent always sees
the slack instructions without reading a file.
- Mirrored read-only to
integrations/<id>/agent/instructions.md in the
workspace, so it's also greppable. Never edit that file directly — it's a
projection and the edit won't stick.
- Editable by the user on the integrations page in the app.
Reading them
get_integration_instructions(integration_id) returns the current content.- A subagent already has its own integration's instructions in context, so it
rarely needs to call this. The executor should call it before amending.
Updating them
update_integration_instructions(integration_id, content) saves the FULL new
body (it replaces, it does not append). To amend, read first (or use the block
already in context), merge, then write the whole thing back.
When to persist (and when NOT to)
