Sync skills from rasa-agent-skills

skills/rasa-building-flows/SKILL.md

@@ -7,7 +7,8 @@ description: >
 license: Apache-2.0
 metadata:
   author: rasa
-  version: "3.x"
+  version: "0.1.0"
+  rasa_version: ">=3.9.0"
   docs-url: https://rasa.com/docs/reference/primitives/flows/
 ---
 
@@ -30,7 +31,9 @@ metadata:
    (see "Branching and conditions").
 10. Extract reusable sub-tasks into child flows via `call` (see "Connecting flows").
 11. Connect follow-up flows via `link` if a separate process should start after.
-12. Validate the project.
+12. Ensure all referenced slots, responses, and actions exist in the domain
+    (see "Ensure domain completeness").
+13. Validate the project (see "Fixing validation errors").
 
 ## Scoping a flow
 
@@ -343,6 +346,27 @@ collect_patient_info:
   if: False
 ```
 
-## Full reference
+## Ensure domain completeness
 
-<!-- TODO: Add references/flows-reference.md with complete syntax documentation -->
+Every element a flow references must be defined in the domain (`domain.yml` or split
+domain files). After writing or editing a flow, walk through each step and verify the
+items below are present. Missing entries cause validation errors or silent runtime
+failures.
+
+- Every slot used in the flow → `slots:`
+  (see `rasa-managing-slots`)
+- Every `collect: slot_name` → `utter_ask_{slot_name}` in `responses:`
+  (see `rasa-writing-responses`)
+- Every `action: utter_*` step → matching entry in `responses:`
+- Every custom action / validation action → `actions:`
+  (see `rasa-writing-custom-actions`)
+- Rejection responses → `responses:`
+
+## Fixing validation errors
+
+When validation fails, preserve the user's **intent** — what the flow is supposed to
+accomplish. The flow steps themselves can change, but the intended behavior must not be
+lost.
+
+Never strip down a flow's intended behavior to make validation pass. If needed, fix the
+domain: slots, responses, and actions to support what the user asked for.

skills/rasa-calling-mcp-tools-from-flows/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: rasa-calling-mcp-tools-from-flows
+description: >
+  Calls MCP tools directly from Rasa flow steps. Use when invoking an MCP tool via a
+  call step, mapping slot values to tool parameters, or extracting tool results into
+  slots. This replaces custom action code for simple API integrations.
+license: Apache-2.0
+metadata:
+  author: rasa
+  version: "0.1.0"
+  rasa_version: ">=3.14.0"
+  docs-url: https://rasa.com/docs/pro/build/mcp-integration
+---
+
+# Calling MCP Tools from Flows
+
+MCP tools can be invoked directly from flow steps using a `call` step with explicit
+input/output mappings. This replaces the need for custom action code when you only need
+to call an external API.
+
+MCP servers must be defined in `endpoints.yml` before calling their tools. See the
+`rasa-configuring-mcp-server` skill for server setup and authentication.
+
+This feature is in **beta** and available starting from **Rasa 3.14.0**.
+
+## When to use MCP vs a custom action
+
+Use an MCP tool call when:
+
+- The tool already exists on an MCP server
+- You just need to pass slot values in and store results back
+- No complex logic around the call (branching, retries, multiple sequential API calls)
+
+Use a custom action instead when:
+
+- You need complex business logic (multiple API calls, conditionals, error handling)
+- You need access to the full tracker (conversation history, events, sender ID)
+- You need to send custom messages via the dispatcher
+- The data transformation can't be expressed in a Jinja2 output mapping
+- The external API isn't exposed via MCP
+
+See `rasa-writing-custom-actions` for custom action guidance.
+
+## Workflow
+
+1. Ensure the MCP server is defined in `endpoints.yml`
+   (see `rasa-configuring-mcp-server` skill).
+2. Call the MCP tool from a flow using a `call` step with `mcp_server` and `mapping`
+   (see "Calling an MCP tool from a flow").
+3. Map tool results to slots, handling both structured and unstructured output
+   (see "Tool result formats").
+4. Validate the project.
+
+## Calling an MCP tool from a flow
+
+Use a `call` step with `mcp_server` and `mapping` to invoke a tool directly.
+
+| Key              | Required | Description |
+|------------------|----------|-------------|
+| `call`           | yes | Tool name as exposed by the MCP server |
+| `mcp_server`     | yes | Must exactly match a `name` in `endpoints.yml`. Fails at runtime if mismatched |
+| `mapping.input`  | yes | Maps slot values to tool parameters. Each entry: `param` (tool parameter name) + `slot` (Rasa slot name) |
+| `mapping.output` | yes | Maps tool results back to slots. Each entry: `slot` (target slot) + `value` (Jinja2 expression to extract the result) |
+
+```yaml
+flows:
+  buy_order:
+    description: helps users place a buy order for a particular stock
+    steps:
+      - collect: stock_name
+      - collect: order_quantity
+      - action: check_feasibility
+        next:
+          - if: slots.order_feasible is True
+            then:
+              - call: place_buy_order
+                mcp_server: trade_server
+                mapping:
+                  input:
+                    - param: ticker_symbol
+                      slot: stock_name
+                    - param: quantity
+                      slot: order_quantity
+                  output:
+                    - slot: order_status
+                      value: result.structuredContent.order_status.success
+          - else:
+              - action: utter_invalid_order
+                next: END
+```
+
+## Tool result formats
+
+MCP tools return results in one of two formats. Handle both in your output mapping.
+
+### Structured content
+
+When the tool defines an output schema, Rasa returns structured data. Access specific
+values using dot notation in the `value` field:
+
+```yaml
+# Tool returns: {"result": {"structuredContent": {"order_status": {"success": true, "order_id": "abc123"}}}}
+output:
+  - slot: order_status
+    value: result.structuredContent.order_status.success
+  - slot: order_id
+    value: result.structuredContent.order_status.order_id
+```
+
+### Unstructured content
+
+When the tool has no output schema, the entire result is a serialized string. Capture
+it in a single slot for downstream processing:
+
+```yaml
+# Tool returns: {"result": {"content": [{"type": "text", "text": "{\"order_status\": ...}"}]}}
+output:
+  - slot: order_data
+    value: result.content
+```
+
+## Common pitfalls
+
+- **MCP server name mismatch** — the `mcp_server` value in a flow `call` step must
+  exactly match a `name` in `endpoints.yml`. A typo means the call fails at runtime
+  with no compile-time warning.
+- **Missing tool on server** — if the tool name in `call` doesn't exist on the
+  referenced MCP server, the call fails at runtime.
+- **Ignoring unstructured content** — when a tool has no output schema, results come
+  back as a serialized string under `result.content`, not as `result.structuredContent`.
+  Always account for both formats.

skills/rasa-configuring-assistant/SKILL.md

@@ -7,7 +7,8 @@ description: >
 license: Apache-2.0
 metadata:
   author: rasa
-  version: "3.x"
+  version: "0.1.0"
+  rasa_version: ">=3.13.0"
   docs-url: https://rasa.com/docs/pro/build/configuring-assistant
 ---
 
@@ -159,6 +160,11 @@ nlg:
 The rephraser (`nlg: type: rephrase`) is covered by the `rasa-rephrasing-responses`
 skill.
 
+### MCP servers
+
+MCP server configuration (`mcp_servers` in `endpoints.yml`) is covered by the
+`rasa-configuring-mcp-server` skill.
+
 ### Silence handling
 
 Controls how long the assistant waits before assuming the user is silent. Only applies
@@ -168,7 +174,3 @@ to voice-stream channels (Twilio, Browser Audio, Genesys, Jambonz, Audiocodes).
 interaction_handling:
   global_silence_timeout: 7    # seconds, default: 7
 ```
