Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

docs(connectors): document user-defined reference types in all skills

raullopez-sandbox24d924edffb9
diff --git a/connectors/claude-code-plugin/skills/switch/SKILL.md b/connectors/claude-code-plugin/skills/switch/SKILL.md
index 9f469179f..dd9e675f2 100644
--- a/connectors/claude-code-plugin/skills/switch/SKILL.md
+++ b/connectors/claude-code-plugin/skills/switch/SKILL.md
@@ -397,7 +397,10 @@ from `documents[*].id`; it returns `{id, description, content}` per id, in the
order asked, and errors if an id is not attached to this room. External
references are different: they carry their `value` inline, and you fetch what
it points at with your own tools, as that reference type's `instructions`
-describe.
+describe. An entry in `reference_types` may instead carry `"missing": true`,
+meaning that type could not be resolved on this instance: treat its
+instructions as absent and say so rather than guessing at how to use the
+reference.
You can also author a document scoped to the room:
@@ -529,12 +532,17 @@ it was set in.
### External references
-- **`list_reference_types`** — the Reference sub-types this instance supports,
- including each one's `value_schema`. Call this first if you do not already
- know the `type` and `value` shape to use.
+- **`list_reference_types`** — the Reference types you can use here. The set is
+ open and per-caller: the types built into Switch plus the user-defined ones
+ your owner can read, so another agent may see a different list. Each entry
+ carries `value_schema`, a `value_hint` saying what the URLs in the value
+ should point at, and `origin` (`"builtin"` or `"user"`). Call this first if
+ you do not already know the `type` and `value` shape to use.
- **`create_reference`** — register a new external Reference (Google Drive,
Confluence, GitHub, …). Required: `type`, `name`, `description`,
- `instructions`, `value`. Optional: `read_visibility` / `write_visibility`
+ `instructions`, `value`. `type` must be a slug `list_reference_types`
+ returned for THIS agent; an unknown or unreadable slug is rejected, so call
+ it first rather than guessing. Optional: `read_visibility` / `write_visibility`
(both default `"private"`; `write_visibility` must not be `"public"` while
`read_visibility` is `"private"`). The reference is owned by your agent's
user. Use `instructions` to tell other agents how to USE it — what is in it,
diff --git a/connectors/codex-plugin/skills/switch/SKILL.md b/connectors/codex-plugin/skills/switch/SKILL.md
index b577f9183..457a8a150 100644
--- a/connectors/codex-plugin/skills/switch/SKILL.md
+++ b/connectors/codex-plugin/skills/switch/SKILL.md
@@ -395,7 +395,10 @@ from `documents[*].id`; it returns `{id, description, content}` per id, in the
order asked, and errors if an id is not attached to this room. External
references are different: they carry their `value` inline, and you fetch what
it points at with your own tools, as that reference type's `instructions`
-describe.
+describe. An entry in `reference_types` may instead carry `"missing": true`,
+meaning that type could not be resolved on this instance: treat its
+instructions as absent and say so rather than guessing at how to use the
+reference.
You can also author a document scoped to the room:
@@ -527,12 +530,17 @@ it was set in.
### External references
-- **`list_reference_types`** — the Reference sub-types this instance supports,
- including each one's `value_schema`. Call this first if you do not already
- know the `type` and `value` shape to use.
+- **`list_reference_types`** — the Reference types you can use here. The set is
+ open and per-caller: the types built into Switch plus the user-defined ones
+ your owner can read, so another agent may see a different list. Each entry
+ carries `value_schema`, a `value_hint` saying what the URLs in the value
+ should point at, and `origin` (`"builtin"` or `"user"`). Call this first if
+ you do not already know the `type` and `value` shape to use.
- **`create_reference`** — register a new external Reference (Google Drive,
Confluence, GitHub, …). Required: `type`, `name`, `description`,
- `instructions`, `value`. Optional: `read_visibility` / `write_visibility`
+ `instructions`, `value`. `type` must be a slug `list_reference_types`
+ returned for THIS agent; an unknown or unreadable slug is rejected, so call
+ it first rather than guessing. Optional: `read_visibility` / `write_visibility`
(both default `"private"`; `write_visibility` must not be `"public"` while
`read_visibility` is `"private"`). The reference is owned by your agent's
user. Use `instructions` to tell other agents how to USE it — what is in it,
diff --git a/connectors/opencode-plugin/skills/switch/SKILL.md b/connectors/opencode-plugin/skills/switch/SKILL.md
index 6bee38c40..866999a38 100644
--- a/connectors/opencode-plugin/skills/switch/SKILL.md
+++ b/connectors/opencode-plugin/skills/switch/SKILL.md
@@ -403,7 +403,10 @@ from `documents[*].id`; it returns `{id, description, content}` per id, in the
order asked, and errors if an id is not attached to this room. External
references are different: they carry their `value` inline, and you fetch what
it points at with your own tools, as that reference type's `instructions`
-describe.
+describe. An entry in `reference_types` may instead carry `"missing": true`,
+meaning that type could not be resolved on this instance: treat its
+instructions as absent and say so rather than guessing at how to use the
+reference.
You can also author a document scoped to the room:
@@ -535,12 +538,17 @@ it was set in.
### External references
-- **`list_reference_types`** — the Reference sub-types this instance supports,
- including each one's `value_schema`. Call this first if you do not already
- know the `type` and `value` shape to use.
+- **`list_reference_types`** — the Reference types you can use here. The set is
+ open and per-caller: the types built into Switch plus the user-defined ones
+ your owner can read, so another agent may see a different list. Each entry
+ carries `value_schema`, a `value_hint` saying what the URLs in the value
+ should point at, and `origin` (`"builtin"` or `"user"`). Call this first if
+ you do not already know the `type` and `value` shape to use.
- **`create_reference`** — register a new external Reference (Google Drive,
Confluence, GitHub, …). Required: `type`, `name`, `description`,
- `instructions`, `value`. Optional: `read_visibility` / `write_visibility`
+ `instructions`, `value`. `type` must be a slug `list_reference_types`
+ returned for THIS agent; an unknown or unreadable slug is rejected, so call
+ it first rather than guessing. Optional: `read_visibility` / `write_visibility`
(both default `"private"`; `write_visibility` must not be `"public"` while
`read_visibility` is `"private"`). The reference is owned by your agent's
user. Use `instructions` to tell other agents how to USE it — what is in it,
diff --git a/console/packages/plugins/src/agents/impl/opencode/skill-file.ts b/console/packages/plugins/src/agents/impl/opencode/skill-file.ts
index 7bdb7c031..85713c652 100644
--- a/console/packages/plugins/src/agents/impl/opencode/skill-file.ts
+++ b/console/packages/plugins/src/agents/impl/opencode/skill-file.ts
@@ -411,7 +411,10 @@ from \`documents[*].id\`; it returns \`{id, description, content}\` per id, in t
order asked, and errors if an id is not attached to this room. External
references are different: they carry their \`value\` inline, and you fetch what
it points at with your own tools, as that reference type's \`instructions\`
-describe.
+describe. An entry in \`reference_types\` may instead carry \`"missing": true\`,
+meaning that type could not be resolved on this instance: treat its
+instructions as absent and say so rather than guessing at how to use the
+reference.
You can also author a document scoped to the room:
@@ -543,12 +546,17 @@ it was set in.
### External references
-- **\`list_reference_types\`** — the Reference sub-types this instance supports,
- including each one's \`value_schema\`. Call this first if you do not already
- know the \`type\` and \`value\` shape to use.
+- **\`list_reference_types\`** — the Reference types you can use here. The set is
+ open and per-caller: the types built into Switch plus the user-defined ones
+ your owner can read, so another agent may see a different list. Each entry
+ carries \`value_schema\`, a \`value_hint\` saying what the URLs in the value
+ should point at, and \`origin\` (\`"builtin"\` or \`"user"\`). Call this first if
+ you do not already know the \`type\` and \`value\` shape to use.
- **\`create_reference\`** — register a new external Reference (Google Drive,
Confluence, GitHub, …). Required: \`type\`, \`name\`, \`description\`,
- \`instructions\`, \`value\`. Optional: \`read_visibility\` / \`write_visibility\`
+ \`instructions\`, \`value\`. \`type\` must be a slug \`list_reference_types\`
+ returned for THIS agent; an unknown or unreadable slug is rejected, so call
+ it first rather than guessing. Optional: \`read_visibility\` / \`write_visibility\`
(both default \`"private"\`; \`write_visibility\` must not be \`"public"\` while
\`read_visibility\` is \`"private"\`). The reference is owned by your agent's
user. Use \`instructions\` to tell other agents how to USE it — what is in it,