Skip to main content
Custom skills are reusable prompts for repeatable work. They capture the detailed instructions you would otherwise type each time you ask an agent to complete a task: what to do, how to do it, which checks to make, and what the result should include. If you find yourself copying the same lengthy prompt into conversations, turn it into a skill. For example, you can create skills for investigating a KPI change, analyzing a conversion funnel, checking data quality, or preparing a weekly business review.

​
Decide when to use a skill

Use a skill for a repeatable procedure that applies to a particular task. Keep behavior that should apply to every conversation in the agent’s instructions. For example, “Use concise language and explain unfamiliar terms” belongs in the agent’s instructions because it applies to every response. A multi-step process for investigating a KPI drop belongs in a skill because the agent only needs it for that analysis. If part of your agent’s instructions has grown into a self-contained workflow that only applies to certain requests, move that workflow into a skill. Skills can use the business context available from the semantic layer and knowledge documents, but they should not copy that context into every workflow. For the complete guide to choosing where agent guidance belongs, see Effective analytics with agents.
This page covers custom skills for Lightdash AI agents. To give coding agents guidance for editing Lightdash projects, see Agent skills.

​
Create or attach a skill

Custom skills live in a shared organization library. Attach a skill to each agent that should be able to use it. Developers and admins can create, edit, and attach skills. Anyone who can use an agent can use the skills attached to it.
1

Open the agent's settings

Go to Ask AI, choose the agent, and open its Setup page. Create the agent first if it has not been saved yet.
2

Add a skill

In Skills, click Add skill. Choose an existing skill from the organization library, or select Create new skill.
3

Describe the workflow

Enter a name, description, and instructions. The name becomes the slash command, so use a short name such as investigate-kpi-change. The description should explain both what the skill does and when the agent should use it.
4

Save the skill

Click Create skill. Lightdash adds it to the organization library and attaches it to the current agent.
To attach the skill to another agent, open that agent’s Skills section, click Library, and select it. Editing a shared skill saves a new version for every agent that uses it. The skill’s name cannot be changed after creation. Remove from this agent only detaches the skill from that agent. It does not remove the skill from the organization library or from other agents.

​
Use a skill

An agent can use an attached skill in two ways:
  • Automatically — ask your question normally. When the request matches a skill’s description, the agent can load the instructions and follow them.
  • On demand — type / in the message composer, search by name or description, and select a skill. Add the task details after the command, for example /investigate-kpi-change weekly active users in EMEA. You can invoke one skill per message.
Text after the slash command is passed to the skill as its arguments. In the skill instructions, use $ARGUMENTS where those details should appear.

​
Write effective skills

Start with a prompt you already repeat or a workflow an experienced analyst already follows. Spell out the sequence, the checks they make, and the mistakes they know to avoid. For example, instead of writing:
give the agent a concrete process:
Include details specific to the workflow, such as which segments to test, how to handle incomplete periods, and what a complete analysis should include. Give sensible defaults so the agent knows how to proceed and when to stop. Keep stable definitions and field-selection guidance in the semantic layer instead of copying them into a skill. Use a description for context that helps people and agents, and an ai_hint for agent-only disambiguation and query guidance. Keep each skill focused on one coherent workflow. If several analyses follow the same process, prefer one reusable skill over separate versions for every metric or team.

​
Example SKILL.md

Lightdash stores each skill as a SKILL.md file. The editor creates this file for you, but seeing the structure can help you write clearer instructions:
The name and description are required. Names use lowercase letters, numbers, and single hyphens. A clear description is especially important because the agent uses it to decide when to load the skill automatically.
A skill changes how an agent works; it does not grant new permissions. The agent can only use its configured tools and data access. Lightdash-hosted skills cannot run shell commands or read files from a filesystem.

​
Use skills through MCP

The Lightdash MCP server exposes custom skills to compatible AI clients. When an agent is active in the MCP session, the client can discover the skills attached to that agent. Without an active agent, it can discover the organization skills the caller has permission to view.

​
Manage skills as code

Use agents as code to review skills in Git and move them between environments. A skill folder contains its SKILL.md and can include supporting Markdown files under resources/.