-
-## Full reference
-
-<!-- TODO: Add references/config-reference.md with complete syntax documentation -->

skills/rasa-configuring-mcp-server/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: rasa-configuring-mcp-server
+description: >
+  Configures MCP (Model Context Protocol) servers in a Rasa CALM assistant. Use when
+  defining MCP servers in endpoints.yml, setting up authentication (API key, OAuth 2.0,
+  pre-issued token), or connecting to multiple external services.
+license: Apache-2.0
+metadata:
+  author: rasa
+  version: "0.1.0"
+  rasa_version: ">=3.14.0"
+  docs-url: https://rasa.com/docs/reference/integrations/mcp-servers
+---
+
+# Configuring MCP Servers
+
+MCP servers expose external tools — APIs, databases, services — to a Rasa assistant. All
+MCP servers are defined in `endpoints.yml` and shared across direct flow tool calls and
+ReAct sub agents.
+
+This feature is in **beta** and available starting from **Rasa 3.14.0**.
+
+## Workflow
+
+1. Add each MCP server to `endpoints.yml` (see "Server definition").
+2. Add authentication if the server requires it (see "Authentication").
+3. Validate the project.
+
+## Server definition
+
+Register every MCP server in `endpoints.yml`.
+
+| Key    | Required | Description |
+|--------|----------|-------------|
+| `name` | yes      | Unique identifier — referenced from flows and sub agent configs. Duplicates cause a validation error at startup |
+| `url`  | yes      | URL where the MCP server is running |
+| `type` | yes      | `http` or `https` |
+
+```yaml
+# endpoints.yml
+mcp_servers:
+  - name: trade_server
+    url: http://localhost:8080
+    type: http
+  - name: payment_server
+    url: https://api.payment-service.com
+    type: https
+```
+
+## Authentication
+
+Add auth fields directly to the server entry in `endpoints.yml` when the MCP server
+requires credentials. Sensitive values (`api_key`, `token`, `client_secret`) **must**
+use `${ENV_VAR}` syntax — plain text is rejected by validation.
+
+### API key
+
+Sent as `Authorization: Bearer <key>` by default. Add `header_name` and
+`header_format` to override the header.
+
+```yaml
+mcp_servers:
+  - name: secure_api_server
+    url: https://api.example.com
+    type: https
+    api_key: "${API_KEY}"
+    header_name: "X-API-Key"       # optional, default: Authorization
+    header_format: "{key}"          # optional, default: Bearer {key}
+```
+
+### OAuth 2.0 (client credentials)
+
+```yaml
+mcp_servers:
+  - name: oauth_server
+    url: https://api.example.com
+    type: https
+    oauth:
+      client_id: "${CLIENT_ID}"
+      client_secret: "${CLIENT_SECRET}"
+      token_url: "https://auth.example.com/oauth/token"
+      scope: "read:data write:data"    # optional
+      audience: "https://api.example.com"  # optional
+      timeout: 10                      # optional
+```
+
+### Pre-issued token
+
+```yaml
+mcp_servers:
+  - name: token_server
+    url: https://api.example.com
+    type: https
+    token: "${ACCESS_TOKEN}"
+```

