> ## Documentation Index > Fetch the complete documentation index at: https://docs.waterr.ai/llms.txt > Use this file to discover all available pages before exploring further. # Attach a skill to a scenario > Link an existing skill to a scenario. Idempotent — re-attaching the same pair returns `200 OK` with the existing row, and re-activates it if it had been disabled. Applies from the scenario's next meeting. ## OpenAPI ````yaml POST /scenarios/{scenarioId}/skills/{id}/attach openapi: 3.0.0 info: title: WaterrAI API version: 1.0.0 description: >- REST API for the WaterrAI meeting platform — create scenarios, spin up AI-driven meetings, fetch transcripts and analyses. contact: name: Support email: harshit@waterr.ai servers: - url: https://api.waterr.ai/v1 description: Production security: - apiKeyAuth: [] tags: - name: Users - name: Personas - name: Voices - name: Scenarios - name: Goals - name: Meetings - name: Analyses - name: Recordings - name: Transcripts - name: Tools description: >- Account-scoped custom function (tool) definitions the LLM can call mid-meeting. - name: Scenario Tools description: >- Per-scenario attachments linking a scenario to one or more tool definitions. - name: Guardrails description: >- Account-scoped named prompt fragments appended to a scenario's system prompt. - name: Scenario Guardrails description: Per-scenario attachments linking a scenario to one or more guardrails. - name: Meeting Skills description: Account-scoped invokable instruction packs the agent loads mid-meeting. - name: Scenario Meeting Skills description: Per-scenario attachments linking a scenario to one or more skills. - name: Memories description: >- Facts your agents remember, in containers named by user_memory_tag and shared across agents. paths: /scenarios/{scenarioId}/skills/{id}/attach: post: tags: - Scenario Meeting Skills summary: Attach a skill to a scenario description: >- Link an existing skill to a scenario. Idempotent — re-attaching the same pair returns `200 OK` with the existing row, and re-activates it if it had been disabled. Applies from the scenario's next meeting. operationId: AttachSkillToScenario parameters: - name: scenarioId in: path required: true schema: type: string format: uuid description: Scenario UUID. example: 7e3b9c2a-1d4f-4a1b-bdc6-9c8b2d3f4e5a - name: id in: path required: true schema: type: string format: uuid description: Skill UUID. example: 9f0e1d2c-3b4a-5968-8776-655443322110 requestBody: required: false content: application/json: schema: type: object properties: position: type: integer minimum: 0 default: 0 example: position: 0 responses: '200': description: Already attached — the existing attachment row is returned. content: application/json: schema: $ref: '#/components/schemas/ScenarioSkillAttachment' '201': description: Newly attached. content: application/json: schema: $ref: '#/components/schemas/ScenarioSkillAttachment' '401': description: Unauthorized — missing or invalid API key. '404': description: Scenario or skill not found on this account. security: - apiKeyAuth: [] components: schemas: ScenarioSkillAttachment: type: object description: >- Links a skill to a scenario. The trigger reaches the agent only when `active = true`. required: - id - scenario_id - skill_id - active properties: id: type: string format: uuid example: 3a2b1c0d-4e5f-6789-abcd-ef0123456789 scenario_id: type: string format: uuid example: 7e3b9c2a-1d4f-4a1b-bdc6-9c8b2d3f4e5a skill_id: type: string format: uuid example: 9f0e1d2c-3b4a-5968-8776-655443322110 active: type: boolean default: true description: >- Set `false` to keep the attachment but hide the skill from the agent. example: true position: type: integer minimum: 0 default: 0 description: Order the triggers are listed in. Lower first. example: 0 skill: $ref: '#/components/schemas/Skill' description: Embedded skill definition. Returned on list/attach/update responses. created_at: type: string format: date-time example: '2026-09-10T09:05:00.000Z' updated_at: type: string format: date-time example: '2026-09-10T09:05:00.000Z' Skill: type: object description: >- An invokable instruction pack. Only the one-line `trigger` sits in the agent's prompt each turn; the full `instructions` load when the agent invokes the skill mid-meeting and are dropped when the flow completes. required: - id - name - trigger - instructions - active properties: id: type: string format: uuid example: 9f0e1d2c-3b4a-5968-8776-655443322110 membership_id: type: string format: uuid example: a1b2c3d4-e5f6-7890-abcd-ef0123456789 name: type: string maxLength: 64 pattern: ^[a-zA-Z0-9_-]{1,64}$ description: Identifier the agent passes to `invoke_skill`. Unique per account. example: book_demo trigger: type: string maxLength: 500 description: >- One line describing WHEN to invoke this skill. Lives in the base prompt on every turn — keep it short and specific. example: 'book_demo: when the participant asks to see the product live.' instructions: type: string maxLength: 8000 description: >- The instruction pack, delivered to the agent only after it invokes the skill. example: >- Confirm intent first. Then collect their preferred time and timezone, one question per turn, and call schedule_demo once. gated_tool_names: type: array maxItems: 20 default: [] items: type: string pattern: ^[a-zA-Z0-9_-]{1,64}$ description: >- Custom-function names that refuse to execute until this skill is invoked. `[]` means the skill is purely behavioural. example: - schedule_demo active: type: boolean default: true description: Account-level kill-switch for the definition. example: true scenarios: type: array description: >- Scenarios this skill is attached to. Returned only on the single-skill read. items: type: object properties: id: type: string format: uuid name: type: string active: type: boolean position: type: integer created_at: type: string format: date-time example: '2026-09-10T09:00:00.000Z' updated_at: type: string format: date-time example: '2026-09-10T09:00:00.000Z' securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: wai_... description: >- API key from waterr.ai/settings?tab=api-keys. Send as `Authorization: Bearer wai_`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.