From d423c9381a6d8de7c801c5d0f84c94e328ab071b Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Wed, 19 Aug 2026 15:34:32 +0200
Subject: [PATCH 1/4] feat(appkit): agent skills v1 (SKILL.md progressive
 disclosure for agents)

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 .../client/src/routes/agent.route.tsx         | 101 ++++-
 .../server/agents/helper/agent.ts             |   4 +
 .../server/agents/skills/haiku/SKILL.md       |  15 +
 .../server/agents/skills/haiku/reference.md   |  15 +
 .../api/appkit/Interface.AgentDefinition.md   |  13 +
 .../appkit/Interface.AgentsPluginConfig.md    |  42 ++
 .../api/appkit/Interface.RegisteredAgent.md   |  12 +
 .../api/appkit/TypeAlias.ResolvedToolEntry.md |  44 +++
 docs/docs/plugins/agents.md                   |  67 +++-
 .../hooks/__tests__/use-agent-chat.test.ts    |  45 +++
 .../src/react/hooks/use-agent-chat.ts         |  26 +-
 packages/appkit/src/core/agent/frontmatter.ts |  18 +
 packages/appkit/src/core/agent/load-agents.ts |  60 ++-
 .../appkit/src/core/agent/skills/index.ts     |   6 +
 .../src/core/agent/skills/load-skills.ts      |  94 +++++
 .../src/core/agent/skills/parse-skill.ts      | 130 ++++++
 .../src/core/agent/skills/read-resource.ts    |  52 +++
 .../appkit/src/core/agent/skills/render.ts    |  42 ++
 .../src/core/agent/skills/resolve-catalog.ts  | 138 +++++++
 .../core/agent/skills/tests/skills.test.ts    | 330 ++++++++++++++++
 .../appkit/src/core/agent/skills/types.ts     |  49 +++
 .../src/core/agent/tests/load-agents.test.ts  |   9 +
 packages/appkit/src/core/agent/types.ts       |  48 +++
 packages/appkit/src/plugins/agents/agents.ts  | 370 +++++++++++++++++-
 .../appkit/src/plugins/agents/manifest.json   |  18 +
 packages/appkit/src/plugins/agents/schemas.ts |   6 +
 .../agents/tests/dispatch-tool-call.test.ts   | 157 +++++++-
 .../plugins/agents/tests/skill-client.test.ts | 148 +++++++
 .../plugins/agents/tests/skill-volume.test.ts | 154 ++++++++
 template/appkit.plugins.json                  |  19 +
 .../client/src/pages/agents/AgentChat.tsx     |  28 +-
 template/server/agents/planner/agent.md       |   6 +-
 .../agents/skills/tracer-bullets/SKILL.md     |  29 ++
 .../agents/skills/tracer-bullets/reference.md |  28 ++
 34 files changed, 2299 insertions(+), 24 deletions(-)
 create mode 100644 apps/dev-playground/server/agents/skills/haiku/SKILL.md
 create mode 100644 apps/dev-playground/server/agents/skills/haiku/reference.md
 create mode 100644 packages/appkit/src/core/agent/frontmatter.ts
 create mode 100644 packages/appkit/src/core/agent/skills/index.ts
 create mode 100644 packages/appkit/src/core/agent/skills/load-skills.ts
 create mode 100644 packages/appkit/src/core/agent/skills/parse-skill.ts
 create mode 100644 packages/appkit/src/core/agent/skills/read-resource.ts
 create mode 100644 packages/appkit/src/core/agent/skills/render.ts
 create mode 100644 packages/appkit/src/core/agent/skills/resolve-catalog.ts
 create mode 100644 packages/appkit/src/core/agent/skills/tests/skills.test.ts
 create mode 100644 packages/appkit/src/core/agent/skills/types.ts
 create mode 100644 packages/appkit/src/plugins/agents/tests/skill-client.test.ts
 create mode 100644 packages/appkit/src/plugins/agents/tests/skill-volume.test.ts
 create mode 100644 template/server/agents/skills/tracer-bullets/SKILL.md
 create mode 100644 template/server/agents/skills/tracer-bullets/reference.md