skills/rasa-configuring-model-groups/SKILL.md

@@ -7,7 +7,8 @@ description: >
 license: Apache-2.0
 metadata:
   author: rasa
-  version: "3.x"
+  version: "0.1.0"
+  rasa_version: ">=3.11.0"
   docs-url: https://rasa.com/docs/pro/deploy/llm-routing
 ---
 

skills/rasa-managing-slots/SKILL.md

@@ -7,7 +7,8 @@ description: >
 license: Apache-2.0
 metadata:
   author: rasa
-  version: "3.x"
+  version: "0.1.0"
+  rasa_version: ">=3.12.0"
   docs-url: https://rasa.com/docs/reference/primitives/slots/
 ---
 
@@ -183,7 +184,3 @@ different conventions, match those instead.
 - Prefix booleans with `is_` or `has_`: `is_verified`, `has_insurance`
 - Avoid special characters `(`, `)`, `=`, `,` in slot names — they break response button
   payloads
-
-## Full reference
-
-<!-- TODO: Add references/slots-reference.md with complete syntax documentation -->

skills/rasa-rephrasing-responses/SKILL.md

@@ -7,7 +7,8 @@ description: >
 license: Apache-2.0
 metadata:
   author: rasa
-  version: "3.x"
+  version: "0.1.0"
+  rasa_version: ">=3.11.0"
   docs-url: https://rasa.com/docs/reference/primitives/contextual-response-rephraser/
 ---
 
@@ -136,7 +137,3 @@ responses:
           Suggested: {{suggested_response}}
           Rephrased:
 ```
-
-## Full reference
-
-<!-- TODO: Add references/slots-reference.md with complete syntax documentation -->