What you will be able to do
- Explain why rarely used capability instructions in a system prompt work against an agent
- Identify which instructions in a system prompt should become Agent Skills, which should stay global, and which need an MCP server
- Write a SKILL.md description and scope that let the agent recognise when to load the skill, so task success holds up after the move
Key concept
Contextual loading of skills — A system prompt or custom instruction is applied on every turn. A skill is packaged separately, and the agent loads it only when the task in front of it matches the skill's description. That is why moving a capability you rarely use into a skill takes it out of the context the agent always carries.
1.Why an overloaded system prompt costs you
A system prompt is the standing set of instructions the model receives every time it runs. Over time, teams add to it: a runbook for an incident procedure, the SQL style guide, the steps for deploying a bundle, a PII-masking checklist. Each one makes sense on its own. Together, they mean every request carries every procedure, even when the user only wants a quick lookup.
Databricks' agent design guidance argues against this directly. It recommends keeping prompts clear and minimal, because extra instructions can contradict each other and distract the model. It also says to give the agent only the context it needs, not a large amount of irrelevant context. Separately, the same guidance notes that each additional LLM or tool call increases token usage and response time. That statement is about calls, not about prompt length, so do not read it as a per-instruction cost. The case against an overloaded prompt rests on the points above: the prompt is given to the model every time it runs, so everything in it is always part of what the model receives.
The problem, then, is not that the instructions are wrong. It is that they are always present. What this subdomain asks is how to keep the knowledge available to the agent while removing it from the standing prompt. Agent Skills are the Databricks answer: the Genie Code documentation says that loading skills only in the relevant context maintains an efficient context window. The documentation gives no figures for the saving and does not describe what, if anything, is held up front for skills that are not loaded, so this lesson makes no claim about either.
Checkpoint 1 of 7· Check yourself
According to the Genie Code documentation, how do skills differ from custom instructions in when they take effect?
Custom instructions apply globally, whereas skills are loaded automatically and only in the relevant context, which is why moving a rarely used capability into a skill keeps it out of the standing prompt.
“Unlike custom instructions, which are applied globally, skills are loaded automatically and only in the relevant context.”Source: docs.databricks.com
2.What an Agent Skill is
Agent skills are task-specific instruction files that AI coding assistants can load to carry out Databricks development tasks. They follow the open Agent Skills standard. A skill is a folder containing a SKILL.md file. That file has YAML front-matter, with a name and a description, followed by Markdown instructions. The folder can also hold supporting files such as scripts, templates or extra documentation. The agent finds skills and loads the relevant ones based on the task at hand.
When skills are published to Unity Catalog, each one becomes a governed securable named catalog.schema.skill. The documentation's examples show the right granularity: one skill covers one task, such as analysing a table, following a runbook or applying your team's SQL conventions.
The documentation describes skills on several surfaces, and they share this SKILL.md format: AI coding assistants (skills installed with the Databricks CLI aitools command group), Genie Code in the workspace, and Unity Gateway Skills (published to Unity Catalog and used through the Unity Gateway CLI, in Beta). The sources do not say which of these a given exam question has in mind, so this lesson relies on the shared format and the contextual-loading behaviour, and names the surface whenever a behaviour is specific to one.
---
name: databricks-sql-guide
description: Databricks SQL conventions for writing queries — use for any Databricks SQL authoring or review.
---Checkpoint 2 of 7· Check yourself
Which statement correctly describes how a Databricks Agent Skill is structured?
A skill is a SKILL.md file with front-matter (name, description) and Markdown instructions, and it can bundle supporting files. It is not a UC function or an MCP server.
“Each skill is a Markdown file with front-matter metadata that describes when and how the skill should be used.”Source: docs.databricks.com
3.Sorting the prompt: skill, global instruction, or MCP server
With an overloaded prompt in front of you, sort each block of instructions into one of three groups.
Skill candidates. These are instructions for a specific task or workflow that apply only to certain requests. Large reference material belongs here too, because a skill can carry more context than an instruction can, including scripts, examples and other resources. Databricks contrasts skills, which load only in the relevant context, with custom instructions, which apply globally. A runbook used once a week is a clear skill candidate.
Keep global. The documentation says only that custom instructions are applied globally while skills are loaded automatically and only in the relevant context. It does not list which rules must stay global. The following is this lesson's own inference from that contrast, not documented guidance: a rule the agent must follow on every turn, such as identity, safety guardrails or output format, is a poor skill candidate, because a skill loads only when the task matches its description and the rule would be missing on every turn that does not match. The test to apply is whether the rule is needed on nearly every turn or only for one type of request.
Needs an MCP server, not just a skill. Some capabilities in the prompt require live data or actions. A skill can tell the agent to use a managed MCP server for a task, but the skill is not an MCP server. Installing skills also does not configure MCP servers for you.
| Prompt content | Where it belongs | Reason |
|---|---|---|
| Team SQL conventions used only when writing queries | Skill | Task-specific; loaded only in the relevant context |
| Weekly incident runbook with scripts and examples | Skill (scripts and examples bundled as supporting files) | Skills carry more context than instructions can |
| Rules that apply to every response | Global instructions | Custom instructions are applied globally |
| Reading live workspace data | MCP server (a skill may point to it) | Skills teach how to work; MCP servers do the work |
Checkpoint 3 of 7· Check yourself
A prompt contains (a) a rule that every reply must follow the company's output format and (b) a quarterly audit procedure used in a few requests. Which split fits the documented contrast between custom instructions and skills?
Custom instructions apply globally, so a rule needed on every turn suits them. A procedure needed only for certain requests suits a skill, which loads only in the relevant context. Keeping (a) global is the lesson's inference from that contrast.
“Unlike custom instructions, which are applied globally, skills are loaded automatically and only in the relevant context.”Source: docs.databricks.com
Checkpoint 4 of 7· Exam question
A Databricks support agent's system prompt has grown large because it contains full step-by-step instructions for exporting a quarterly compliance report in a legacy format, a task requested by exactly one team once every few months. All other instructions in the prompt are used in nearly every conversation. Which change best reduces baseline context cost without hurting the agent's ability to complete the quarterly export when asked?
Correct answer: A — Move the compliance-export instructions into an Agent Skill so they load only when that task is triggered
Checkpoint 5 of 7· Check yourself
A team moves the instructions for querying live Unity Catalog metadata out of the prompt and into a skill. The agent can now describe the procedure but cannot fetch any data. Why?
Skills hold know-how, and MCP servers provide the ability to act. A skill can point to a managed MCP server, but that server still has to be connected separately.
“Skills teach the agent how to work; MCP servers let it do the work.”Source: docs.databricks.com
4.Moving a capability without breaking it
Moving instructions into a skill cuts baseline context only if the agent still finds the skill when it needs it. If it doesn't, task success drops. Whether the agent finds it depends mostly on the description. Databricks says the description matters most because the agent compares it against the task when deciding whether to use the skill. It should say specifically what the skill covers and when to use it. This is stated in the Unity Gateway Skills tutorial, and the Genie Code guidance likewise says clear names and descriptions help match the right skill to the right request.
Scope matters too. The Genie Code guidance is to keep each skill focused on a single task or workflow, because a narrow scope makes it easier to tell when the skill applies. Leave out unnecessary context, since extra detail makes a skill harder to apply reliably. Inside the skill, include step-by-step instructions, examples and edge cases. The Genie Code guidance also says to use Markdown for intent and best practices and scripts for repeatable actions. Splitting an overloaded prompt therefore usually produces several narrow skills, not one large skill that holds everything the prompt used to.
Some behaviours depend on the surface:
- Genie Code: a user can invoke a skill manually by @-mentioning it. Edits to an existing skill do not take effect in active chats, so start a new chat after changing a description. - Genie One chat: a user skill is invoked by typing / followed by its name. - Unity Gateway Skills: a downloaded skill is a point-in-time copy that loads every session, and you re-download for updates. A schema loaded live over MCP loads a skill on demand when the task matches its description and stays current.
How to confirm success held: the Genie Code guidance recommends testing new or updated skills on representative tasks to find where the agent struggles, then updating the instructions to close those gaps. In practice, run the same set of representative tasks before and after the move and compare outcomes. The skill sources prescribe no further measurement method. The general agent design guidance does recommend defining evaluation metrics with MLflow Evaluation and running regression tests, which is the natural way to repeat that comparison.
Checkpoint 6 of 7· Exam question
What must a Databricks Agent Skill file (SKILL.md) contain so that an AI assistant can discover it and decide when to load it?
Correct answer: A — Front-matter metadata, such as a name and description, that indicates when and how the skill should be used
Checkpoint 7 of 7· Check yourself
After the move, the agent often fails to apply the new SQL-conventions skill to SQL review requests. What should you fix first?
The agent compares the description against the task when choosing a skill. A vague description explains missed matches, and adding body text does not change what the agent matches on.
“The description matters most: it is what agents match against when deciding whether to use a skill”Source: docs.databricks.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Packaging a capability as a skill also gives the agent the tool access it needs to carry it out.Why is that wrong?
A skill holds instructions only. It can direct the agent to a managed MCP server, but it is not one, and installing skills does not configure MCP servers.
Covered in Sorting the prompt: skill, global instruction, or MCP server
2.The skill body carries the detail, so a short generic description is good enough.Why is that wrong?
The agent decides whether to use a skill by comparing the task against its description. A vague description means the skill is missed and task success drops.
Covered in Moving a capability without breaking it
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Provide only the tools and context your agent requires, rather than an unbounded set of APIs or large irrelevant context.”
↩︎ Why an overloaded system prompt costs you“Each additional LLM or tool call increases token usage and response time.”
↩︎ Why an overloaded system prompt costs you“Use MLflow Evaluation and production monitoring to define evaluation metrics for development and production.”
↩︎ Moving a capability without breaking it“Keep prompts clear and minimal to avoid contradictory instructions, distracting information and reduce hallucinations.”
↩︎ Prediction - 2.https://www.databricks.com/blog/ai-harnessSecondary source
“A system prompt is the standing set of instructions given to the model every time it runs”
↩︎ Why an overloaded system prompt costs you - 3.https://docs.databricks.com/aws/en/genie-code/skillsOfficial docs
“This maintains an efficient context window”
↩︎ Why an overloaded system prompt costs you“Skills follow the open standard of Agent Skills.”
↩︎ What an Agent Skill is“With skills, you can provide greater context (such as scripts, examples, and other resources) for a task than you can with instructions.”
↩︎ Sorting the prompt: skill, global instruction, or MCP server“Unlike custom instructions, which are applied globally, skills are loaded automatically and only in the relevant context.”
↩︎ Sorting the prompt: skill, global instruction, or MCP server“Keep skills focused. Skills work best when they focus on a single task or workflow.”
↩︎ Moving a capability without breaking it“Avoid unnecessary context. Only include information that is required for the task.”
↩︎ Moving a capability without breaking it“You can also manually invoke skills by @ mentioning them.”
↩︎ Moving a capability without breaking it“Test new or updated skills on representative tasks to find where the agent struggles, then update the instructions to close those gaps.”
↩︎ Moving a capability without breaking it“Edits don't take effect in active chats.”
↩︎ Moving a capability without breaking it“Unlike custom instructions, which are applied globally, skills are loaded automatically and only in the relevant context.”
↩︎ Key concept“Unlike custom instructions, which are applied globally, skills are loaded automatically and only in the relevant context.”
↩︎ Checkpoint“Narrow scope makes it easier for Genie Code to recognize when a skill applies.”
↩︎ Prediction - 4.https://docs.databricks.com/aws/en/agent-skillsOfficial docs
“AI coding assistants automatically discover and load relevant skills based on the task at hand.”
↩︎ What an Agent Skill is“Install Databricks AI tools using the Databricks CLI aitools command group.”
↩︎ What an Agent Skill is“Skills teach the agent how to work; MCP servers let it do the work.”
↩︎ Sorting the prompt: skill, global instruction, or MCP server“the skill is not itself an MCP server, and installing AI tools does not configure MCP servers for you”
↩︎ Exam trap 1“Each skill is a Markdown file with front-matter metadata that describes when and how the skill should be used.”
↩︎ Checkpoint - 5.https://docs.databricks.com/aws/en/agents/uc-skillsOfficial docs
“Skills teach an agent how to do one task well, such as analyzing a table, following a runbook, or applying your team's SQL conventions.”
↩︎ What an Agent Skill is - 6.
“A skill is just a folder: a SKILL.md file with instructions, plus any supporting files the agent should read.”
↩︎ What an Agent Skill is“The description matters most: it is what agents match against when deciding whether to use a skill”
↩︎ Exam trap 2“The description matters most: it is what agents match against when deciding whether to use a skill”
↩︎ Checkpoint - 7.
“A downloaded skill is a point-in-time copy.”
↩︎ Moving a capability without breaking it