--- title: "Skills API | Grafana Cloud documentation" description: "Create, list, update, and delete Grafana Assistant skills with the HTTP API." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Skills API Use skills to store reusable knowledge that Assistant can retrieve during conversations. Skills contain instructions, procedures, or reference material that Assistant draws on when relevant to a user’s question. Skills have two scopes: - **Tenant skills** are visible to all users in the organization. This is the default scope. - **User skills** are visible only to the identity that created them. When a service account creates a user skill, only that service account can see it. You can’t create user skills on behalf of other users. Examples use the base URL and service account token described in [Grafana Assistant HTTP API reference](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis). ## Create a skill Create a new skill. **Endpoint** `POST /skills` **Permissions** Expand table | Skill scope | Required permission | |-------------|----------------------------------------------| | `user` | `grafana-assistant-app.skills.user:create` | | `tenant` | `grafana-assistant-app.skills.tenant:create` | **Request** Send a JSON request body. Expand table | Field | Required | Description | |--------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | Yes | Display name for the skill. Maximum 512 characters. | | `body` | Yes | The skill content: instructions, procedures, or reference material. Maximum 65,535 bytes of UTF-8 text. | | `scope` | No | Skill scope: `user` or `tenant`. Default: `tenant`. | | `includeInKnowledgebase` | No | Whether agents can automatically discover and reference this skill. When `false`, the skill is still available through slash commands and manual references. Default: `true`. | | `allowedTools` | No | Tools that skip user approval when this skill is invoked. | **Allowed tools object** The `allowedTools` field is an array of tools that Assistant can run without asking for user approval when this skill is invoked. Each entry identifies a tool on a specific MCP server integration. Expand table | Field | Required | Description | |-----------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `integrationId` | Yes | The ID of an MCP server integration, returned when you [create an MCP server](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/mcp-servers/#create-an-mcp-server) or [list MCP servers](/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/mcp-servers/#list-mcp-servers). | | `toolName` | Yes | The tool name as defined by the MCP server. You can discover tool names by connecting the server through the Grafana UI or by calling the server’s MCP `tools/list` method directly. Maximum 255 characters. | JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "name": "Incident triage checklist", "body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes", "scope": "tenant", "includeInKnowledgebase": true, "allowedTools": [ { "integrationId": "d6e4f5a7-8901-2345-bdef-167890123456", "toolName": "search_docs" } ] } ``` **Response** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "id": "b4c2d3e5-6789-0123-bcde-f45678901234", "name": "Incident triage checklist", "body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes", "created": "2025-11-15T09:00:00Z", "modified": "2025-11-15T09:00:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "includeInKnowledgebase": true, "scope": "tenant" } } ``` **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X POST "${ASSISTANT_API_URL}/skills" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \ -d '{ "name": "Incident triage checklist", "body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes", "scope": "tenant" }' ``` ## List skills Retrieve skills with optional filtering and pagination. **Endpoint** `GET /skills` **Permissions** Expand table | Skill scope | Required permission | |-------------|--------------------------------------------| | `user` | `grafana-assistant-app.skills.user:read` | | `tenant` | `grafana-assistant-app.skills.tenant:read` | **Request** Expand table | Parameter | Required | Description | |-----------|----------|------------------------------------------------------------------| | `scope` | No | Filter by scope: `all`, `user`, or `tenant`. Default: `all`. | | `limit` | No | Maximum number of skills to return. Range: 1-100. Default: `20`. | | `offset` | No | Pagination offset. Default: `0`. | **Response** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "skills": [ { "id": "b4c2d3e5-6789-0123-bcde-f45678901234", "name": "Incident triage checklist", "body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes", "created": "2025-11-15T09:00:00Z", "modified": "2025-11-15T09:00:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "includeInKnowledgebase": true, "scope": "tenant" } ], "pagination": { "total": 1, "limit": 20, "offset": 0 } } } ``` **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl -X GET "${ASSISTANT_API_URL}/skills?scope=tenant&limit=10" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" ``` ## Get a skill Retrieve a single skill by ID. **Endpoint** `GET /skills/{id}` **Permissions** Expand table | Skill scope | Required permission | |-------------|--------------------------------------------| | `user` | `grafana-assistant-app.skills.user:read` | | `tenant` | `grafana-assistant-app.skills.tenant:read` | **Request** Expand table | Parameter | Required | Description | |-----------|----------|------------------------------------------------| | `id` | Yes | The skill ID returned when you create a skill. | **Response** JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "id": "b4c2d3e5-6789-0123-bcde-f45678901234", "name": "Incident triage checklist", "body": "When triaging an incident:\n1. Check recent deployments\n2. Review error logs for the affected service\n3. Check service dependencies for cascading failures\n4. Review metrics for anomalies in the last 30 minutes", "created": "2025-11-15T09:00:00Z", "modified": "2025-11-15T09:00:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "includeInKnowledgebase": true, "scope": "tenant" } } ``` **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash SKILL_ID="b4c2d3e5-6789-0123-bcde-f45678901234" curl -X GET "${ASSISTANT_API_URL}/skills/${SKILL_ID}" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" ``` ## Update a skill Update an existing skill. Only the fields you include in the request body are changed. **Endpoint** `PUT /skills/{id}` **Permissions** Expand table | Skill scope | Required permission | |-------------|---------------------------------------------| | `user` | `grafana-assistant-app.skills.user:write` | | `tenant` | `grafana-assistant-app.skills.tenant:write` | To change a skill’s scope, the service account needs write permissions for both scopes. Only the skill’s creator can change its scope. **Request** Expand table | Parameter | Required | Description | |-----------|----------|---------------| | `id` | Yes | The skill ID. | Send a JSON request body with the fields to update. Expand table | Field | Required | Description | |--------------------------|----------|------------------------------------------------------------------------------------------| | `name` | No | Updated display name. | | `body` | No | Updated skill content. Maximum 65,535 bytes of UTF-8 text. | | `scope` | No | The desired scope: `user` or `tenant`. Omit to leave unchanged. | | `includeInKnowledgebase` | No | Whether agents can automatically discover and reference this skill during conversations. | | `allowedTools` | No | Updated tool auto-approvals. | **Response** The response contains the full updated skill. JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "status": "success", "data": { "id": "b4c2d3e5-6789-0123-bcde-f45678901234", "name": "Incident triage checklist", "body": "Updated triage steps...", "created": "2025-11-15T09:00:00Z", "modified": "2025-11-20T14:15:00Z", "createdBy": "sa-5594@serviceaccount.grafana", "updatedBy": "sa-5594@serviceaccount.grafana", "includeInKnowledgebase": true, "scope": "tenant" } } ``` **Examples** Update a skill’s content: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash SKILL_ID="b4c2d3e5-6789-0123-bcde-f45678901234" curl -X PUT "${ASSISTANT_API_URL}/skills/${SKILL_ID}" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \ -d '{ "body": "Updated triage steps:\n1. Check recent deployments in the last 2 hours\n2. Review error rate dashboards\n3. Check upstream dependencies" }' ``` ## Delete a skill Permanently delete a skill. **Endpoint** `DELETE /skills/{id}` **Permissions** Expand table | Skill scope | Required permission | |-------------|----------------------------------------------| | `user` | `grafana-assistant-app.skills.user:delete` | | `tenant` | `grafana-assistant-app.skills.tenant:delete` | **Request** Expand table | Parameter | Required | Description | |-----------|----------|---------------| | `id` | Yes | The skill ID. | **Response** A successful deletion returns HTTP 204 with no response body. **Examples** Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash SKILL_ID="b4c2d3e5-6789-0123-bcde-f45678901234" curl -X DELETE "${ASSISTANT_API_URL}/skills/${SKILL_ID}" \ -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" ```