Documentation Grafana Cloud AI and machine learning Grafana Assistant Guides Create Skills

Create Skills

Skills are documents that guide Grafana Assistant agents with instructions, context, and specialized knowledge. By defining skills, you can encode how your team troubleshoots services, handles specific alerts, or manages shared infrastructure.

Unlike strict rules, skills are flexible guides that agents discover and use when relevant to a user’s request.

What you’ll achieve

• Create skills to standardize troubleshooting workflows.
• Attach dashboards, queries, and other context to agent instructions.
• Enable slash commands to run complex skills on demand.
• Configure skills to trigger MCP actions in external systems.
• Control visibility to share skills with your team or keep them private.

Before you begin

• Grafana Cloud: You must have a Grafana Cloud account.
• Grafana Assistant: Ensure the Assistant is enabled for your stack.

Create a skill

Create skills to capture your team’s expertise and standardize troubleshooting workflows.

Create skills to capture your team’s expertise. For example, create a “Service Troubleshooting” skill that lists critical services and the canonical steps to diagnose issues.

1. Open Grafana Assistant.
2. Click the menu icon (three dots) and select Skills.
3. Click New Skill.
4. Enter a title and description.
   • Use headings to structure instructions.
   • Write in natural language (e.g., “First check error rates, then look at logs”).
   • Include specific metric names, alert names, and error messages for better context.
5. (Optional) Toggle Visible to agents to allow agents to discover this skill via semantic search during conversations.
6. Click Save.

Use templates

Use quick templates to start with a structured outline:

• Health checks: Comprehensive system health, SLO audit, database health.
• Incident triage: Prometheus alert investigation, Loki log analysis, Tempo latency triage.
• Infrastructure & capacity: Resource saturation checks, Kubernetes crash loops.
• Databases: Slow query analysis, connection pool exhaustion.

Select a template when creating a new skill to save time on structure.

Monitor usage

Track how often your skills are used by the team and the Assistant.

The usage sparkline in the skill sidebar shows activity over the last 30 days. Hover over the chart to see details:

• Total runs: Combined executions by users and agents.
• Slash commands: Direct invocations via /command.
• Assistant references: Automatic discovery via semantic search.

Use these insights to identify high-value skills or those that need updates.

Add context

Attach specific resources to your skill to give agents direct access to the right data.

Type @ in the skill editor to open the resource picker.

• Dashboards: Reference dashboards so agents know where to look.
• Queries: Include PromQL or LogQL queries for the agent to run.
• Labels: Specify relevant labels for filtering.

Check the @checkout-service dashboard and look for spikes in error rates.

To remove a context item, click the remove icon next to it in the editor.

Manage visibility

Control who sees and uses your skills to maintain privacy or enable team collaboration.

By default, new skills are visible to everyone in your team.

• Private (Just me): Visible only to you. Valid for experimenting or personal workflows.
• Team (Everybody): Visible to everyone on your team. Use this for shared processes and standard operating procedures.

To change visibility, use the toggle in the skill settings.

You can view who created the skill and who last edited it, along with the last updated timestamp, in the skill sidebar.

Agent search and discovery

The Assistant uses semantic search to automatically find and reference relevant skills during conversations.

When you enable Visible to agents, the Assistant automatically searches and references your skills when answering questions—even if you don’t mention them explicitly.

When skills are searched

The Assistant automatically searches skills when your question requires:

• Domain-specific knowledge about your systems or processes
• System architecture or design information
• Troubleshooting guidance
• Procedural information

Optimize for search

Structure skills to help agents find the right information quickly.

Use descriptive titles: Write clear, specific titles like “Investigate Database Connection Failures” instead of “DB Stuff”.

Include keywords: Mention specific service names, metric names (e.g., CoreDNSErrorsHigh), error codes, and process names.

Use clear structure: Organize content with headings and step-by-step instructions.

Organize by alert: Structure skills with sections per alert name. This helps agents find exact troubleshooting steps for specific alerts.

Example structure:

Markdown Copy

# Infrastructure Troubleshooting Skill

## CoreDNSErrorsHigh

When this alert fires, check:

- DNS query latency in the CoreDNS dashboard
- Pod restart count in the last 15 minutes
- Network policy changes that might block DNS traffic

## DatabaseConnectionPoolExhausted

When this alert fires, check:

- Active connection count vs pool size
- Long-running queries blocking connections
- Application connection leak patterns

Each section is indexed separately, so agents can retrieve only the relevant alert response steps.

Use slash commands

Turn any skill into a slash command for quick, on-demand execution.

Slash commands are useful for recurring tasks like health checks or specific troubleshooting flows.

1. In the skill editor, toggle Enable slash command.
2. Assign a command name (e.g., /check-cart).
   • Must be under 25 characters (1-24 characters).
   • Must contain only letters, numbers, hyphens, or underscores.
   • Must start with a letter or number (no symbols).
   • Command names must be unique within your tenant.
3. Save the skill.

Now, you can type the command in the Assistant chat to trigger the skill immediately.

Discover commands

Type / at the start of a message to see all available slash commands in your tenant.

Combine with additional context

Add extra information when running a command to provide specific context:

Copy

/investigate-loki-errors

Check errors from the last hour in production.

Copy

/deploy-api

Deploy version 2.3.1 to staging.

Copy

/slo-metrics

What are the current SLO metrics for billing?

Naming best practices

• Short and memorable: deploy-api not deploy-api-service-to-production
• Descriptive: investigate-db-errors not db1
• Consistent: Use prefixes like investigate-*, deploy-*, or check-*

Take action with MCP

Configure skills to trigger MCP actions in external systems like GitHub, Linear, or Slack.

Be explicit about when and how agents should use MCP tools in your skill content.

Specify when to make calls:

Markdown Copy

After completing the troubleshooting:

1. If a bug is found, use the GitHub MCP integration to create an issue
2. Include the alert name, root cause, and remediation steps in the issue
3. Assign the issue to the on-call team

Define conditions:

Markdown Copy

If a bug is identified:

- Use the Linear MCP tool to update ticket [TICKET-ID]
- Set the status to "In Progress"
- Add the findings as a comment

Provide context:

Markdown Copy

When the alert severity is critical:

- Use the Slack MCP integration to send a message to #on-call
- Include the alert name, current status, and summary
- Tag the on-call engineer

When an agent proposes an MCP call, you review and approve it before execution. Include all necessary details in your instructions—ticket IDs, channel names, user names—so the agent can construct accurate tool calls.

Best practices

• Be specific: Include metric names, alert names, service names, and error messages to improve searchability.
• Structure for discovery: Use clear headings and organize by alert name when possible.

Next steps

• Configure MCP servers
• Configure rules