diff --git a/apps/dev-playground/client/src/routes/agent.route.tsx b/apps/dev-playground/client/src/routes/agent.route.tsx
index 2ae2a2557..01493539b 100644
--- a/apps/dev-playground/client/src/routes/agent.route.tsx
+++ b/apps/dev-playground/client/src/routes/agent.route.tsx
@@ -151,7 +151,7 @@ function useAutocomplete(enabled: boolean) {
 
 function AgentRoute() {
   const [messages, setMessages] = useState<ChatMessage[]>([]);
-  const [events, setEvents] = useState<AgentEvent[]>([]);
+  const [events, setEvents] = useState<SSEEvent[]>([]);
   const [input, setInput] = useState("");
   const [isLoading, setIsLoading] = useState(false);
   const [threadId, setThreadId] = useState<string | null>(null);
@@ -159,6 +159,8 @@ function AgentRoute() {
   const [pendingApprovals, setPendingApprovals] = useState<PendingApproval[]>(
     [],
   );
+  // Highlighted row in the `/skill` menu.
+  const [skillIndex, setSkillIndex] = useState(0);
 
   const decideApproval = useCallback(
     async (approvalId: string, decision: "approve" | "deny") => {
@@ -191,8 +193,11 @@ function AgentRoute() {
   const agentConfig = getPluginClientConfig<{
     agents?: string[];
     defaultAgent?: string;
+    skills?: Record<string, { name: string; description: string }[]>;
   }>("agents");
   const hasAutocomplete = (agentConfig.agents ?? []).includes("autocomplete");
+  // Skills visible to the selected agent, from the boot config.
+  const activeSkills = agentConfig.skills?.[agent] ?? [];
 
   const {
     suggestion,
@@ -201,6 +206,29 @@ function AgentRoute() {
     clear: clearSuggestion,
   } = useAutocomplete(hasAutocomplete);
 
+  // Slash-command menu: when the input is a leading `/token` (no space yet),
+  // surface matching skills for the active agent.
+  const slashQuery = input.match(/^\/([^\s]*)$/)?.[1] ?? null;
+  const skillMatches =
+    slashQuery !== null && activeSkills.length > 0
+      ? activeSkills.filter((s) =>
+          s.name.toLowerCase().includes(slashQuery.toLowerCase()),
+        )
+      : [];
+  const skillMenuOpen = skillMatches.length > 0;
+
+  const pickSkill = (name: string) => {
+    setInput(`/${name} `);
+    clearSuggestion();
+    inputRef.current?.focus();
+  };
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: reset highlight as the query changes
+  useEffect(() => {
+    setSkillIndex(0);
+  }, [input, agent]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: scroll on new messages
   useEffect(() => {
     messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
   }, [messages]);
@@ -218,13 +246,25 @@ function AgentRoute() {
     setEvents([]);
     setIsLoading(true);
 
+    // `/skill-name …` forces a skill for this turn (the agents plugin injects
+    // its instructions); the model can still auto-load others via load_skill.
+    let messageBody = userMessage;
+    let skill: string | undefined;
+    const skillMatch = messageBody.match(/^\/([A-Za-z0-9][\w.:-]*)\s*/);
+    if (skillMatch) {
+      skill = skillMatch[1];
+      messageBody = messageBody.slice(skillMatch[0].length);
+      if (messageBody.trim() === "") messageBody = `Use the ${skill} skill.`;
+    }
+
     try {
       const response = await fetch("/api/agents/chat", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          message: userMessage,
+          message: messageBody,
           agent,
+          ...(skill && { skill }),
           ...(threadId && { threadId }),
         }),
       });
@@ -506,6 +546,34 @@ function AgentRoute() {
                     value={input}
                     onChange={(e) => handleInputChange(e.target.value)}
                     onKeyDown={(e) => {
+                      if (skillMenuOpen) {
+                        if (e.key === "ArrowDown") {
+                          e.preventDefault();
+                          setSkillIndex((i) => (i + 1) % skillMatches.length);
+                          return;
+                        }
+                        if (e.key === "ArrowUp") {
+                          e.preventDefault();
+                          setSkillIndex(
+                            (i) =>
+                              (i - 1 + skillMatches.length) %
+                              skillMatches.length,
+                          );
+                          return;
+                        }
+                        if (e.key === "Enter" || e.key === "Tab") {
+                          e.preventDefault();
+                          pickSkill(
+                            (skillMatches[skillIndex] ?? skillMatches[0]).name,
+                          );
+                          return;
+                        }
+                        if (e.key === "Escape") {
+                          e.preventDefault();
+                          setInput("");
+                          return;
+                        }
+                      }
                       if (e.key === "Tab" && suggestion) {
                         e.preventDefault();
                         acceptSuggestion();
@@ -518,11 +586,38 @@ function AgentRoute() {
                         sendMessage();
                       }
                     }}
-                    placeholder="Ask a question..."
+                    placeholder={
+                      activeSkills.length > 0
+                        ? "Ask a question…  (type / for skills)"
+                        : "Ask a question..."
+                    }
                     disabled={isLoading}
                     rows={1}
                     className="w-full rounded-md border border-input bg-transparent px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50 resize-none"
                   />
+                  {skillMenuOpen && (
+                    <ul className="absolute bottom-full left-0 mb-1 w-full max-h-48 overflow-y-auto rounded-md border bg-card shadow-md z-10 py-1">
+                      {skillMatches.map((s, i) => (
+                        <li key={s.name}>
+                          <button
+                            type="button"
+                            onMouseDown={(e) => {
+                              e.preventDefault();
+                              pickSkill(s.name);
+                            }}
+                            className={`block w-full text-left px-3 py-1.5 text-sm ${
+                              i === skillIndex ? "bg-muted" : ""
+                            }`}
+                          >
+                            <span className="font-mono">/{s.name}</span>
+                            <span className="ml-2 text-xs text-muted-foreground">
+                              {s.description}
+                            </span>
+                          </button>
+                        </li>
+                      ))}
+                    </ul>
+                  )}
                 </div>
                 <Button
                   type="submit"
diff --git a/apps/dev-playground/server/agents/helper/agent.ts b/apps/dev-playground/server/agents/helper/agent.ts
index 2242e7559..9ff11e7a0 100644
--- a/apps/dev-playground/server/agents/helper/agent.ts
+++ b/apps/dev-playground/server/agents/helper/agent.ts
@@ -8,6 +8,10 @@ export default createAgent({
   instructions:
     "You are a demo helper. Use analytics tools to answer data questions, " +
     "or get_weather for light small-talk.",
+  // Opts into the global `haiku` skill (server/agents/skills/haiku/SKILL.md).
+  // The model auto-loads it when a request matches, or the user can force it
+  // with `/haiku …` in the chat box.
+  skills: ["haiku"],
   tools(plugins) {
     return {
       ...plugins.analytics.toolkit(),
diff --git a/apps/dev-playground/server/agents/skills/haiku/SKILL.md b/apps/dev-playground/server/agents/skills/haiku/SKILL.md
new file mode 100644
index 000000000..51c3a8fc4
--- /dev/null
+++ b/apps/dev-playground/server/agents/skills/haiku/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: haiku
+description: Format the final answer as a traditional 5-7-5 haiku. Use when the user asks for a haiku or a poetic reply.
+---
+
+When this skill is active, deliver your final answer as a single haiku:
+
+- Three lines, following a 5 / 7 / 5 syllable pattern.
+- Capture the essence of the answer — if the user asked a data question,
+  answer it truthfully first (call any tools you need), then distill the
+  result into the poem. Don't invent facts to fit the meter.
+- No title, no preamble, no explanation after the poem. Just the three lines.
+
+See `reference.md` for a worked example, including how to fold a real tool
+result into the poem.
diff --git a/apps/dev-playground/server/agents/skills/haiku/reference.md b/apps/dev-playground/server/agents/skills/haiku/reference.md
new file mode 100644
index 000000000..c90e02869
--- /dev/null
+++ b/apps/dev-playground/server/agents/skills/haiku/reference.md
@@ -0,0 +1,15 @@
+# Haiku skill: worked example
+
+**User:** what's the weather in Paris?
+
+**Wrong** (explains, then poem):
+> The weather in Paris is sunny and 22°C. Here's your haiku:
+> Sunlight over Seine / ...
+
+**Right** (call the tool, then answer as the poem alone):
+> Sun warms the Seine's banks
+> Twenty-two degrees of calm
+> Paris wears the light
+
+Fold the real tool result (sunny, 22°C) into the imagery. Never bend the
+facts to fit the syllables — bend the words instead.
diff --git a/docs/docs/api/appkit/Interface.AgentDefinition.md b/docs/docs/api/appkit/Interface.AgentDefinition.md
index 2c9b5bb27..3010adf52 100644
--- a/docs/docs/api/appkit/Interface.AgentDefinition.md
+++ b/docs/docs/api/appkit/Interface.AgentDefinition.md
@@ -131,6 +131,19 @@ entirely.
 
 ***
 
+### skills?
+
+```ts
+optional skills: string[];
+```
+
+Names of global skills (shared `skills/` pool or catalog volume) to make
+visible to this agent. Per-agent skills under `<id>/skills/` are always
+visible and need not be listed. Ignored when the plugin's
+`autoInheritSkills` makes every global skill visible.
+
+***
+
 ### tools?
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.AgentsPluginConfig.md b/docs/docs/api/appkit/Interface.AgentsPluginConfig.md
index 59d7d1220..a2f2c963f 100644
--- a/docs/docs/api/appkit/Interface.AgentsPluginConfig.md
+++ b/docs/docs/api/appkit/Interface.AgentsPluginConfig.md
@@ -69,6 +69,22 @@ Milliseconds to wait before auto-denying. Default: 60_000.
 
 ***
 
+### autoInheritSkills?
+
+```ts
+optional autoInheritSkills: 
+  | boolean
+  | AutoInheritToolsConfig;
+```
+
+Whether every global skill (shared `skills/` pool or catalog volume) is
+visible to an agent without listing it in `skills:` frontmatter. Off by
+default so each agent's always-on skill catalog stays lean; accepts a
+boolean shorthand or a per-origin `{ file, code }` config, mirroring
+[autoInheritTools](#autoinherittools).
+
+***
+
 ### autoInheritTools?
 
 ```ts
@@ -218,6 +234,32 @@ optional name: string;
 
 ***
 
+### skillCredentialMode?
+
+```ts
+optional skillCredentialMode: "sp" | "obo";
+```
+
+Identity used to read catalog (volume) skills. v1 supports `"sp"` (default —
+a shared, service-principal-readable curated pool). `"obo"` is the reserved
+switch point for per-user skill volumes and is not wired yet (falls back to
+`"sp"` with a warning).
+
+***
+
+### skillsVolume?
+
+```ts
+optional skillsVolume: string;
+```
+
+Unity Catalog Volume path for catalog-sourced skills (e.g.
+`/Volumes/<catalog>/<schema>/<volume>`). Falls back to the
+`DATABRICKS_VOLUME_AGENT_SKILLS` env var. Skills at `<volume>/<name>/SKILL.md`
+are discovered at boot and on `reload()` and read as the service principal.
+
+***
+
 ### telemetry?
 
 ```ts
diff --git a/docs/docs/api/appkit/Interface.RegisteredAgent.md b/docs/docs/api/appkit/Interface.RegisteredAgent.md
index 4cbe04682..78a70f9a1 100644
--- a/docs/docs/api/appkit/Interface.RegisteredAgent.md
+++ b/docs/docs/api/appkit/Interface.RegisteredAgent.md
@@ -70,6 +70,18 @@ name: string;
 
 ***
 
+### skills?
+
+```ts
+optional skills: ResolvedSkillCatalog;
+```
+
+Resolved per-agent skill catalog (visibility + collision rules applied).
+Present when any skill is visible to this agent; drives the always-on
+prompt catalog and `load_skill` dispatch.
+
+***
+
 ### toolIndex
 
 ```ts
diff --git a/docs/docs/api/appkit/TypeAlias.ResolvedToolEntry.md b/docs/docs/api/appkit/TypeAlias.ResolvedToolEntry.md
index d03c0afda..08571cff5 100644
--- a/docs/docs/api/appkit/TypeAlias.ResolvedToolEntry.md
+++ b/docs/docs/api/appkit/TypeAlias.ResolvedToolEntry.md
@@ -27,6 +27,12 @@ type ResolvedToolEntry =
   def: AgentToolDefinition;
   source: "hosted-supervisor";
   spec: SupervisorTool;
+}
+  | {
+  builtin: "load_skill" | "read_skill_file";
+  catalog: ResolvedSkillCatalog;
+  def: AgentToolDefinition;
+  source: "skill";
 };
 ```
 
@@ -179,3 +185,41 @@ is intentionally NOT included in the `tools` array passed to
 ```ts
 spec: SupervisorTool;
 ```
+
+```ts
+{
+  builtin: "load_skill" | "read_skill_file";
+  catalog: ResolvedSkillCatalog;
+  def: AgentToolDefinition;
+  source: "skill";
+}
+```
+
+### builtin
+
+```ts
+builtin: "load_skill" | "read_skill_file";
+```
+
+### catalog
+
+```ts
+catalog: ResolvedSkillCatalog;
+```
+
+### def
+
+```ts
+def: AgentToolDefinition;
+```
+
+### source
+
+```ts
+source: "skill";
+```
+
+Built-in skill tools (`load_skill`, `read_skill_file`) injected into
+any agent that has a visible skill catalog. Executed in-process by the
+agents plugin against the agent's resolved catalog; read-only, so they
+bypass the approval gate.
diff --git a/docs/docs/plugins/agents.md b/docs/docs/plugins/agents.md
index 11bb32505..19b0f6da2 100644
--- a/docs/docs/plugins/agents.md
+++ b/docs/docs/plugins/agents.md
@@ -37,7 +37,7 @@ That alone gives you a live HTTP server with `POST /invocations` (and its alias
 
 ## Level 1: drop a markdown agent package
 
-Each agent lives in its own folder under `server/agents/` with entry file `agent.md`. A folder is an agent only if it holds an entry file (`agent.md` or `agent.ts`); a folder without one is skipped, so per-agent asset folders like `skills/` sit beside the entry.
+Each agent lives in its own folder under `server/agents/` with entry file `agent.md`. A folder is an agent only if it holds an entry file (`agent.md` or `agent.ts`); a folder without one is skipped, so per-agent asset folders sit beside the entry — notably a `skills/` folder holding [Skills](#skills) (on-demand instruction packs the agent loads by name). A shared `server/agents/skills/` folder holds skills available to any agent.
 
 ```
 my-app/
@@ -206,6 +206,67 @@ await createApp({
 
 Put `supervisor`, `researcher`, and `writer` in their own `server/agents/<id>/agent.ts` folders (default export each) — a markdown parent can also delegate to a code child in a sibling folder via `agents: [helper]` frontmatter. Each key in `agents: {...}` on an `AgentDefinition` becomes an `agent-<key>` tool on the parent. When invoked, the agents plugin runs the child's adapter with a fresh message list (no shared thread state) and returns the aggregated text. Cycles in a code agent's inline `agents: {}` graph are rejected at load (`createAgent`); markdown `agents:` delegation rejects self-references at load and bounds deeper cycles at runtime via `limits.maxSubAgentDepth`.
 
+## Skills
+
+Skills are on-demand instruction packs — the same `SKILL.md` format Claude Code and Cursor use. Only each skill's `name` + `description` sit in the system prompt (always-on, cheap); the full body loads on demand when the agent (or the user) invokes it. This works on any Databricks-served model — AppKit implements the disclosure itself, so it doesn't depend on a provider-native skills feature.
+
+A skill is a directory with a `SKILL.md` plus any bundled reference files:
+
+```
+config/agents/
+  skills/                    # shared pool — any agent can opt in
+    pdf-forms/
+      SKILL.md
+      reference.md
+  planner/
+    agent.md
+    skills/                  # private to the `planner` agent
+      house-style/
+        SKILL.md
+```
+
+```md
+---
+name: pdf-forms
+description: Fill and validate PDF form fields from a data record.
+---
+
+To fill a PDF form:
+
+1. Read `reference.md` for the field-name conventions.
+2. ...
+```
+
+`name` and `description` are required; `license`, `allowed-tools`, and `metadata` are accepted for compatibility with skills authored elsewhere. Unknown keys warn and are ignored.
+
+### Visibility
+
+- **Per-agent skills** (`config/agents/<id>/skills/`) are always visible to that agent.
+- **Global skills** (`config/agents/skills/`, and catalog-volume skills) are **opt-in**: list them in the agent's frontmatter, `skills: [pdf-forms]`. Set `autoInheritSkills: true` (or `{ file, code }`) on the plugin to make every global skill visible without listing — off by default so each agent's always-on catalog stays lean.
+
+### How the agent uses a skill
+
+Two read-only built-in tools are injected into any agent that has a visible catalog:
+
+- `load_skill(skill)` — returns the skill's full instructions plus a manifest of its bundled files.
+- `read_skill_file(skill, path)` — returns the contents of one of those bundled files.
+
+The model calls `load_skill` on its own when a task matches a skill's description. A **user** can force a specific skill for a turn with the `/skill-name` prefix in chat (or the `send(message, { skill })` option on `useAgentChat`); the skill's instructions are injected into that turn deterministically, and `load_skill` remains available for auto-selection. The client reads the per-agent catalog from the plugin's `clientConfig()` payload to power a picker.
+
+### Catalog skills (Unity Catalog Volume)
+
+Point `skillsVolume` (or the `DATABRICKS_VOLUME_AGENT_SKILLS` env var) at a UC Volume laid out the same way — `<volume>/<name>/SKILL.md`. Catalog skills are discovered at boot and on `reload()`, merged into the shared global pool, and read as the **service principal** (`skillCredentialMode` defaults to `"sp"`). They're intended as a shared, curated pool; per-user (OBO) skill volumes are not wired yet. Declaring the optional `volume` resource in the manifest lets the scaffolder grant the SP read access.
+
+### Name collisions
+
+Skill names are addressed bare. If two sources provide the same name, each becomes a qualified `<scope>:name` (`agent:`, `bundle:`, `volume:`) and the bare name is rejected as ambiguous with the alternatives listed. Two skills with the same name from the *same* source is a boot-time error.
+
+### v1 caveats
+
+- **Scripts are not executed.** A skill may reference `scripts/foo.py`; v1 loads prose and reference docs only.
+- **`allowed-tools` is advisory.** It's surfaced as a hint in the loaded skill, not enforced — loading a skill does not restrict the agent's callable tools. It is not a sandbox.
+- **Skill bodies are not per-user access-controlled** (they read as the SP). Keep user-sensitive content out of skill bodies.
+
 ## Level 5: standalone (no `createApp`)
 
 ```ts
@@ -414,6 +475,9 @@ agents({
   defaultModel?: AgentAdapter | Promise<AgentAdapter> | string,
   tools?: Record<string, AgentTool>,
   autoInheritTools?: boolean | { file?: boolean, code?: boolean },
+  autoInheritSkills?: boolean | { file?: boolean, code?: boolean }, // default off
+  skillsVolume?: string,        // UC Volume for catalog skills; falls back to DATABRICKS_VOLUME_AGENT_SKILLS
+  skillCredentialMode?: "sp" | "obo", // default "sp" (see Skills)
   threadStore?: ThreadStore,    // default in-memory
   baseSystemPrompt?: false | string | (ctx: PromptContext) => string,
   mcp?: {
@@ -603,6 +667,7 @@ appkit.agents.getThreads(userId);   // list user's threads
 | `endpoint` | string | Model serving endpoint name. Shortcut for `model`. |
 | `model` | string | Same as `endpoint`; either works. |
 | `tools` | array | Unified tool list. Entries are `plugin:<name>` / `plugin:<name>: [t1, t2]` / `plugin:<name>: { only, except, rename, prefix }` for plugin tools, or a bare `<key>` resolved against `agents({ tools: {...} })` for ambient tools. See "Level 2: scope tools in frontmatter" above for examples. |
+| `skills` | array | Names of global skills (shared `skills/` pool or catalog volume) to make visible to this agent. Per-agent skills under `<id>/skills/` are always visible. See [Skills](#skills). |
 | `default` | boolean | First agent id (sorted order) with `default: true` becomes the default agent. |
 | `agents` | array | Sub-agent ids (sibling folders) to delegate to; each becomes an `agent-<id>` tool. Resolves against other markdown and code agents. |
 | `maxSteps` | number | Adapter max-step hint. |
diff --git a/packages/appkit-ui/src/react/hooks/__tests__/use-agent-chat.test.ts b/packages/appkit-ui/src/react/hooks/__tests__/use-agent-chat.test.ts
index c066d35f8..4e6646913 100644
--- a/packages/appkit-ui/src/react/hooks/__tests__/use-agent-chat.test.ts
+++ b/packages/appkit-ui/src/react/hooks/__tests__/use-agent-chat.test.ts
@@ -77,6 +77,51 @@ describe("useAgentChat", () => {
     expect(capturedCallbacks.maxRetries).toBe(0);
   });
 
+  test("send(message, { skill }) includes the skill in the payload", async () => {
+    const { result } = renderHook(() => useAgentChat({ agent: "helper" }));
+
+    act(() => {
+      void result.current.send("summarize", { skill: "pdf" });
+    });
+
+    await waitFor(() => expect(mockConnectSSE).toHaveBeenCalled());
+    expect(capturedCallbacks.payload).toEqual({
+      message: "summarize",
+      agent: "helper",
+      skill: "pdf",
+    });
+  });
+
+  test("parses a leading /skill-name token off the message", async () => {
+    const { result } = renderHook(() => useAgentChat({ agent: "helper" }));
+
+    act(() => {
+      void result.current.send("/pdf extract the tables");
+    });
+
+    await waitFor(() => expect(mockConnectSSE).toHaveBeenCalled());
+    expect(capturedCallbacks.payload).toEqual({
+      message: "extract the tables",
+      agent: "helper",
+      skill: "pdf",
+    });
+  });
+
+  test("/skill-name with no text falls back to a non-empty message", async () => {
+    const { result } = renderHook(() => useAgentChat({ agent: "helper" }));
+
+    act(() => {
+      void result.current.send("/pdf");
+    });
+
+    await waitFor(() => expect(mockConnectSSE).toHaveBeenCalled());
+    expect(capturedCallbacks.payload).toEqual({
+      message: "Use the pdf skill.",
+      agent: "helper",
+      skill: "pdf",
+    });
+  });
+
   test("custom endpoint is forwarded to connectSSE", async () => {
     const { result } = renderHook(() =>
       useAgentChat({ agent: "helper", endpoint: "/v2/chat" }),
diff --git a/packages/appkit-ui/src/react/hooks/use-agent-chat.ts b/packages/appkit-ui/src/react/hooks/use-agent-chat.ts
index c256adf07..7107cb362 100644
--- a/packages/appkit-ui/src/react/hooks/use-agent-chat.ts
+++ b/packages/appkit-ui/src/react/hooks/use-agent-chat.ts
@@ -85,8 +85,13 @@ export interface UseAgentChatResult {
   /**
    * Send a user turn and stream the response. Aborts any in-flight
    * stream. Resolves when the stream completes (success or error).
+   *
+   * Pass `opts.skill` to force-load a skill for this turn, or prefix the
+   * message with `/skill-name` as sugar (the leading token is parsed off and
+   * sent as the skill; the rest becomes the message). An explicit
+   * `opts.skill` wins over a `/`-prefix.
    */
-  send: (message: string) => Promise<void>;
+  send: (message: string, opts?: { skill?: string }) => Promise<void>;
   /**
    * Discard accumulated content, events, and threadId. Aborts any
    * in-flight stream. Use when switching agents or starting a fresh
@@ -158,7 +163,7 @@ export function useAgentChat({
   }, []);
 
   const send = useCallback(
-    async (message: string) => {
+    async (message: string, opts?: { skill?: string }) => {
       // Abort any previous stream — only one chat turn in flight per hook.
       abortControllerRef.current?.abort();
       const controller = new AbortController();
@@ -170,9 +175,24 @@ export function useAgentChat({
       setError(null);
       setIsStreaming(true);
 
+      // Resolve the forced skill: explicit opts.skill wins; otherwise parse a
+      // leading `/skill-name` token off the message. When the message is only
+      // the token, fall back to a minimal instruction so the turn isn't empty.
+      let text = message;
+      let skill = opts?.skill;
+      if (!skill) {
+        const match = text.match(/^\/([A-Za-z0-9][\w.:-]*)\s*/);
+        if (match) {
+          skill = match[1];
+          text = text.slice(match[0].length);
+          if (text.trim() === "") text = `Use the ${skill} skill.`;
+        }
+      }
+
       const payload = {
-        message,
+        message: text,
         agent,
+        ...(skill ? { skill } : {}),
         ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
       };
 
diff --git a/packages/appkit/src/core/agent/frontmatter.ts b/packages/appkit/src/core/agent/frontmatter.ts
new file mode 100644
index 000000000..57fba1b7d
--- /dev/null
+++ b/packages/appkit/src/core/agent/frontmatter.ts
@@ -0,0 +1,18 @@
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Splits a `--- yaml ---\nbody` markdown string into its raw YAML block and
+ * trimmed body. Returns `yaml: null` when there is no leading frontmatter
+ * fence. Shared by the agent loader ({@link parseFrontmatter}) and the skill
+ * parser so the fence regex lives in one place.
+ */
+export function splitFrontmatter(raw: string): {
+  yaml: string | null;
+  body: string;
+} {
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) {
+    return { yaml: null, body: raw.trim() };
+  }
+  return { yaml: match[1], body: match[2].trim() };
+}
diff --git a/packages/appkit/src/core/agent/load-agents.ts b/packages/appkit/src/core/agent/load-agents.ts
index 54c77f157..2952ccaae 100644
--- a/packages/appkit/src/core/agent/load-agents.ts
+++ b/packages/appkit/src/core/agent/load-agents.ts
@@ -16,6 +16,7 @@ import type {
 import { isToolkitEntry } from "../../core/agent/types";
 import { createLogger } from "../../logging/logger";
 import { agentDirNames } from "./agent-dirs";
+import { splitFrontmatter } from "./frontmatter";
 
 const logger = createLogger("agents:loader");
 
@@ -77,6 +78,13 @@ interface Frontmatter {
    * rejects non-empty values since there are no siblings to resolve against.
    */
   agents?: string[];
+  /**
+   * Names of global skills (from the shared `skills/` pool or a catalog
+   * volume) to make visible to this agent. Per-agent skills under
+   * `<id>/skills/` are always visible and need not be listed here. Ignored
+   * when the plugin's `autoInheritSkills` makes every global skill visible.
+   */
+  skills?: string[];
   maxSteps?: number;
   maxTokens?: number;
   /**
@@ -128,6 +136,7 @@ const ALLOWED_KEYS = new Set([
   "model",
   "tools",
   "agents",
+  "skills",
   "maxSteps",
   "maxTokens",
   "generationParams",
@@ -311,13 +320,13 @@ export function parseFrontmatter(
   raw: string,
   sourcePath?: string,
 ): { data: Frontmatter | null; content: string } {
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!match) {
-    return { data: null, content: raw.trim() };
+  const { yaml: yamlBlock, body } = splitFrontmatter(raw);
+  if (yamlBlock === null) {
+    return { data: null, content: body };
   }
   let parsed: unknown;
   try {
-    parsed = yaml.load(match[1]);
+    parsed = yaml.load(yamlBlock);
   } catch (err) {
     const src = sourcePath ? ` (${sourcePath})` : "";
     throw new Error(
@@ -325,7 +334,7 @@ export function parseFrontmatter(
     );
   }
   if (parsed === null || parsed === undefined) {
-    return { data: {}, content: match[2].trim() };
+    return { data: {}, content: body };
   }
   if (typeof parsed !== "object" || Array.isArray(parsed)) {
     const src = sourcePath ? ` (${sourcePath})` : "";
@@ -341,7 +350,7 @@ export function parseFrontmatter(
       );
     }
   }
-  return { data: data as Frontmatter, content: match[2].trim() };
+  return { data: data as Frontmatter, content: body };
 }
 
 const isNumber = (v: unknown): v is number => typeof v === "number";
@@ -411,6 +420,44 @@ function parseGenerationParams(
   return Object.keys(out).length > 0 ? (out as GenerationParams) : undefined;
 }
 
+/**
+ * Defensively parses a frontmatter `skills:` list into deduped skill names.
+ * Non-array values and non-string/empty entries are dropped with a warning,
+ * so a malformed list is visible rather than silently applied. Returns
+ * `undefined` when nothing valid is present.
+ */
+function parseSkillsFrontmatter(
+  value: unknown,
+  sourcePath?: string,
+): string[] | undefined {
+  if (value === undefined) return undefined;
+  const where = sourcePath ?? "<inline>";
+  if (!Array.isArray(value)) {
+    logger.warn(
+      "Ignoring 'skills' in %s: expected an array of skill names",
+      where,
+    );
+    return undefined;
+  }
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string" || item.trim() === "") {
+      logger.warn(
+        "Ignoring invalid 'skills' entry in %s: %s",
+        where,
+        JSON.stringify(item),
+      );
+      continue;
+    }
+    const name = item.trim();
+    if (seen.has(name)) continue;
+    seen.add(name);
+    out.push(name);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
 function buildDefinition(
   name: string,
   raw: string,
@@ -433,6 +480,7 @@ function buildDefinition(
     instructions: content,
     model,
     tools: Object.keys(tools).length > 0 ? tools : undefined,
+    skills: parseSkillsFrontmatter(fm.skills, filePath),
     maxSteps: typeof fm.maxSteps === "number" ? fm.maxSteps : undefined,
     maxTokens: typeof fm.maxTokens === "number" ? fm.maxTokens : undefined,
     generationParams: parseGenerationParams(fm.generationParams, filePath),
diff --git a/packages/appkit/src/core/agent/skills/index.ts b/packages/appkit/src/core/agent/skills/index.ts
new file mode 100644
index 000000000..40d00e8f9
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/index.ts
@@ -0,0 +1,6 @@
+export { loadSkillsFromDir } from "./load-skills";
+export { parseSkill } from "./parse-skill";
+export { readSkillResource } from "./read-resource";
+export { renderLoadedSkill, renderSkillCatalog } from "./render";
+export { resolveSkill, resolveSkillCatalog } from "./resolve-catalog";
+export type { ResolvedSkillCatalog, SkillDefinition } from "./types";
diff --git a/packages/appkit/src/core/agent/skills/load-skills.ts b/packages/appkit/src/core/agent/skills/load-skills.ts
new file mode 100644
index 000000000..60718ebc2
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/load-skills.ts
@@ -0,0 +1,94 @@
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { createLogger } from "../../../logging/logger";
+import { parseSkill } from "./parse-skill";
+import type { SkillDefinition, SkillSource } from "./types";
+
+const logger = createLogger("agents:skills");
+
+const SKILL_FILE = "SKILL.md";
+
+/**
+ * Discovers skills under `dir` — one subfolder per skill, each containing a
+ * `SKILL.md`. Returns `[]` if the directory does not exist. Folders without a
+ * `SKILL.md` are skipped with a warning (they may be non-skill assets).
+ *
+ * Reads bodies eagerly at load time; the body is only *injected* into model
+ * context on demand, so reading a small markdown file at boot is cheap.
+ */
+export async function loadSkillsFromDir(
+  dir: string,
+  source: SkillSource,
+): Promise<SkillDefinition[]> {
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+
+  const skillDirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+
+  const skills: SkillDefinition[] = [];
+  for (const name of skillDirs) {
+    const skillDir = path.join(dir, name);
+    const skillFile = path.join(skillDir, SKILL_FILE);
+    let raw: string;
+    try {
+      raw = await fs.readFile(skillFile, "utf-8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        logger.warn("Skipping '%s': no %s found.", skillDir, SKILL_FILE);
+        continue;
+      }
+      throw err;
+    }
+
+    const parsed = parseSkill(raw, skillFile);
+    const files = await listResourceFiles(skillDir);
+    skills.push({
+      name: parsed.name,
+      description: parsed.description,
+      body: parsed.body,
+      source,
+      dir: skillDir,
+      files,
+      allowedTools: parsed.allowedTools,
+    });
+  }
+
+  return skills;
+}
+
+/**
+ * Recursively lists resource files under a skill directory, returning relative
+ * posix paths and excluding the top-level `SKILL.md`. Used to build the file
+ * manifest `load_skill` returns so the model knows what else it can read.
+ */
+async function listResourceFiles(baseDir: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function walk(current: string, rel: string): Promise<void> {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(path.join(current, entry.name), childRel);
+      } else if (entry.isFile()) {
+        if (rel === "" && entry.name === SKILL_FILE) continue;
+        out.push(childRel);
+      }
+    }
+  }
+
+  await walk(baseDir, "");
+  return out;
+}
diff --git a/packages/appkit/src/core/agent/skills/parse-skill.ts b/packages/appkit/src/core/agent/skills/parse-skill.ts
new file mode 100644
index 000000000..bd622bc11
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/parse-skill.ts
@@ -0,0 +1,130 @@
+import yaml from "js-yaml";
+
+import { createLogger } from "../../../logging/logger";
+import { splitFrontmatter } from "../frontmatter";
+
+const logger = createLogger("agents:skills");
+
+/**
+ * Frontmatter keys AppKit recognizes. Compatibility-first: this is the
+ * Anthropic `SKILL.md` surface (`name`, `description`, `license`,
+ * `allowed-tools`, `metadata`) so skills authored for Claude Code / Cursor
+ * load unmodified. Unknown keys warn rather than error.
+ */
+const KNOWN_SKILL_KEYS = new Set([
+  "name",
+  "description",
+  "license",
+  "allowed-tools",
+  "metadata",
+]);
+
+/** Addressable-name guard: no `:` (qualified-name separator), no `/`, no whitespace. */
+const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+
+interface ParsedSkill {
+  name: string;
+  description: string;
+  body: string;
+  allowedTools?: string[];
+}
+
+/**
+ * Parses a `SKILL.md` string. Requires non-empty `name` + `description`;
+ * validates the name is addressable; warns on unknown frontmatter keys.
+ */
+export function parseSkill(raw: string, sourcePath: string): ParsedSkill {
+  const { yaml: yamlBlock, body } = splitFrontmatter(raw);
+  if (yamlBlock === null) {
+    throw new Error(
+      `Skill file ${sourcePath} has no YAML frontmatter (expected '--- name/description ---').`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = yaml.load(yamlBlock);
+  } catch (err) {
+    throw new Error(
+      `Invalid YAML frontmatter in ${sourcePath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `Skill frontmatter in ${sourcePath} must be a YAML object.`,
+    );
+  }
+
+  const data = parsed as Record<string, unknown>;
+  const { name, description } = data;
+
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new Error(
+      `Skill ${sourcePath} is missing a non-empty 'name' in frontmatter.`,
+    );
+  }
+  const trimmedName = name.trim();
+  if (!NAME_RE.test(trimmedName)) {
+    throw new Error(
+      `Skill '${trimmedName}' (${sourcePath}) has an invalid name: use letters, digits, '.', '_', '-' only (no ':', '/', or spaces).`,
+    );
+  }
+  if (typeof description !== "string" || description.trim() === "") {
+    throw new Error(
+      `Skill '${trimmedName}' (${sourcePath}) is missing a non-empty 'description' in frontmatter.`,
+    );
+  }
+
+  for (const key of Object.keys(data)) {
+    if (!KNOWN_SKILL_KEYS.has(key)) {
+      logger.warn(
+        "Ignoring unknown SKILL.md frontmatter key '%s' in %s",
+        key,
+        sourcePath,
+      );
+    }
+  }
+
+  return {
+    name: trimmedName,
+    description: description.trim(),
+    body,
+    allowedTools: parseAllowedTools(
+      data["allowed-tools"],
+      trimmedName,
+      sourcePath,
+    ),
+  };
+}
+
+/**
+ * Accepts `allowed-tools` as a string[] or a comma-separated string (both
+ * appear in the wild). Returns `undefined` when absent/empty/malformed.
+ */
+function parseAllowedTools(
+  value: unknown,
+  skillName: string,
+  sourcePath: string,
+): string[] | undefined {
+  if (value === undefined) return undefined;
+
+  let list: string[];
+  if (typeof value === "string") {
+    list = value.split(",");
+  } else if (
+    Array.isArray(value) &&
+    value.every((v) => typeof v === "string")
+  ) {
+    list = value as string[];
+  } else {
+    logger.warn(
+      "Ignoring 'allowed-tools' for skill '%s' in %s: expected string or string[]",
+      skillName,
+      sourcePath,
+    );
+    return undefined;
+  }
+
+  const cleaned = list.map((s) => s.trim()).filter((s) => s.length > 0);
+  return cleaned.length > 0 ? cleaned : undefined;
+}
diff --git a/packages/appkit/src/core/agent/skills/read-resource.ts b/packages/appkit/src/core/agent/skills/read-resource.ts
new file mode 100644
index 000000000..8c14d9e59
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/read-resource.ts
@@ -0,0 +1,52 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/** Read cap for a bundled skill resource file (bytes). */
+const MAX_SKILL_FILE_BYTES = 1_000_000;
+
+/**
+ * Reads a bundled skill resource file from local disk, constrained to the
+ * skill's own directory. The path must be relative; `..` traversal, null
+ * bytes, and absolute paths are rejected, and the resolved path is verified
+ * to stay within `baseDir` (a containment guard the agent markdown loader
+ * does not itself apply). Throws when the target is missing, not a file, or
+ * exceeds the size cap.
+ */
+export async function readSkillResource(
+  baseDir: string,
+  relPath: string,
+  maxSize = MAX_SKILL_FILE_BYTES,
+): Promise<string> {
+  if (relPath.includes("\0")) {
+    throw new Error("Path must not contain null bytes.");
+  }
+  if (relPath.length > 4096) {
+    throw new Error("Path exceeds the maximum length of 4096 characters.");
+  }
+  if (path.isAbsolute(relPath)) {
+    throw new Error(
+      "Skill resource path must be relative to the skill directory.",
+    );
+  }
+  if (relPath.split(/[\\/]/).some((segment) => segment === "..")) {
+    throw new Error('Path traversal ("../") is not allowed.');
+  }
+
+  const root = path.resolve(baseDir);
+  const abs = path.resolve(root, relPath);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    throw new Error("Resolved path escapes the skill directory.");
+  }
+
+  const stat = await fs.stat(abs);
+  if (!stat.isFile()) {
+    throw new Error(`Skill resource '${relPath}' is not a file.`);
+  }
+  if (stat.size > maxSize) {
+    throw new Error(
+      `Skill resource '${relPath}' exceeds the ${maxSize}-byte read limit.`,
+    );
+  }
+
+  return fs.readFile(abs, "utf-8");
+}
diff --git a/packages/appkit/src/core/agent/skills/render.ts b/packages/appkit/src/core/agent/skills/render.ts
new file mode 100644
index 000000000..1f87247da
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/render.ts
@@ -0,0 +1,42 @@
+import type { SkillCatalogEntry, SkillDefinition } from "./types";
+
+/**
+ * Renders the always-on skill catalog block appended to an agent's system
+ * prompt. Lists each visible skill's name + description and tells the model to
+ * call `load_skill` before acting on a matching task.
+ */
+export function renderSkillCatalog(entries: SkillCatalogEntry[]): string {
+  return [
+    "## Available skills",
+    "When a task matches one of these skills, call the `load_skill` tool with the skill's exact name to load its full instructions before proceeding.",
+    "",
+    ...entries.map((e) => `- **${e.name}**: ${e.description}`),
+  ].join("\n");
+}
+
+/**
+ * Renders the tool-result payload returned by `load_skill`: the skill body
+ * plus a manifest of bundled files (readable via `read_skill_file`) and any
+ * advisory `allowed-tools` hint.
+ */
+export function renderLoadedSkill(skill: SkillDefinition): string {
+  const parts = [`# Skill: ${skill.name}`, "", skill.body];
+
+  if (skill.files.length > 0) {
+    parts.push(
+      "",
+      "## Bundled files",
+      "Read any of these with the `read_skill_file` tool (pass this skill's name and the file path):",
+      ...skill.files.map((f) => `- ${f}`),
+    );
+  }
+
+  if (skill.allowedTools && skill.allowedTools.length > 0) {
+    parts.push(
+      "",
+      `_Suggested tools for this skill: ${skill.allowedTools.join(", ")}._`,
+    );
+  }
+
+  return parts.join("\n");
+}
diff --git a/packages/appkit/src/core/agent/skills/resolve-catalog.ts b/packages/appkit/src/core/agent/skills/resolve-catalog.ts
new file mode 100644
index 000000000..410b18bf2
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/resolve-catalog.ts
@@ -0,0 +1,138 @@
+import { createLogger } from "../../../logging/logger";
+import type {
+  ResolvedSkillCatalog,
+  SkillCatalogEntry,
+  SkillDefinition,
+  SkillSource,
+} from "./types";
+
+const logger = createLogger("agents:skills");
+
+/** Qualified-name scope prefix per source, used only on cross-source collision. */
+const SCOPE_BY_SOURCE: Record<SkillSource, string> = {
+  "bundle-agent": "agent",
+  "bundle-global": "bundle",
+  volume: "volume",
+};
+
+interface ResolveCatalogInput {
+  agentName: string;
+  /** The agent's `skills:` frontmatter — opt-in selection from the global pool. */
+  agentSkillNames?: string[];
+  /** Skills private to this agent (`<id>/skills/`), always visible. */
+  perAgentSkills: SkillDefinition[];
+  /** Shared pool (bundle-global + volume), visible only when opted in or inherited. */
+  globalSkills: SkillDefinition[];
+  /** When true, every global skill is visible without an explicit `skills:` list. */
+  autoInherit: boolean;
+}
+
+/**
+ * Applies visibility (per-agent auto; global opt-in or auto-inherit) then
+ * collision handling: a unique name is addressable bare; a name provided by
+ * multiple sources becomes `<scope>:name` per source and the bare name is
+ * marked ambiguous (addressing it errors with the alternatives). Two skills
+ * with the same name from the *same* source is a fatal config error.
+ */
+export function resolveSkillCatalog(
+  input: ResolveCatalogInput,
+): ResolvedSkillCatalog {
+  const {
+    agentName,
+    agentSkillNames,
+    perAgentSkills,
+    globalSkills,
+    autoInherit,
+  } = input;
+
+  const visible: SkillDefinition[] = [...perAgentSkills];
+  if (autoInherit) {
+    visible.push(...globalSkills);
+  } else if (agentSkillNames && agentSkillNames.length > 0) {
+    const wanted = new Set(agentSkillNames);
+    for (const skill of globalSkills) {
+      if (wanted.has(skill.name)) visible.push(skill);
+    }
+    const localNames = new Set(perAgentSkills.map((s) => s.name));
+    const globalNames = new Set(globalSkills.map((s) => s.name));
+    for (const want of agentSkillNames) {
+      if (!globalNames.has(want) && !localNames.has(want)) {
+        logger.warn(
+          "Agent '%s' lists skill '%s' in 'skills:', but no global or per-agent skill with that name exists.",
+          agentName,
+          want,
+        );
+      }
+    }
+  }
+
+  const byName = new Map<string, SkillDefinition[]>();
+  for (const skill of visible) {
+    const group = byName.get(skill.name) ?? [];
+    group.push(skill);
+    byName.set(skill.name, group);
+  }
+
+  const byAddress = new Map<string, SkillDefinition>();
+  const ambiguous = new Map<string, string[]>();
+
+  for (const [name, group] of byName) {
+    if (group.length === 1) {
+      byAddress.set(name, group[0]);
+      continue;
+    }
+
+    const alternatives: string[] = [];
+    for (const skill of group) {
+      const qualified = `${SCOPE_BY_SOURCE[skill.source]}:${name}`;
+      const existing = byAddress.get(qualified);
+      if (existing) {
+        throw new Error(
+          `Agent '${agentName}': two '${skill.source}' skills are both named '${name}' ` +
+            `(${existing.dir} and ${skill.dir}). Skill names must be unique within a source.`,
+        );
+      }
+      byAddress.set(qualified, skill);
+      alternatives.push(qualified);
+    }
+    alternatives.sort();
+    ambiguous.set(name, alternatives);
+    logger.warn(
+      "Agent '%s': skill name '%s' is provided by multiple sources; address it as %s.",
+      agentName,
+      name,
+      alternatives.join(" or "),
+    );
+  }
+
+  const catalog: SkillCatalogEntry[] = [...byAddress.entries()]
+    .map(([address, skill]) => ({
+      name: address,
+      description: skill.description,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return { byAddress, ambiguous, catalog };
+}
+
+/**
+ * Resolves a requested skill name (bare or qualified) against a catalog.
+ * Throws a helpful error on ambiguous or unknown names.
+ */
+export function resolveSkill(
+  catalog: ResolvedSkillCatalog,
+  requested: string,
+): SkillDefinition {
+  const direct = catalog.byAddress.get(requested);
+  if (direct) return direct;
+
+  const alternatives = catalog.ambiguous.get(requested);
+  if (alternatives) {
+    throw new Error(
+      `Skill '${requested}' is ambiguous; specify one of: ${alternatives.join(", ")}.`,
+    );
+  }
+
+  const available = [...catalog.byAddress.keys()].sort().join(", ") || "<none>";
+  throw new Error(`Unknown skill '${requested}'. Available: ${available}.`);
+}
diff --git a/packages/appkit/src/core/agent/skills/tests/skills.test.ts b/packages/appkit/src/core/agent/skills/tests/skills.test.ts
new file mode 100644
index 000000000..3ef906eb6
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/tests/skills.test.ts
@@ -0,0 +1,330 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { loadSkillsFromDir } from "../load-skills";
+import { parseSkill } from "../parse-skill";
+import { readSkillResource } from "../read-resource";
+import { renderLoadedSkill, renderSkillCatalog } from "../render";
+import { resolveSkill, resolveSkillCatalog } from "../resolve-catalog";
+import type { SkillDefinition, SkillSource } from "../types";
+
+let workDir: string;
+
+beforeEach(() => {
+  workDir = fs.mkdtempSync(path.join(os.tmpdir(), "skills-test-"));
+});
+
+afterEach(() => {
+  fs.rmSync(workDir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+/** Writes `<workDir>/<name>/SKILL.md` plus optional sibling resource files. */
+function writeSkill(
+  name: string,
+  content: string,
+  files: Record<string, string> = {},
+) {
+  const dir = path.join(workDir, name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, "SKILL.md"), content, "utf-8");
+  for (const [rel, body] of Object.entries(files)) {
+    const abs = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, body, "utf-8");
+  }
+  return dir;
+}
+
+/** Convenience for resolver tests that don't need real files. */
+function skill(
+  name: string,
+  source: SkillSource,
+  overrides: Partial<SkillDefinition> = {},
+): SkillDefinition {
+  return {
+    name,
+    description: `${name} description`,
+    body: `${name} body`,
+    source,
+    dir: `/fake/${source}/${name}`,
+    files: [],
+    ...overrides,
+  };
+}
+
+describe("parseSkill", () => {
+  test("parses name, description, and body", () => {
+    const parsed = parseSkill(
+      "---\nname: pdf\ndescription: Work with PDFs\n---\nHow to work with PDFs.",
+      "SKILL.md",
+    );
+    expect(parsed).toMatchObject({
+      name: "pdf",
+      description: "Work with PDFs",
+      body: "How to work with PDFs.",
+    });
+    expect(parsed.allowedTools).toBeUndefined();
+  });
+
+  test("accepts allowed-tools as an array or comma string", () => {
+    const arr = parseSkill(
+      "---\nname: a\ndescription: d\nallowed-tools:\n  - read\n  - grep\n---\nbody",
+      "SKILL.md",
+    );
+    expect(arr.allowedTools).toEqual(["read", "grep"]);
+
+    const str = parseSkill(
+      "---\nname: b\ndescription: d\nallowed-tools: read, grep\n---\nbody",
+      "SKILL.md",
+    );
+    expect(str.allowedTools).toEqual(["read", "grep"]);
+  });
+
+  test("throws when name or description is missing", () => {
+    expect(() =>
+      parseSkill("---\ndescription: d\n---\nbody", "SKILL.md"),
+    ).toThrow(/missing a non-empty 'name'/);
+    expect(() => parseSkill("---\nname: a\n---\nbody", "SKILL.md")).toThrow(
+      /missing a non-empty 'description'/,
+    );
+  });
+
+  test("rejects a name that breaks addressing", () => {
+    expect(() =>
+      parseSkill("---\nname: bad:name\ndescription: d\n---\nbody", "SKILL.md"),
+    ).toThrow(/invalid name/);
+  });
+
+  test("throws when frontmatter is absent", () => {
+    expect(() => parseSkill("no frontmatter here", "SKILL.md")).toThrow(
+      /no YAML frontmatter/,
+    );
+  });
+
+  test("warns on unknown frontmatter keys, keeps parsing", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const parsed = parseSkill(
+      "---\nname: a\ndescription: d\nbananas: 3\n---\nbody",
+      "SKILL.md",
+    );
+    expect(parsed.name).toBe("a");
+    expect(warn).toHaveBeenCalled();
+  });
+});
+
+describe("loadSkillsFromDir", () => {
+  test("returns [] for a missing directory", async () => {
+    const skills = await loadSkillsFromDir(
+      path.join(workDir, "nope"),
+      "bundle-global",
+    );
+    expect(skills).toEqual([]);
+  });
+
+  test("discovers skills and enumerates resource files recursively", async () => {
+    writeSkill("pdf", "---\nname: pdf\ndescription: d\n---\nbody", {
+      "reference.md": "ref",
+      "scripts/extract.py": "print(1)",
+    });
+    const skills = await loadSkillsFromDir(workDir, "bundle-global");
+    expect(skills).toHaveLength(1);
+    expect(skills[0]).toMatchObject({
+      name: "pdf",
+      description: "d",
+      body: "body",
+      source: "bundle-global",
+    });
+    expect(skills[0].files).toEqual(["reference.md", "scripts/extract.py"]);
+  });
+
+  test("skips folders without a SKILL.md", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    fs.mkdirSync(path.join(workDir, "not-a-skill"), { recursive: true });
+    writeSkill("real", "---\nname: real\ndescription: d\n---\nbody");
+    const skills = await loadSkillsFromDir(workDir, "bundle-global");
+    expect(skills.map((s) => s.name)).toEqual(["real"]);
+    expect(warn).toHaveBeenCalled();
+  });
+});
+
+describe("resolveSkillCatalog", () => {
+  test("per-agent skills are auto-visible; global skills are opt-in", () => {
+    const local = skill("local", "bundle-agent");
+    const g1 = skill("wanted", "bundle-global");
+    const g2 = skill("unwanted", "bundle-global");
+
+    const catalog = resolveSkillCatalog({
+      agentName: "a",
+      agentSkillNames: ["wanted"],
+      perAgentSkills: [local],
+      globalSkills: [g1, g2],
+      autoInherit: false,
+    });
+
+    expect([...catalog.byAddress.keys()].sort()).toEqual(["local", "wanted"]);
+    expect(catalog.catalog.map((e) => e.name).sort()).toEqual([
+      "local",
+      "wanted",
+    ]);
+  });
+
+  test("autoInherit exposes every global skill without an opt-in list", () => {
+    const catalog = resolveSkillCatalog({
+      agentName: "a",
+      perAgentSkills: [],
+      globalSkills: [skill("x", "bundle-global"), skill("y", "bundle-global")],
+      autoInherit: true,
+    });
+    expect([...catalog.byAddress.keys()].sort()).toEqual(["x", "y"]);
+  });
+
+  test("warns for opt-in names that match no skill", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    resolveSkillCatalog({
+      agentName: "a",
+      agentSkillNames: ["ghost"],
+      perAgentSkills: [],
+      globalSkills: [skill("real", "bundle-global")],
+      autoInherit: false,
+    });
+    expect(warn).toHaveBeenCalled();
+  });
+
+  test("cross-source name collision produces qualified names + ambiguous bare", () => {
+    const catalog = resolveSkillCatalog({
+      agentName: "a",
+      perAgentSkills: [skill("dup", "bundle-agent")],
+      globalSkills: [skill("dup", "bundle-global"), skill("dup", "volume")],
+      autoInherit: true,
+    });
+    expect([...catalog.byAddress.keys()].sort()).toEqual([
+      "agent:dup",
+      "bundle:dup",
+      "volume:dup",
+    ]);
+    expect(catalog.ambiguous.get("dup")).toEqual([
+      "agent:dup",
+      "bundle:dup",
+      "volume:dup",
+    ]);
+  });
+
+  test("throws when two skills from the same source share a name", () => {
+    expect(() =>
+      resolveSkillCatalog({
+        agentName: "a",
+        perAgentSkills: [],
+        globalSkills: [
+          skill("dup", "bundle-global", { dir: "/a" }),
+          skill("dup", "bundle-global", { dir: "/b" }),
+        ],
+        autoInherit: true,
+      }),
+    ).toThrow(/unique within a source/);
+  });
+});
+
+describe("resolveSkill", () => {
+  const catalog = resolveSkillCatalog({
+    agentName: "a",
+    perAgentSkills: [skill("solo", "bundle-agent")],
+    globalSkills: [skill("dup", "bundle-global"), skill("dup", "volume")],
+    autoInherit: true,
+  });
+
+  test("resolves a bare unique name", () => {
+    expect(resolveSkill(catalog, "solo").name).toBe("solo");
+  });
+
+  test("resolves a qualified name", () => {
+    expect(resolveSkill(catalog, "volume:dup").source).toBe("volume");
+  });
+
+  test("errors on an ambiguous bare name, listing alternatives", () => {
+    expect(() => resolveSkill(catalog, "dup")).toThrow(
+      /ambiguous.*bundle:dup.*volume:dup/,
+    );
+  });
+
+  test("errors on an unknown name", () => {
+    expect(() => resolveSkill(catalog, "missing")).toThrow(/Unknown skill/);
+  });
+});
+
+describe("renderSkillCatalog", () => {
+  test("lists each entry and points at load_skill", () => {
+    const out = renderSkillCatalog([
+      { name: "pdf", description: "Work with PDFs" },
+      { name: "sql", description: "Write SQL" },
+    ]);
+    expect(out).toContain("load_skill");
+    expect(out).toContain("**pdf**: Work with PDFs");
+    expect(out).toContain("**sql**: Write SQL");
+  });
+});
+
+describe("renderLoadedSkill", () => {
+  test("includes the body and a file manifest when present", () => {
+    const out = renderLoadedSkill(
+      skill("pdf", "bundle-global", {
+        body: "Detailed PDF instructions.",
+        files: ["reference.md", "scripts/x.py"],
+        allowedTools: ["read", "grep"],
+      }),
+    );
+    expect(out).toContain("Detailed PDF instructions.");
+    expect(out).toContain("read_skill_file");
+    expect(out).toContain("- reference.md");
+    expect(out).toContain("- scripts/x.py");
+    expect(out).toContain("Suggested tools for this skill: read, grep");
+  });
+
+  test("omits the manifest when there are no bundled files", () => {
+    const out = renderLoadedSkill(
+      skill("bare", "bundle-agent", { body: "Just prose.", files: [] }),
+    );
+    expect(out).toContain("Just prose.");
+    expect(out).not.toContain("Bundled files");
+  });
+});
+
+describe("readSkillResource", () => {
+  test("reads a file inside the skill directory", async () => {
+    const dir = writeSkill("pdf", "---\nname: pdf\ndescription: d\n---\nbody", {
+      "reference.md": "the reference",
+    });
+    await expect(readSkillResource(dir, "reference.md")).resolves.toBe(
+      "the reference",
+    );
+  });
+
+  test("rejects traversal, absolute paths, and escapes", async () => {
+    const dir = writeSkill("pdf", "---\nname: pdf\ndescription: d\n---\nbody");
+    // A real secret sitting next to the skill dir, reachable only via escape.
+    fs.writeFileSync(path.join(workDir, "secret.txt"), "top secret", "utf-8");
+    await expect(readSkillResource(dir, "../secret.txt")).rejects.toThrow(
+      /traversal/,
+    );
+    await expect(
+      readSkillResource(dir, path.join(workDir, "secret.txt")),
+    ).rejects.toThrow(/relative/);
+  });
+
+  test("throws when the file is missing", async () => {
+    const dir = writeSkill("pdf", "---\nname: pdf\ndescription: d\n---\nbody");
+    await expect(readSkillResource(dir, "nope.md")).rejects.toThrow();
+  });
+
+  test("enforces the size cap", async () => {
+    const dir = writeSkill("pdf", "---\nname: pdf\ndescription: d\n---\nbody", {
+      "big.txt": "x".repeat(50),
+    });
+    await expect(readSkillResource(dir, "big.txt", 10)).rejects.toThrow(
+      /read limit/,
+    );
+  });
+});
diff --git a/packages/appkit/src/core/agent/skills/types.ts b/packages/appkit/src/core/agent/skills/types.ts
new file mode 100644
index 000000000..34717551c
--- /dev/null
+++ b/packages/appkit/src/core/agent/skills/types.ts
@@ -0,0 +1,49 @@
+/** Where a skill was discovered. Drives the qualified name used on collision. */
+export type SkillSource = "bundle-agent" | "bundle-global" | "volume";
+
+/**
+ * A single skill: a `SKILL.md` (frontmatter `name`+`description` + Markdown
+ * body) plus any bundled resource files in the same directory. The body is
+ * loaded into model context on demand (via the `load_skill` tool or a forced
+ * `/skill-name` invocation); only `name`+`description` are always-on in the
+ * prompt catalog.
+ */
+export interface SkillDefinition {
+  /** Frontmatter `name`. The addressable skill id. */
+  name: string;
+  /** Frontmatter `description`. Injected into the always-on prompt catalog. */
+  description: string;
+  /** Markdown body — the instructions loaded on demand. */
+  body: string;
+  /** Where the skill came from. */
+  source: SkillSource;
+  /** Absolute directory containing `SKILL.md` and any bundled resources. */
+  dir: string;
+  /** Relative posix paths of bundled resource files (excludes `SKILL.md`). */
+  files: string[];
+  /**
+   * Optional advisory tool allowlist from frontmatter `allowed-tools`. Surfaced
+   * as a hint in v1 — NOT enforced (loading a skill does not restrict the
+   * agent's callable tools).
+   */
+  allowedTools?: string[];
+}
+
+/** The always-on prompt entry for a skill (what the model sees before loading). */
+export interface SkillCatalogEntry {
+  /** Addressable name — bare when unique, `<scope>:name` when collided. */
+  name: string;
+  description: string;
+}
+
+/**
+ * Per-agent resolved skill catalog: visibility + collision rules applied.
+ * `byAddress` maps every addressable name (bare or qualified) to its skill;
+ * `ambiguous` maps a bare name shadowed by multiple sources to the qualified
+ * alternatives; `catalog` is the always-on prompt list (one entry per address).
+ */
+export interface ResolvedSkillCatalog {
+  byAddress: Map<string, SkillDefinition>;
+  ambiguous: Map<string, string[]>;
+  catalog: SkillCatalogEntry[];
+}
diff --git a/packages/appkit/src/core/agent/tests/load-agents.test.ts b/packages/appkit/src/core/agent/tests/load-agents.test.ts
index e17160168..cc927d9a8 100644
--- a/packages/appkit/src/core/agent/tests/load-agents.test.ts
+++ b/packages/appkit/src/core/agent/tests/load-agents.test.ts
@@ -194,6 +194,15 @@ describe("loadAgentsFromDir", () => {
     expect(Object.keys(res.defs)).toEqual(["solo"]);
   });
 
+  test("parses the skills opt-in list from frontmatter", async () => {
+    writeAgent(
+      "picker",
+      "---\nendpoint: e\nskills:\n  - pdf\n  - pdf\n  - sql\n---\nPrompt.",
+    );
+    const res = await loadAgentsFromDir(workDir, {});
+    expect(res.defs.picker.skills).toEqual(["pdf", "sql"]);
+  });
+
   test("picks up default: true from frontmatter (deterministic sorted ids)", async () => {
     writeAgent("one", "---\nendpoint: a\n---\nOne.");
     writeAgent("two", "---\nendpoint: b\ndefault: true\n---\nTwo.");
diff --git a/packages/appkit/src/core/agent/types.ts b/packages/appkit/src/core/agent/types.ts
index 234aa45c1..53dae3c87 100644
--- a/packages/appkit/src/core/agent/types.ts
+++ b/packages/appkit/src/core/agent/types.ts
@@ -8,6 +8,7 @@ import type {
 
 import type { GenerationParams } from "../../agents/databricks";
 import type { McpHostPolicyConfig } from "../../connectors/mcp";
+import type { ResolvedSkillCatalog } from "./skills/types";
 import type { FunctionTool } from "./tools/function-tool";
 import type { HostedTool } from "./tools/hosted-tools";
 
@@ -173,6 +174,13 @@ export interface AgentDefinition {
   tools?: AgentTools | AgentToolsFn;
   /** Sub-agents, exposed as `agent-<key>` tools on this agent. */
   agents?: Record<string, AgentDefinition>;
+  /**
+   * Names of global skills (shared `skills/` pool or catalog volume) to make
+   * visible to this agent. Per-agent skills under `<id>/skills/` are always
+   * visible and need not be listed. Ignored when the plugin's
+   * `autoInheritSkills` makes every global skill visible.
+   */
+  skills?: string[];
   /** Override the plugin's baseSystemPrompt for this agent only. */
   baseSystemPrompt?: BaseSystemPromptOption;
   maxSteps?: number;
@@ -233,6 +241,28 @@ export interface AgentsPluginConfig extends BasePluginConfig {
   tools?: Record<string, AgentTool>;
   /** Whether to auto-inherit every ToolProvider plugin's toolkit. Accepts a boolean shorthand. */
   autoInheritTools?: boolean | AutoInheritToolsConfig;
+  /**
+   * Whether every global skill (shared `skills/` pool or catalog volume) is
+   * visible to an agent without listing it in `skills:` frontmatter. Off by
+   * default so each agent's always-on skill catalog stays lean; accepts a
+   * boolean shorthand or a per-origin `{ file, code }` config, mirroring
+   * {@link autoInheritTools}.
+   */
+  autoInheritSkills?: boolean | AutoInheritToolsConfig;
+  /**
+   * Unity Catalog Volume path for catalog-sourced skills (e.g.
+   * `/Volumes/<catalog>/<schema>/<volume>`). Falls back to the
+   * `DATABRICKS_VOLUME_AGENT_SKILLS` env var. Skills at `<volume>/<name>/SKILL.md`
+   * are discovered at boot and on `reload()` and read as the service principal.
+   */
+  skillsVolume?: string;
+  /**
+   * Identity used to read catalog (volume) skills. v1 supports `"sp"` (default —
+   * a shared, service-principal-readable curated pool). `"obo"` is the reserved
+   * switch point for per-user skill volumes and is not wired yet (falls back to
+   * `"sp"` with a warning).
+   */
+  skillCredentialMode?: "sp" | "obo";
   /** Persistent thread store. Default: in-memory. */
   threadStore?: ThreadStore;
   /** Customize or disable the AppKit base system prompt. */
@@ -343,6 +373,18 @@ export type ResolvedToolEntry =
       source: "hosted-supervisor";
       spec: import("../../agents/supervisor-api").SupervisorTool;
       def: AgentToolDefinition;
+    }
+  | {
+      /**
+       * Built-in skill tools (`load_skill`, `read_skill_file`) injected into
+       * any agent that has a visible skill catalog. Executed in-process by the
+       * agents plugin against the agent's resolved catalog; read-only, so they
+       * bypass the approval gate.
+       */
+      source: "skill";
+      builtin: "load_skill" | "read_skill_file";
+      catalog: ResolvedSkillCatalog;
+      def: AgentToolDefinition;
     };
 
 export interface RegisteredAgent {
@@ -357,6 +399,12 @@ export interface RegisteredAgent {
   generationParams?: GenerationParams;
   /** Mirrors `AgentDefinition.ephemeral` — skip thread persistence. */
   ephemeral?: boolean;
+  /**
+   * Resolved per-agent skill catalog (visibility + collision rules applied).
+   * Present when any skill is visible to this agent; drives the always-on
+   * prompt catalog and `load_skill` dispatch.
+   */
+  skills?: ResolvedSkillCatalog;
 }
 
 /**
diff --git a/packages/appkit/src/plugins/agents/agents.ts b/packages/appkit/src/plugins/agents/agents.ts
index b9e508a45..c03a0c8b5 100644
--- a/packages/appkit/src/plugins/agents/agents.ts
+++ b/packages/appkit/src/plugins/agents/agents.ts
@@ -23,7 +23,9 @@ import {
   SUPERVISOR_EXTENSION_KEY,
   type SupervisorTool,
 } from "../../agents/supervisor-api";
+import { FilesConnector } from "../../connectors/files";
 import { AppKitMcpClient, buildMcpHostPolicy } from "../../connectors/mcp";
+import { getWorkspaceClient } from "../../context";
 import { consumeAdapterStream } from "../../core/agent/consume-adapter-stream";
 import { loadAgentsFromDir } from "../../core/agent/load-agents";
 import {
@@ -33,6 +35,17 @@ import {
 } from "../../core/agent/load-code-agents";
 import { normalizeToolResult } from "../../core/agent/normalize-result";
 import { createPluginsProxy } from "../../core/agent/plugins-map";
+import {
+  loadSkillsFromDir,
+  parseSkill,
+  type ResolvedSkillCatalog,
+  readSkillResource,
+  renderLoadedSkill,
+  renderSkillCatalog,
+  resolveSkill,
+  resolveSkillCatalog,
+  type SkillDefinition,
+} from "../../core/agent/skills";
 import {
   buildBaseSystemPrompt,
   composeSystemPrompt,
@@ -59,6 +72,7 @@ import { isToolkitEntry } from "../../core/agent/types";
 import { createLogger } from "../../logging/logger";
 import { Plugin, toPlugin } from "../../plugin";
 import type { PluginManifest } from "../../registry";
+import type { WorkspaceClient } from "../../workspace-client";
 import { agentStreamDefaults } from "./defaults";
 import { EventChannel } from "./event-channel";
 import { AgentEventTranslator } from "./event-translator";
@@ -150,9 +164,9 @@ interface RunState {
 
 export class AgentsPlugin extends Plugin implements ToolProvider {
   // Routed through `unknown`: the optional resources have differing `fields`
-  // keys (serving `name`, experiment `experimentId`), which TS widens to an
-  // incompatible union on the JSON import. The shape is validated at runtime
-  // against the plugin-manifest schema.
+  // keys (serving `name`, experiment `experimentId`, volume `path`), which TS
+  // widens to an incompatible union on the JSON import. The shape is validated
+  // at runtime against the plugin-manifest schema.
   static manifest = manifest as unknown as PluginManifest;
   static phase: PluginPhase = "deferred";
 
@@ -210,6 +224,13 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
    * negative, or `NaN`) can't degrade into immediate auto-denial of every
    * mutating tool call.
    */
+  /**
+   * Shared global skill pool (bundle `skills/` + catalog volume), loaded once
+   * per registry build. Read by {@link buildRegisteredAgent} to resolve each
+   * agent's visible catalog and by the live `register` path.
+   */
+  private globalSkills: SkillDefinition[] = [];
+
   private cachedApprovalPolicy: {
     requireForDestructive: boolean;
     timeoutMs: number;
@@ -348,6 +369,14 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
     const discovered = await this.loadCodeAgents();
     const deprecatedMapRaw = this.config.agents ?? {};
 
+    // Global skills (bundle + configured UC volume) load in parallel; per-agent
+    // skills resolve later during agent build.
+    const [bundleSkills, volumeSkills] = await Promise.all([
+      this.loadGlobalSkills(),
+      this.loadVolumeSkills(),
+    ]);
+    this.globalSkills = [...bundleSkills, ...volumeSkills];
+
     if (Object.keys(deprecatedMapRaw).length > 0) {
       this.warnAgentsMapDeprecated();
     }
@@ -626,7 +655,8 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
     src: AgentSource,
   ): Promise<RegisteredAgent> {
     const adapter = await this.resolveAdapter(def, name);
-    const toolIndex = await this.buildToolIndex(name, def, src);
+    const skills = await this.resolveAgentSkills(name, def, src);
+    const toolIndex = await this.buildToolIndex(name, def, src, skills);
 
     warnOnCapabilityMismatch(name, adapter, toolIndex);
 
@@ -640,9 +670,161 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
       maxTokens: def.maxTokens,
       generationParams: def.generationParams,
       ephemeral: def.ephemeral,
+      skills,
     };
   }
 
+  /** Loads the shared global skill pool from `<agentsDir>/skills/`. */
+  private async loadGlobalSkills(): Promise<SkillDefinition[]> {
+    const dir = this.resolvedAgentsDir();
+    if (!dir) return [];
+    return loadSkillsFromDir(path.join(dir, "skills"), "bundle-global");
+  }
+
+  /** Configured catalog-skills volume path, or null when none is set. */
+  private resolveSkillsVolume(): string | null {
+    const configured =
+      this.config.skillsVolume ?? process.env.DATABRICKS_VOLUME_AGENT_SKILLS;
+    return configured && configured.trim() !== "" ? configured.trim() : null;
+  }
+
+  /**
+   * Workspace client used to read catalog skills. v1 reads as the app service
+   * principal; `getWorkspaceClient()` resolves to SP outside a user scope
+   * (boot and skill-tool dispatch are both unscoped). This is the single
+   * switch point for a future OBO mode.
+   */
+  private skillWorkspaceClient(): WorkspaceClient {
+    return getWorkspaceClient();
+  }
+
+  /**
+   * Discovers catalog skills from the configured UC Volume, read as the
+   * service principal at boot (and on `reload()`). Each `<volume>/<name>/`
+   * folder with a `SKILL.md` becomes a `source: "volume"` skill. Best-effort:
+   * a missing volume, unavailable workspace client, or a malformed individual
+   * skill is logged and skipped rather than failing the whole registry build.
+   */
+  private async loadVolumeSkills(): Promise<SkillDefinition[]> {
+    const volume = this.resolveSkillsVolume();
+    if (!volume) return [];
+
+    if ((this.config.skillCredentialMode ?? "sp") === "obo") {
+      logger.warn(
+        "skillCredentialMode 'obo' is not wired yet; reading catalog skills as the service principal.",
+      );
+    }
+
+    let client: WorkspaceClient;
+    try {
+      client = this.skillWorkspaceClient();
+    } catch (err) {
+      logger.warn(
+        "Skipping catalog skills at '%s': no workspace client available (%s).",
+        volume,
+        err instanceof Error ? err.message : String(err),
+      );
+      return [];
+    }
+
+    const connector = new FilesConnector({ defaultVolume: volume });
+    let entries: Awaited<ReturnType<FilesConnector["list"]>>;
+    try {
+      entries = await connector.list(client, volume);
+    } catch (err) {
+      logger.warn(
+        "Failed to list catalog skills volume '%s': %s",
+        volume,
+        err instanceof Error ? err.message : String(err),
+      );
+      return [];
+    }
+
+    const skills: SkillDefinition[] = [];
+    for (const entry of entries) {
+      if (!entry.is_directory || !entry.name || !entry.path) continue;
+      const skillDir = entry.path;
+      const skillFile = `${skillDir}/SKILL.md`;
+      try {
+        const raw = await connector.read(client, skillFile);
+        const parsed = parseSkill(raw, skillFile);
+        const files = await this.listVolumeSkillFiles(
+          connector,
+          client,
+          skillDir,
+        );
+        skills.push({
+          name: parsed.name,
+          description: parsed.description,
+          body: parsed.body,
+          source: "volume",
+          dir: skillDir,
+          files,
+          allowedTools: parsed.allowedTools,
+        });
+      } catch (err) {
+        logger.warn(
+          "Skipping catalog skill '%s': %s",
+          skillDir,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    }
+    return skills;
+  }
+
+  /** Lists a volume skill's resource files (one level, excluding SKILL.md). */
+  private async listVolumeSkillFiles(
+    connector: FilesConnector,
+    client: WorkspaceClient,
+    skillDir: string,
+  ): Promise<string[]> {
+    try {
+      const entries = await connector.list(client, skillDir);
+      return entries
+        .filter((e) => !e.is_directory && e.name && e.name !== "SKILL.md")
+        .map((e) => e.name as string)
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Resolves the per-agent skill catalog: loads this agent's private skills
+   * (`<agentsDir>/<id>/skills/`, file-origin only), then applies visibility
+   * (opt-in via `def.skills` or `autoInheritSkills`) and collision rules
+   * against the shared global pool. Returns `undefined` when nothing is
+   * visible so the prompt catalog and dispatch can cheaply skip skills.
+   */
+  private async resolveAgentSkills(
+    name: string,
+    def: AgentDefinition,
+    src: AgentSource,
+  ): Promise<RegisteredAgent["skills"]> {
+    const dir = this.resolvedAgentsDir();
+    const perAgentSkills =
+      src.origin === "file" && dir
+        ? await loadSkillsFromDir(
+            path.join(dir, name, "skills"),
+            "bundle-agent",
+          )
+        : [];
+
+    const inherit = normalizeAutoInherit(this.config.autoInheritSkills);
+    const autoInherit = src.origin === "file" ? inherit.file : inherit.code;
+
+    const catalog = resolveSkillCatalog({
+      agentName: name,
+      agentSkillNames: def.skills,
+      perAgentSkills,
+      globalSkills: this.globalSkills,
+      autoInherit,
+    });
+
+    return catalog.byAddress.size > 0 ? catalog : undefined;
+  }
+
   private async resolveAdapter(
     def: AgentDefinition,
     name: string,
@@ -691,6 +873,7 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
     agentName: string,
     def: AgentDefinition,
     src: AgentSource,
+    skills?: ResolvedSkillCatalog,
   ): Promise<Map<string, ResolvedToolEntry>> {
     const index = new Map<string, ResolvedToolEntry>();
     const hasDeclaredTools = def.tools !== undefined;
@@ -785,6 +968,23 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
       await this.connectHostedTools(hostedToCollect, index);
     }
 
+    // 3. Built-in skill tools, present only when this agent has a visible
+    //    catalog. Injected last so they reliably shadow any same-named tool.
+    if (skills && skills.byAddress.size > 0) {
+      index.set("load_skill", {
+        source: "skill",
+        builtin: "load_skill",
+        catalog: skills,
+        def: LOAD_SKILL_TOOL_DEF,
+      });
+      index.set("read_skill_file", {
+        source: "skill",
+        builtin: "read_skill_file",
+        catalog: skills,
+        def: READ_SKILL_FILE_TOOL_DEF,
+      });
+    }
+
     return index;
   }
 
@@ -1045,9 +1245,17 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
   }
 
   clientConfig(): Record<string, unknown> {
+    // Per-agent skill catalog (name + description) so the client can offer a
+    // `/skill-name` autocomplete / picker. Only agents with a visible catalog
+    // appear here.
+    const skills: Record<string, { name: string; description: string }[]> = {};
+    for (const [name, agent] of this.agents) {
+      if (agent.skills) skills[name] = agent.skills.catalog;
+    }
     return {
       agents: Array.from(this.agents.keys()),
       defaultAgent: this.defaultAgentName,
+      skills,
     };
   }
 
@@ -1060,7 +1268,13 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
       });
       return;
     }
-    const { message, threadId, agent: agentName, mlflowRunId } = parsed.data;
+    const {
+      message,
+      threadId,
+      agent: agentName,
+      mlflowRunId,
+      skill,
+    } = parsed.data;
 
     const registered = this.resolveAgent(agentName);
     if (!registered) {
@@ -1114,7 +1328,15 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
       res.status(500).json({ error: "Thread operation failed" });
       return;
     }
-    return this._streamAgent(req, res, registered, thread, userId, mlflowRunId);
+    return this._streamAgent(
+      req,
+      res,
+      registered,
+      thread,
+      userId,
+      mlflowRunId,
+      skill,
+    );
   }
 
   /**
@@ -1249,6 +1471,7 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
     thread: Thread,
     userId: string,
     mlflowRunId?: string,
+    forcedSkill?: string,
   ): Promise<void> {
     const abortController = new AbortController();
     const signal = abortController.signal;
@@ -1320,7 +1543,7 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
                   .getPluginNames()
                   .filter((n) => n !== this.name && n !== "server")
               : [];
-            const fullPrompt = composePromptForAgent(
+            let fullPrompt = composePromptForAgent(
               registered,
               this.config.baseSystemPrompt,
               {
@@ -1330,6 +1553,15 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
               },
             );
 
+            // Deterministic `/skill-name` invocation: eagerly inject the
+            // requested skill's instructions into this turn rather than waiting
+            // for the model to call load_skill. The tool stays available for
+            // the model to auto-select others.
+            if (forcedSkill) {
+              const addendum = this.renderForcedSkill(registered, forcedSkill);
+              if (addendum) fullPrompt = `${fullPrompt}\n\n${addendum}`;
+            }
+
             const messagesWithSystem: Message[] = [
               {
                 id: "system",
@@ -1740,6 +1972,8 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
           `Tool '${name}' is a hosted-supervisor tool and cannot be invoked from the Node process. ` +
             "It is executed server-side by the Databricks AI Gateway and is only reachable when the agent's model is a Supervisor API adapter.",
         );
+      } else if (entry.source === "skill") {
+        result = await this.dispatchSkillTool(entry, args);
       }
 
       return result;
@@ -1748,6 +1982,81 @@ export class AgentsPlugin extends Plugin implements ToolProvider {
     return normalizeToolResult(toolResult);
   }
 
+  /**
+   * Executes the built-in `load_skill` / `read_skill_file` tools against the
+   * agent's resolved skill catalog. `load_skill` returns a skill's body plus a
+   * manifest of bundled files; `read_skill_file` returns the contents of one
+   * of those files (bundle skills only in v1 — catalog-volume resource reads
+   * arrive with the volume source).
+   */
+  private async dispatchSkillTool(
+    entry: Extract<ResolvedToolEntry, { source: "skill" }>,
+    args: unknown,
+  ): Promise<string> {
+    const obj =
+      typeof args === "object" && args !== null
+        ? (args as Record<string, unknown>)
+        : {};
+    const skillName = typeof obj.skill === "string" ? obj.skill.trim() : "";
+    if (!skillName) {
+      throw new Error(
+        `'${entry.builtin}' requires a 'skill' argument naming the skill to use.`,
+      );
+    }
+
+    const skill = resolveSkill(entry.catalog, skillName);
+
+    if (entry.builtin === "load_skill") {
+      return renderLoadedSkill(skill);
+    }
+
+    // read_skill_file
+    const filePath = typeof obj.path === "string" ? obj.path.trim() : "";
+    if (!filePath) {
+      throw new Error("'read_skill_file' requires a 'path' argument.");
+    }
+    if (!skill.files.includes(filePath)) {
+      throw new Error(
+        `Skill '${skill.name}' has no bundled file '${filePath}'. Available: ${
+          skill.files.join(", ") || "<none>"
+        }.`,
+      );
+    }
+
+    if (skill.source === "volume") {
+      const connector = new FilesConnector({ defaultVolume: skill.dir });
+      return connector.read(
+        this.skillWorkspaceClient(),
+        `${skill.dir}/${filePath}`,
+      );
+    }
+    return readSkillResource(skill.dir, filePath);
+  }
+
+  /**
+   * Renders the prompt addendum for a force-loaded skill (`/skill-name`).
+   * Returns null when the agent has no catalog or the name doesn't resolve —
+   * an unusable request shouldn't fail the whole turn, so it's logged and the
+   * model proceeds with the catalog + `load_skill` still available.
+   */
+  private renderForcedSkill(
+    registered: RegisteredAgent,
+    name: string,
+  ): string | null {
+    if (!registered.skills) return null;
+    try {
+      const skill = resolveSkill(registered.skills, name);
+      return `The user explicitly requested the "${skill.name}" skill for this turn. Its instructions:\n\n${renderLoadedSkill(skill)}`;
+    } catch (err) {
+      logger.warn(
+        "Ignoring forced skill '%s': %s",
+        name,
+        err instanceof Error ? err.message : String(err),
+      );
+      return null;
+    }
+  }
+
   /**
    * Runs a sub-agent in response to an `agent-<key>` tool call. Returns the
    * concatenated text output to hand back to the parent adapter as the tool
@@ -2028,6 +2337,45 @@ function normalizeAutoInherit(value: AgentsPluginConfig["autoInheritTools"]): {
   return { file: value.file ?? false, code: value.code ?? false };
 }
 
+/** Built-in tool the model calls to load a skill's full instructions on demand. */
+const LOAD_SKILL_TOOL_DEF: AgentToolDefinition = {
+  name: "load_skill",
+  description:
+    "Load the full instructions for one of the available skills by name. Call this before acting on a task that matches a skill's description. Returns the skill's instructions plus a list of any bundled files you can read with read_skill_file.",
+  parameters: {
+    type: "object",
+    properties: {
+      skill: {
+        type: "string",
+        description:
+          "The exact skill name to load, as shown in the available-skills list.",
+      },
+    },
+    required: ["skill"],
+  },
+  annotations: { effect: "read" },
+};
+
+/** Built-in tool for reading a resource file that a loaded skill references. */
+const READ_SKILL_FILE_TOOL_DEF: AgentToolDefinition = {
+  name: "read_skill_file",
+  description:
+    "Read a bundled resource file that a loaded skill references (e.g. a reference doc). Only files listed by load_skill for that skill are readable.",
+  parameters: {
+    type: "object",
+    properties: {
+      skill: { type: "string", description: "The skill that owns the file." },
+      path: {
+        type: "string",
+        description:
+          "Relative path of the file within the skill, as listed by load_skill.",
+      },
+    },
+    required: ["skill", "path"],
+  },
+  annotations: { effect: "read" },
+};
+
 function composePromptForAgent(
   registered: RegisteredAgent,
   pluginLevel: BaseSystemPromptOption | undefined,
@@ -2047,7 +2395,13 @@ function composePromptForAgent(
     base = buildBaseSystemPrompt(ctx);
   }
 
-  return composeSystemPrompt(base, registered.instructions);
+  const composed = composeSystemPrompt(base, registered.instructions);
+
+  // Append the always-on skill catalog (name + description only). Done here,
+  // after composeSystemPrompt, so it survives a custom/`false` base prompt.
+  const catalog = registered.skills?.catalog;
+  if (!catalog || catalog.length === 0) return composed;
+  return `${composed}\n\n${renderSkillCatalog(catalog)}`;
 }
 
 /**
diff --git a/packages/appkit/src/plugins/agents/manifest.json b/packages/appkit/src/plugins/agents/manifest.json
index 4d6f52485..529c640bc 100644
--- a/packages/appkit/src/plugins/agents/manifest.json
+++ b/packages/appkit/src/plugins/agents/manifest.json
@@ -32,6 +32,24 @@
             "description": "MLflow experiment id traces are logged to"
           }
         }
+      },
+      {
+        "type": "volume",
+        "alias": "Agent skills",
+        "resourceKey": "agents-skills",
+        "description": "Optional Unity Catalog Volume providing catalog-sourced agent skills (read-only)",
+        "permission": "READ_VOLUME",
+        "fields": {
+          "path": {
+            "env": "DATABRICKS_VOLUME_AGENT_SKILLS",
+            "description": "Volume path for agent skills (e.g. /Volumes/catalog/schema/skills)",
+            "discovery": {
+              "type": "kind",
+              "resourceKind": "volume",
+              "select": "full_name"
+            }
+          }
+        }
       }
     ]
   }
diff --git a/packages/appkit/src/plugins/agents/schemas.ts b/packages/appkit/src/plugins/agents/schemas.ts
index 6dc5040cb..24e38f1d5 100644
--- a/packages/appkit/src/plugins/agents/schemas.ts
+++ b/packages/appkit/src/plugins/agents/schemas.ts
@@ -40,6 +40,12 @@ export const chatRequestSchema = z.object({
    * to a run-id-shaped length since it reaches trace metadata and logs.
    */
   mlflowRunId: z.string().max(64).optional(),
+  /**
+   * Optional skill to force-load for this turn (deterministic `/skill-name`
+   * invocation). Its instructions are injected into the turn's context; the
+   * model can still auto-load others via the `load_skill` tool.
+   */
+  skill: z.string().optional(),
 });
 
 const messageItemSchema = z.object({
diff --git a/packages/appkit/src/plugins/agents/tests/dispatch-tool-call.test.ts b/packages/appkit/src/plugins/agents/tests/dispatch-tool-call.test.ts
index f700379f4..d503fea6f 100644
--- a/packages/appkit/src/plugins/agents/tests/dispatch-tool-call.test.ts
+++ b/packages/appkit/src/plugins/agents/tests/dispatch-tool-call.test.ts
@@ -1,7 +1,13 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
 import type express from "express";
-import { beforeEach, describe, expect, test, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import { CacheManager } from "../../../cache";
+import { resolveSkillCatalog } from "../../../core/agent/skills/resolve-catalog";
+import type { SkillDefinition } from "../../../core/agent/skills/types";
 import { createTestPluginContext } from "../../../testing";
 import { AgentsPlugin } from "../agents";
 
@@ -458,3 +464,152 @@ describe("runSubAgent — sub-agent event forwarding", () => {
     expect(types).toContain("message_delta");
   });
 });
+
+describe("dispatchToolCall — skill built-ins", () => {
+  let skillDir = "";
+
+  afterEach(() => {
+    if (skillDir) {
+      fs.rmSync(skillDir, { recursive: true, force: true });
+      skillDir = "";
+    }
+  });
+
+  function skillCatalog(skills: SkillDefinition[]) {
+    return resolveSkillCatalog({
+      agentName: "a",
+      perAgentSkills: skills,
+      globalSkills: [],
+      autoInherit: false,
+    });
+  }
+
+  function skillToolIndex(
+    catalog: ReturnType<typeof skillCatalog>,
+  ): Map<string, unknown> {
+    const readOnly = { effect: "read" as const };
+    return new Map<string, unknown>([
+      [
+        "load_skill",
+        {
+          source: "skill",
+          builtin: "load_skill",
+          catalog,
+          def: {
+            name: "load_skill",
+            description: "load",
+            parameters: { type: "object" },
+            annotations: readOnly,
+          },
+        },
+      ],
+      [
+        "read_skill_file",
+        {
+          source: "skill",
+          builtin: "read_skill_file",
+          catalog,
+          def: {
+            name: "read_skill_file",
+            description: "read",
+            parameters: { type: "object" },
+            annotations: readOnly,
+          },
+        },
+      ],
+    ]);
+  }
+
+  test("load_skill returns the skill body + manifest and skips the gate", async () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    const { runState } = makeRunState(plugin);
+    const catalog = skillCatalog([
+      {
+        name: "pdf",
+        description: "d",
+        body: "Detailed PDF steps.",
+        source: "bundle-agent",
+        dir: "/fake/pdf",
+        files: ["reference.md"],
+      },
+    ]);
+    // biome-ignore lint/suspicious/noExplicitAny: stub gate to assert it never fires
+    (plugin as any).approvalGate.wait = vi.fn();
+
+    const result = await callDispatch(plugin, {
+      runState,
+      toolIndex: skillToolIndex(catalog),
+      name: "load_skill",
+      args: { skill: "pdf" },
+    });
+
+    expect(String(result)).toContain("Detailed PDF steps.");
+    expect(String(result)).toContain("reference.md");
+    // biome-ignore lint/suspicious/noExplicitAny: assertion on stub
+    expect((plugin as any).approvalGate.wait).not.toHaveBeenCalled();
+  });
+
+  test("load_skill errors on an unknown skill name", async () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    const { runState } = makeRunState(plugin);
+    const catalog = skillCatalog([
+      {
+        name: "pdf",
+        description: "d",
+        body: "b",
+        source: "bundle-agent",
+        dir: "/fake/pdf",
+        files: [],
+      },
+    ]);
+
+    await expect(
+      callDispatch(plugin, {
+        runState,
+        toolIndex: skillToolIndex(catalog),
+        name: "load_skill",
+        args: { skill: "ghost" },
+      }),
+    ).rejects.toThrow(/Unknown skill/);
+  });
+
+  test("read_skill_file reads a listed file and rejects an unlisted path", async () => {
+    skillDir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-dispatch-"));
+    fs.writeFileSync(
+      path.join(skillDir, "reference.md"),
+      "the reference",
+      "utf-8",
+    );
+    const plugin = new AgentsPlugin({ dir: false });
+    const { runState } = makeRunState(plugin);
+    const catalog = skillCatalog([
+      {
+        name: "pdf",
+        description: "d",
+        body: "b",
+        source: "bundle-agent",
+        dir: skillDir,
+        files: ["reference.md"],
+      },
+    ]);
+    const toolIndex = skillToolIndex(catalog);
+
+    await expect(
+      callDispatch(plugin, {
+        runState,
+        toolIndex,
+        name: "read_skill_file",
+        args: { skill: "pdf", path: "reference.md" },
+      }),
+    ).resolves.toContain("the reference");
+
+    await expect(
+      callDispatch(plugin, {
+        runState,
+        toolIndex,
+        name: "read_skill_file",
+        args: { skill: "pdf", path: "../secret" },
+      }),
+    ).rejects.toThrow();
+  });
+});
diff --git a/packages/appkit/src/plugins/agents/tests/skill-client.test.ts b/packages/appkit/src/plugins/agents/tests/skill-client.test.ts
new file mode 100644
index 000000000..0a814f153
--- /dev/null
+++ b/packages/appkit/src/plugins/agents/tests/skill-client.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, test, vi } from "vitest";
+
+import type { SkillDefinition } from "../../../core/agent/skills";
+import { resolveSkillCatalog } from "../../../core/agent/skills";
+import { AgentsPlugin } from "../agents";
+
+/**
+ * Phase 4 — the server surfaces the skill catalog to the client via
+ * `clientConfig()`, and force-loads a skill for a turn via `renderForcedSkill`
+ * (the deterministic `/skill-name` path). Both are pure and don't touch a
+ * workspace, so no mocks are needed.
+ */
+
+function skill(
+  name: string,
+  overrides: Partial<SkillDefinition> = {},
+): SkillDefinition {
+  return {
+    name,
+    description: `${name} description`,
+    body: `${name} body`,
+    source: "bundle-agent",
+    dir: `/fake/${name}`,
+    files: [],
+    ...overrides,
+  };
+}
+
+function catalogOf(...skills: SkillDefinition[]) {
+  return resolveSkillCatalog({
+    agentName: "a",
+    perAgentSkills: skills,
+    globalSkills: [],
+    autoInherit: false,
+  });
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: minimal RegisteredAgent stub
+function registeredWith(catalog?: ReturnType<typeof catalogOf>): any {
+  return {
+    name: "a",
+    instructions: "",
+    adapter: {},
+    toolIndex: new Map(),
+    ...(catalog ? { skills: catalog } : {}),
+  };
+}
+
+describe("skills are wired uniformly for every registered agent", () => {
+  // Sub-agents are ordinary registered agents resolved through
+  // buildRegisteredAgent, so opting one into a skill gives it the same
+  // catalog + load_skill/read_skill_file tools as a top-level agent.
+  test("buildRegisteredAgent gives a code agent its catalog and skill tools", async () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    // biome-ignore lint/suspicious/noExplicitAny: seed the shared pool
+    (plugin as any).globalSkills = [skill("x", { description: "X skill" })];
+
+    // biome-ignore lint/suspicious/noExplicitAny: call private with a stub adapter
+    const registered = await (plugin as any).buildRegisteredAgent(
+      "child",
+      {
+        instructions: "hi",
+        model: {
+          run: async function* () {},
+          acceptsExtensions: [],
+          consumesInputTools: false,
+        },
+        skills: ["x"],
+      },
+      { origin: "code" },
+    );
+
+    expect(registered.skills?.byAddress.has("x")).toBe(true);
+    expect(registered.toolIndex.has("load_skill")).toBe(true);
+    expect(registered.toolIndex.has("read_skill_file")).toBe(true);
+  });
+
+  test("an agent with no visible skills gets no skill tools", async () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    // biome-ignore lint/suspicious/noExplicitAny: call private with a stub adapter
+    const registered = await (plugin as any).buildRegisteredAgent(
+      "bare",
+      { instructions: "hi", model: { run: async function* () {} } },
+      { origin: "code" },
+    );
+    expect(registered.skills).toBeUndefined();
+    expect(registered.toolIndex.has("load_skill")).toBe(false);
+  });
+});
+
+describe("clientConfig — skills", () => {
+  test("exposes each agent's skill catalog keyed by agent name", () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    // biome-ignore lint/suspicious/noExplicitAny: seed private registry
+    (plugin as any).agents = new Map([
+      [
+        "helper",
+        registeredWith(catalogOf(skill("pdf", { description: "PDFs" }))),
+      ],
+    ]);
+    // biome-ignore lint/suspicious/noExplicitAny: seed private field
+    (plugin as any).defaultAgentName = "helper";
+
+    const cfg = plugin.clientConfig();
+    expect(cfg.agents).toEqual(["helper"]);
+    expect(cfg.skills).toEqual({
+      helper: [{ name: "pdf", description: "PDFs" }],
+    });
+  });
+
+  test("omits agents that have no visible catalog", () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    // biome-ignore lint/suspicious/noExplicitAny: seed private registry
+    (plugin as any).agents = new Map([["bare", registeredWith()]]);
+    expect(plugin.clientConfig().skills).toEqual({});
+  });
+});
+
+describe("renderForcedSkill", () => {
+  test("renders the resolved skill body with a request note", () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    const registered = registeredWith(
+      catalogOf(skill("pdf", { body: "PDF steps." })),
+    );
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    const out = (plugin as any).renderForcedSkill(registered, "pdf");
+    expect(out).toContain("PDF steps.");
+    expect(out).toContain("explicitly requested");
+  });
+
+  test("returns null for an unknown forced skill", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const plugin = new AgentsPlugin({ dir: false });
+    const registered = registeredWith(catalogOf(skill("pdf")));
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    expect((plugin as any).renderForcedSkill(registered, "ghost")).toBeNull();
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  test("returns null when the agent has no catalog", () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    expect(
+      (plugin as any).renderForcedSkill(registeredWith(), "pdf"),
+    ).toBeNull();
+  });
+});
diff --git a/packages/appkit/src/plugins/agents/tests/skill-volume.test.ts b/packages/appkit/src/plugins/agents/tests/skill-volume.test.ts
new file mode 100644
index 000000000..5e33bf168
--- /dev/null
+++ b/packages/appkit/src/plugins/agents/tests/skill-volume.test.ts
@@ -0,0 +1,154 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { resolveSkillCatalog } from "../../../core/agent/skills";
+
+/**
+ * Phase 3 — catalog (UC Volume) skill source. The workspace client and the
+ * files connector are mocked so the test never touches Databricks: the mock
+ * connector serves a synthetic `<volume>/pdf/SKILL.md` + `reference.md`.
+ */
+
+const h = vi.hoisted(() => ({
+  list: vi.fn(),
+  read: vi.fn(),
+  client: { marker: "sp-client" } as unknown,
+}));
+
+vi.mock("../../../context", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../../context")>();
+  return { ...actual, getWorkspaceClient: () => h.client };
+});
+
+vi.mock("../../../connectors/files", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("../../../connectors/files")>();
+  return {
+    ...actual,
+    FilesConnector: class {
+      constructor(public config: { defaultVolume?: string }) {}
+      list(client: unknown, dir?: string) {
+        return h.list(client, dir);
+      }
+      read(client: unknown, filePath: string) {
+        return h.read(client, filePath);
+      }
+    },
+  };
+});
+
+// Imported after the mocks are registered.
+const { AgentsPlugin } = await import("../agents");
+
+const VOL = "/Volumes/cat/schema/skills";
+
+beforeEach(() => {
+  process.env.DATABRICKS_VOLUME_AGENT_SKILLS = undefined;
+  delete process.env.DATABRICKS_VOLUME_AGENT_SKILLS;
+
+  h.list.mockImplementation(async (_client: unknown, dir?: string) => {
+    if (dir === VOL) {
+      return [{ name: "pdf", is_directory: true, path: `${VOL}/pdf` }];
+    }
+    if (dir === `${VOL}/pdf`) {
+      return [
+        { name: "SKILL.md", is_directory: false, path: `${VOL}/pdf/SKILL.md` },
+        {
+          name: "reference.md",
+          is_directory: false,
+          path: `${VOL}/pdf/reference.md`,
+        },
+      ];
+    }
+    return [];
+  });
+  h.read.mockImplementation(async (_client: unknown, filePath: string) => {
+    if (filePath === `${VOL}/pdf/SKILL.md`) {
+      return "---\nname: pdf\ndescription: Work with PDFs\n---\nPDF body.";
+    }
+    if (filePath === `${VOL}/pdf/reference.md`) {
+      return "the reference";
+    }
+    throw new Error(`unexpected read: ${filePath}`);
+  });
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("loadVolumeSkills", () => {
+  test("discovers, parses, and manifests a volume skill (SP identity)", async () => {
+    const plugin = new AgentsPlugin({ dir: false, skillsVolume: VOL });
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    const skills = await (plugin as any).loadVolumeSkills();
+
+    expect(skills).toHaveLength(1);
+    expect(skills[0]).toMatchObject({
+      name: "pdf",
+      description: "Work with PDFs",
+      body: "PDF body.",
+      source: "volume",
+      dir: `${VOL}/pdf`,
+      files: ["reference.md"],
+    });
+    // Read as the SP client the mock hands back.
+    expect(h.read).toHaveBeenCalledWith(h.client, `${VOL}/pdf/SKILL.md`);
+  });
+
+  test("returns [] when no volume is configured", async () => {
+    const plugin = new AgentsPlugin({ dir: false });
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    const skills = await (plugin as any).loadVolumeSkills();
+    expect(skills).toEqual([]);
+    expect(h.list).not.toHaveBeenCalled();
+  });
+});
+
+describe("catalog resolution merges volume skills", () => {
+  test("a code agent opts into a volume skill via skills:", async () => {
+    const plugin = new AgentsPlugin({ dir: false, skillsVolume: VOL });
+    // biome-ignore lint/suspicious/noExplicitAny: seed the global pool + call private
+    (plugin as any).globalSkills = await (plugin as any).loadVolumeSkills();
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    const catalog = await (plugin as any).resolveAgentSkills(
+      "helper",
+      { instructions: "hi", skills: ["pdf"] },
+      { origin: "code" },
+    );
+    expect(catalog?.byAddress.has("pdf")).toBe(true);
+  });
+});
+
+describe("read_skill_file reads a volume resource", () => {
+  test("reads the file through the connector under SP identity", async () => {
+    const plugin = new AgentsPlugin({ dir: false, skillsVolume: VOL });
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    const skills = await (plugin as any).loadVolumeSkills();
+    const catalog = resolveSkillCatalog({
+      agentName: "a",
+      perAgentSkills: [],
+      globalSkills: skills,
+      autoInherit: true,
+    });
+    const entry = {
+      source: "skill" as const,
+      builtin: "read_skill_file" as const,
+      catalog,
+      def: {
+        name: "read_skill_file",
+        description: "read",
+        parameters: { type: "object" },
+        annotations: { effect: "read" as const },
+      },
+    };
+
+    // biome-ignore lint/suspicious/noExplicitAny: call private
+    const result = await (plugin as any).dispatchSkillTool(entry, {
+      skill: "pdf",
+      path: "reference.md",
+    });
+
+    expect(result).toBe("the reference");
+    expect(h.read).toHaveBeenCalledWith(h.client, `${VOL}/pdf/reference.md`);
+  });
+});
diff --git a/template/appkit.plugins.json b/template/appkit.plugins.json
index 503ee7983..85fcbb8f2 100644
--- a/template/appkit.plugins.json
+++ b/template/appkit.plugins.json
@@ -37,6 +37,25 @@
                 "origin": "user"
               }
             }
+          },
+          {
+            "type": "volume",
+            "alias": "Agent skills",
+            "resourceKey": "agents-skills",
+            "description": "Optional Unity Catalog Volume providing catalog-sourced agent skills (read-only)",
+            "permission": "READ_VOLUME",
+            "fields": {
+              "path": {
+                "env": "DATABRICKS_VOLUME_AGENT_SKILLS",
+                "description": "Volume path for agent skills (e.g. /Volumes/catalog/schema/skills)",
+                "discovery": {
+                  "type": "kind",
+                  "resourceKind": "volume",
+                  "select": "full_name"
+                },
+                "origin": "user"
+              }
+            }
           }
         ]
       },
diff --git a/template/client/src/pages/agents/AgentChat.tsx b/template/client/src/pages/agents/AgentChat.tsx
index 115230197..c6739e3c0 100644
--- a/template/client/src/pages/agents/AgentChat.tsx
+++ b/template/client/src/pages/agents/AgentChat.tsx
@@ -26,6 +26,8 @@ interface Message {
 interface AgentsClientConfig {
   agents: string[];
   defaultAgent: string | null;
+  /** Per-agent skill catalog (name + description) for the `/skill` picker. */
+  skills?: Record<string, { name: string; description: string }[]>;
 }
 
 /**
@@ -53,9 +55,11 @@ export function AgentChat() {
   // Agent registry comes from the agents plugin's `clientConfig()` payload
   // (boot-time, no fetch). `defaultAgent` is null only when no agents are
   // registered; both `planner` and `helper` are registered here.
-  const { agents, defaultAgent } =
+  const { agents, defaultAgent, skills } =
     usePluginClientConfig<AgentsClientConfig>('agents');
   const activeAgent = defaultAgent ?? agents[0] ?? null;
+  // Skills visible to the active agent, if any — drives the `/skill` picker.
+  const activeSkills = (activeAgent && skills?.[activeAgent]) || [];
   const [messages, setMessages] = useState<Message[]>([]);
   const [input, setInput] = useState('');
   const [pendingAssistantId, setPendingAssistantId] = useState<string | null>(
@@ -187,6 +191,28 @@ export function AgentChat() {
         </CardContent>
 
         <form onSubmit={handleSubmit} className="p-3 border-t flex gap-2">
+          {activeSkills.length > 0 && (
+            <select
+              className="text-sm border rounded-md px-2 bg-background text-foreground shrink-0"
+              value=""
+              disabled={isStreaming}
+              aria-label="Load a skill"
+              onChange={(e) => {
+                const name = e.target.value;
+                if (!name) return;
+                // Prepend `/skill-name` sugar; useAgentChat parses it off.
+                setInput((v) => `/${name} ${v.replace(/^\/\S+\s*/, '')}`);
+                e.currentTarget.value = '';
+              }}
+            >
+              <option value="">+ skill</option>
+              {activeSkills.map((s) => (
+                <option key={s.name} value={s.name} title={s.description}>
+                  {s.name}
+                </option>
+              ))}
+            </select>
+          )}
           <Input
             value={input}
             onChange={(e) => setInput(e.target.value)}
diff --git a/template/server/agents/planner/agent.md b/template/server/agents/planner/agent.md
index b6e6f9137..0c3815eaa 100644
--- a/template/server/agents/planner/agent.md
+++ b/template/server/agents/planner/agent.md
@@ -3,6 +3,8 @@
 default: true
 agents:
   - helper
+skills:
+  - tracer-bullets
 ---
 
 You are a planning partner for the developer running this Databricks
@@ -20,7 +22,9 @@ When the user describes something they want to build or change:
 3. Once the open questions are settled, propose a small, ordered plan
    (typically three to six steps). Each step should be concrete enough
    that a developer could open the file and start. Call out risks and
-   reversible-vs-irreversible decisions.
+   reversible-vs-irreversible decisions. When the user wants a feature
+   broken into steps, load the `tracer-bullets` skill first and follow
+   its slicing method.
 4. If the user asks for an opinion, give one — briefly, with the
    reasoning. If you don't have enough context, say so and ask the one
    question that would let you answer.
diff --git a/template/server/agents/skills/tracer-bullets/SKILL.md b/template/server/agents/skills/tracer-bullets/SKILL.md
new file mode 100644
index 000000000..facdb5d63
--- /dev/null
+++ b/template/server/agents/skills/tracer-bullets/SKILL.md
@@ -0,0 +1,29 @@
+{{if .plugins.agents -}}
+---
+name: tracer-bullets
+description: Slice a feature into thin end-to-end "tracer bullet" increments — each one shippable, demoable, and touching every layer — instead of building horizontal layers that only connect at the end.
+---
+
+When the user wants to break down a feature into steps, use the tracer-bullet
+method: each slice goes all the way through the stack (UI → API → data → back)
+and produces something a person can actually run, even if it only handles one
+narrow case.
+
+How to apply it in a planning conversation:
+
+1. Name the thinnest path that produces a visible result end-to-end. Ignore
+   edge cases, config, and polish. This is slice 1 — it should feel almost
+   embarrassingly small.
+2. Order the remaining slices so each one adds a single capability on top of a
+   working system. Every slice ends with "you can now do X" — never "the
+   database layer is done."
+3. For each slice, name its demo: the one action that proves it works.
+4. Call out which slices are reversible vs. hard to undo, and put the
+   irreversible ones as late as the plan allows.
+
+See `reference.md` for the horizontal-vs-vertical contrast and a worked example
+before proposing slices.
+
+Keep the plan to three to six slices. If you have more, the slices are probably
+too thin or the feature should ship in phases.
+{{- end}}
diff --git a/template/server/agents/skills/tracer-bullets/reference.md b/template/server/agents/skills/tracer-bullets/reference.md
new file mode 100644
index 000000000..4ed4da5f6
--- /dev/null
+++ b/template/server/agents/skills/tracer-bullets/reference.md
@@ -0,0 +1,28 @@
+{{if .plugins.agents -}}
+# Tracer bullets: reference
+
+## Horizontal vs. vertical
+
+**Horizontal (avoid):** build all of one layer before the next — the whole
+data model, then the whole API, then the whole UI. Nothing runs end-to-end
+until the last layer lands, so integration risk is discovered last and there's
+nothing to demo for weeks.
+
+**Vertical / tracer bullet (prefer):** build a thin path through every layer at
+once. It handles one case, but it *runs*. Each later slice widens it.
+
+## Worked example — "users can export a report"
+
+1. **Slice 1 — one hardcoded row, real download.** A button calls a new
+   endpoint that returns a CSV with a single hardcoded row. Demo: click the
+   button, a file downloads.
+2. **Slice 2 — real data, one format.** Wire the endpoint to the actual query.
+   Demo: the CSV now reflects the live table.
+3. **Slice 3 — the user's filters.** Pass the screen's active filters into the
+   query. Demo: filtered view exports filtered data.
+4. **Slice 4 — second format + empty state.** Add XLSX and a friendly message
+   when there are zero rows. Demo: toggle format; export an empty result.
+
+Each slice ships. If slice 1 can't be demoed by a person, it isn't thin
+enough yet — cut it further.
+{{- end}}

From 24ba909c51919b58feb4efae00bbc6dfaae0b028 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Wed, 19 Aug 2026 16:55:39 +0200
Subject: [PATCH 2/4] test(playground): add per-agent, collision, and
 multi-global skill fixtures

Exercise the previously-untested skill sources/paths in the reference app:

- global `bullet-brief` skill; helper opts into it (multi-entry menu on a code agent)
- per-agent `query/skills/routing-brief` (bundle-agent source + bundled reference.md)
- per-agent `query/skills/haiku` collides with global `haiku` (query opts in),
  forcing qualified agent:haiku / bundle:haiku addressing
- add `query` to the /agent page picker so its skills surface in the input

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 .../client/src/routes/agent.route.tsx           |  4 ++++
 .../server/agents/helper/agent.ts               |  9 +++++----
 .../dev-playground/server/agents/query/agent.md |  5 +++++
 .../server/agents/query/skills/haiku/SKILL.md   | 10 ++++++++++
 .../agents/query/skills/routing-brief/SKILL.md  | 17 +++++++++++++++++
 .../query/skills/routing-brief/reference.md     | 16 ++++++++++++++++
 .../server/agents/skills/bullet-brief/SKILL.md  | 12 ++++++++++++
 7 files changed, 69 insertions(+), 4 deletions(-)
 create mode 100644 apps/dev-playground/server/agents/query/skills/haiku/SKILL.md
 create mode 100644 apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md
 create mode 100644 apps/dev-playground/server/agents/query/skills/routing-brief/reference.md
 create mode 100644 apps/dev-playground/server/agents/skills/bullet-brief/SKILL.md

diff --git a/apps/dev-playground/client/src/routes/agent.route.tsx b/apps/dev-playground/client/src/routes/agent.route.tsx
index 01493539b..d32651a64 100644
--- a/apps/dev-playground/client/src/routes/agent.route.tsx
+++ b/apps/dev-playground/client/src/routes/agent.route.tsx
@@ -18,6 +18,10 @@ const AGENT_OPTIONS = [
   { value: "helper", label: "Helper — general assistant" },
   { value: "sql_analyst", label: "SQL Analyst — NYC taxi queries" },
   { value: "supervisor", label: "Supervisor — Databricks-hosted tools" },
+  {
+    value: "query",
+    label: "Query — dispatcher (per-agent + collision skills)",
+  },
 ] as const;
 
 interface SSEEvent {
diff --git a/apps/dev-playground/server/agents/helper/agent.ts b/apps/dev-playground/server/agents/helper/agent.ts
index 9ff11e7a0..693cd0f24 100644
--- a/apps/dev-playground/server/agents/helper/agent.ts
+++ b/apps/dev-playground/server/agents/helper/agent.ts
@@ -8,10 +8,11 @@ export default createAgent({
   instructions:
     "You are a demo helper. Use analytics tools to answer data questions, " +
     "or get_weather for light small-talk.",
-  // Opts into the global `haiku` skill (server/agents/skills/haiku/SKILL.md).
-  // The model auto-loads it when a request matches, or the user can force it
-  // with `/haiku …` in the chat box.
-  skills: ["haiku"],
+  // Opts into two global skills (server/agents/skills/<name>/SKILL.md). A code
+  // agent has no per-agent skills/ folder, so opting in is the only way it
+  // reaches the shared pool. The model auto-loads a skill when a request
+  // matches, or the user can force one with `/haiku …` / `/bullet-brief …`.
+  skills: ["haiku", "bullet-brief"],
   tools(plugins) {
     return {
       ...plugins.analytics.toolkit(),
diff --git a/apps/dev-playground/server/agents/query/agent.md b/apps/dev-playground/server/agents/query/agent.md
index ad96fd16a..014816d61 100644
--- a/apps/dev-playground/server/agents/query/agent.md
+++ b/apps/dev-playground/server/agents/query/agent.md
@@ -5,6 +5,11 @@ agents:
   - dashboard_pilot
 tools:
   - plugin:files: [files.read, files.list, files.metadata]
+# Per-agent skills (query/skills/) are always visible. Opting into the global
+# `haiku` here deliberately collides with the per-agent `haiku`, so both must
+# be addressed qualified: `agent:haiku` (per-agent) and `bundle:haiku` (global).
+skills:
+  - haiku
 ---
 
 You are the dispatcher for the Smart Dashboard — NYC taxi analytics
diff --git a/apps/dev-playground/server/agents/query/skills/haiku/SKILL.md b/apps/dev-playground/server/agents/query/skills/haiku/SKILL.md
new file mode 100644
index 000000000..56c8b2789
--- /dev/null
+++ b/apps/dev-playground/server/agents/query/skills/haiku/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: haiku
+description: Dispatcher's haiku — summarize the routing outcome as a 5-7-5 haiku. Per-agent variant; collides with the global `haiku`, so address it as `agent:haiku`.
+---
+
+When this skill is active, once the work is done, distill the outcome into a
+single 5 / 7 / 5 haiku about what was routed and what came back.
+
+- Three lines, 5 / 7 / 5 syllables. No title, no preamble.
+- Base it on the specialists' real results — don't invent numbers.
diff --git a/apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md b/apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md
new file mode 100644
index 000000000..5dee12956
--- /dev/null
+++ b/apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md
@@ -0,0 +1,17 @@
+---
+name: routing-brief
+description: How the dispatcher writes a one-line handoff and merges specialist replies. Per-agent skill — always visible to the query agent without opting in.
+allowed-tools: [agent-sql_analyst, agent-dashboard_pilot]
+---
+
+You are routing a request to a specialist. Keep your own words to a minimum:
+
+- Emit at most one short sentence before delegating ("Handing this to the SQL
+  analyst…") — or nothing at all when the intent is obvious.
+- Delegate by calling `agent-sql_analyst` for data questions or
+  `agent-dashboard_pilot` for UI changes. Never answer a data question
+  yourself.
+- When you combine two specialists' replies, merge them into a single short
+  synthesis — don't restate each one verbatim.
+
+See `reference.md` for worked handoff examples.
diff --git a/apps/dev-playground/server/agents/query/skills/routing-brief/reference.md b/apps/dev-playground/server/agents/query/skills/routing-brief/reference.md
new file mode 100644
index 000000000..1fd0e26f8
--- /dev/null
+++ b/apps/dev-playground/server/agents/query/skills/routing-brief/reference.md
@@ -0,0 +1,16 @@
+# Routing brief — worked examples
+
+## Single specialist
+
+User: "How many trips last Friday?"
+
+→ Say "Handing this to the SQL analyst…", then call `agent-sql_analyst` with
+the question. Let its answer stand; add nothing.
+
+## Two specialists
+
+User: "Filter to Friday and tell me the top pickup zone."
+
+→ Call `agent-dashboard_pilot` to apply the date filter and `agent-sql_analyst`
+for the top zone, then merge into one line:
+"Filtered to Fri; top pickup zone was Midtown (12,481 trips)."
diff --git a/apps/dev-playground/server/agents/skills/bullet-brief/SKILL.md b/apps/dev-playground/server/agents/skills/bullet-brief/SKILL.md
new file mode 100644
index 000000000..b4c4c35e3
--- /dev/null
+++ b/apps/dev-playground/server/agents/skills/bullet-brief/SKILL.md
@@ -0,0 +1,12 @@
+---
+name: bullet-brief
+description: Format the final answer as a tight markdown bullet list — one idea per bullet, no preamble. Use when the user asks for a summary, a rundown, or to "keep it brief".
+---
+
+When this skill is active, deliver your final answer as a compact markdown
+bullet list:
+
+- One idea per bullet; lead with the number or noun that matters.
+- No opening sentence and no closing summary — just the bullets.
+- Five bullets max. If a data question was asked, call the tools you need and
+  put the real numbers in the bullets. Don't pad to reach five.

From 5a33e95b082743cbb4d301a134e080570dc6ae69 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Thu, 20 Aug 2026 19:10:20 +0200
Subject: [PATCH 3/4] test(appkit): drop the removed dir option from
 skill-client tests

Reconciles with the rebased base: agents({ dir }) was removed (server/agents
is now a fixed convention), so the skill-client tests construct the plugin
with {} instead of { dir: false }.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 .../src/plugins/agents/tests/skill-client.test.ts  | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/appkit/src/plugins/agents/tests/skill-client.test.ts b/packages/appkit/src/plugins/agents/tests/skill-client.test.ts
index 0a814f153..988e4f987 100644
--- a/packages/appkit/src/plugins/agents/tests/skill-client.test.ts
+++ b/packages/appkit/src/plugins/agents/tests/skill-client.test.ts
@@ -51,7 +51,7 @@ describe("skills are wired uniformly for every registered agent", () => {
   // buildRegisteredAgent, so opting one into a skill gives it the same
   // catalog + load_skill/read_skill_file tools as a top-level agent.
   test("buildRegisteredAgent gives a code agent its catalog and skill tools", async () => {
-    const plugin = new AgentsPlugin({ dir: false });
+    const plugin = new AgentsPlugin({});
     // biome-ignore lint/suspicious/noExplicitAny: seed the shared pool
     (plugin as any).globalSkills = [skill("x", { description: "X skill" })];
 
@@ -76,7 +76,7 @@ describe("skills are wired uniformly for every registered agent", () => {
   });
 
   test("an agent with no visible skills gets no skill tools", async () => {
-    const plugin = new AgentsPlugin({ dir: false });
+    const plugin = new AgentsPlugin({});
     // biome-ignore lint/suspicious/noExplicitAny: call private with a stub adapter
     const registered = await (plugin as any).buildRegisteredAgent(
       "bare",
@@ -90,7 +90,7 @@ describe("skills are wired uniformly for every registered agent", () => {
 
 describe("clientConfig — skills", () => {
   test("exposes each agent's skill catalog keyed by agent name", () => {
-    const plugin = new AgentsPlugin({ dir: false });
+    const plugin = new AgentsPlugin({});
     // biome-ignore lint/suspicious/noExplicitAny: seed private registry
     (plugin as any).agents = new Map([
       [
@@ -109,7 +109,7 @@ describe("clientConfig — skills", () => {
   });
 
   test("omits agents that have no visible catalog", () => {
-    const plugin = new AgentsPlugin({ dir: false });
+    const plugin = new AgentsPlugin({});
     // biome-ignore lint/suspicious/noExplicitAny: seed private registry
     (plugin as any).agents = new Map([["bare", registeredWith()]]);
     expect(plugin.clientConfig().skills).toEqual({});
@@ -118,7 +118,7 @@ describe("clientConfig — skills", () => {
 
 describe("renderForcedSkill", () => {
   test("renders the resolved skill body with a request note", () => {
-    const plugin = new AgentsPlugin({ dir: false });
+    const plugin = new AgentsPlugin({});
     const registered = registeredWith(
       catalogOf(skill("pdf", { body: "PDF steps." })),
     );
@@ -130,7 +130,7 @@ describe("renderForcedSkill", () => {
 
   test("returns null for an unknown forced skill", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const plugin = new AgentsPlugin({ dir: false });
+    const plugin = new AgentsPlugin({});
     const registered = registeredWith(catalogOf(skill("pdf")));
     // biome-ignore lint/suspicious/noExplicitAny: call private
     expect((plugin as any).renderForcedSkill(registered, "ghost")).toBeNull();
@@ -139,7 +139,7 @@ describe("renderForcedSkill", () => {
   });
 
   test("returns null when the agent has no catalog", () => {
-    const plugin = new AgentsPlugin({ dir: false });
+    const plugin = new AgentsPlugin({});
     // biome-ignore lint/suspicious/noExplicitAny: call private
     expect(
       (plugin as any).renderForcedSkill(registeredWith(), "pdf"),

From 170f40d6532c9b3a2f82d2ac67908f865664ab88 Mon Sep 17 00:00:00 2001
From: MarioCadenas <MarioCadenas@users.noreply.github.com>
Date: Fri, 21 Aug 2026 12:31:37 +0200
Subject: [PATCH 4/4] refactor(playground): trim skill fixtures

Ponytail review cuts: one-line query picker entry (shorter label), and a
single worked example in routing-brief/reference.md. No behavior change.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>
---
 apps/dev-playground/client/src/routes/agent.route.tsx  |  5 +----
 .../server/agents/query/skills/routing-brief/SKILL.md  |  2 +-
 .../agents/query/skills/routing-brief/reference.md     | 10 +---------
 3 files changed, 3 insertions(+), 14 deletions(-)

diff --git a/apps/dev-playground/client/src/routes/agent.route.tsx b/apps/dev-playground/client/src/routes/agent.route.tsx
index d32651a64..95fb700d0 100644
--- a/apps/dev-playground/client/src/routes/agent.route.tsx
+++ b/apps/dev-playground/client/src/routes/agent.route.tsx
@@ -18,10 +18,7 @@ const AGENT_OPTIONS = [
   { value: "helper", label: "Helper — general assistant" },
   { value: "sql_analyst", label: "SQL Analyst — NYC taxi queries" },
   { value: "supervisor", label: "Supervisor — Databricks-hosted tools" },
-  {
-    value: "query",
-    label: "Query — dispatcher (per-agent + collision skills)",
-  },
+  { value: "query", label: "Query — skills dispatcher" },
 ] as const;
 
 interface SSEEvent {
diff --git a/apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md b/apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md
index 5dee12956..b72f01b6b 100644
--- a/apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md
+++ b/apps/dev-playground/server/agents/query/skills/routing-brief/SKILL.md
@@ -14,4 +14,4 @@ You are routing a request to a specialist. Keep your own words to a minimum:
 - When you combine two specialists' replies, merge them into a single short
   synthesis — don't restate each one verbatim.
 
-See `reference.md` for worked handoff examples.
+See `reference.md` for a worked handoff example.
diff --git a/apps/dev-playground/server/agents/query/skills/routing-brief/reference.md b/apps/dev-playground/server/agents/query/skills/routing-brief/reference.md
index 1fd0e26f8..fbae725f4 100644
--- a/apps/dev-playground/server/agents/query/skills/routing-brief/reference.md
+++ b/apps/dev-playground/server/agents/query/skills/routing-brief/reference.md
@@ -1,4 +1,4 @@
-# Routing brief — worked examples
+# Routing brief — worked example
 
 ## Single specialist
 
@@ -6,11 +6,3 @@ User: "How many trips last Friday?"
 
 → Say "Handing this to the SQL analyst…", then call `agent-sql_analyst` with
 the question. Let its answer stand; add nothing.
-
-## Two specialists
-
-User: "Filter to Friday and tell me the top pickup zone."
-
-→ Call `agent-dashboard_pilot` to apply the date filter and `agent-sql_analyst`
-for the top zone, then merge into one line:
-"Filtered to Fri; top pickup zone was Midtown (12,481 trips)."