feat: add per-agent skills support (#995)

* feat: add per-agent skills support to SDK types and docs (#958)

Add a 'skills' field to CustomAgentConfig across all four SDK languages
(Node.js, Python, Go, .NET) to support scoping skills to individual
subagents. Skills are opt-in: agents get no skills by default.

Changes:
- Add skills?: string[] to CustomAgentConfig in all SDKs
- Update custom-agents.md with skills in config table and new section
- Update skills.md with per-agent skills example and opt-in note
- Update streaming-events.md with agentName on skill.invoked event
- Add E2E tests for agent-scoped skills in all four SDKs
- Add snapshot YAML files for new test scenarios

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: update skills semantics to eager injection model

Update type comments, docs, and test descriptions to reflect that
per-agent skills are eagerly injected into the agent's context at
startup rather than filtered for invocation. Sub-agents do not
inherit skills from the parent.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: remove agentName from skill.invoked event table

The runtime does not emit agentName on the skill.invoked event.
The agent name is used only for internal logging during eager
skill loading, not as event data.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: address PR review feedback for per-agent skills (#995)

- Add skills field to Python wire format converter
- Explicitly select agents in all E2E tests for deterministic behavior

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: update Go skills tests to use typed SessionEventData after rebase

The generated_session_events.go on main changed from a flat Data struct
to a SessionEventData interface with per-event typed structs. The agent
skills test cases added in this PR were using the old message.Data.Content
pattern instead of the type assertion pattern used elsewhere.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore: revert unintentional package-lock.json changes

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: update proxy and snapshots for eager skill injection

The runtime now eagerly injects skill content into <agent_instructions>
in the user message instead of using a skill tool call. Update the
replay proxy to strip <agent_instructions> during normalization, and
simplify the snapshot for agent-with-skills to match the new flow.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test: add agent_instructions normalization tests for replay proxy

Add two regression tests validating that <agent_instructions> blocks
are properly stripped during user message normalization, including
the case where skill-context is nested inside agent_instructions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: use IList<string> for Skills property in .NET SDK

Match the established convention used by Tools, SkillDirectories,
DisabledSkills, and other collection properties in the codebase.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: restore original skillDirectories path in skills.md sample

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: use see cref for SkillDirectories in XML doc

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: MackinnonBuck

docs/features/custom-agents.md

@@ -252,6 +252,7 @@ try (var client = new CopilotClient()) {
 | `prompt` | `string` | ✅ | System prompt for the agent |
 | `mcpServers` | `object` | | MCP server configurations specific to this agent |
 | `infer` | `boolean` | | Whether the runtime can auto-select this agent (default: `true`) |
+| `skills` | `string[]` | | Skill names to preload into the agent's context at startup |
 
 > **Tip:** A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities.
 
@@ -261,6 +262,33 @@ In addition to per-agent configuration above, you can set `agent` on the **sessi
 |-------------------------|------|-------------|
 | `agent` | `string` | Name of the custom agent to pre-select at session creation. Must match a `name` in `customAgents`. |
 
+## Per-Agent Skills
+
+You can preload skills into an agent's context using the `skills` property. When specified, the **full content** of each listed skill is eagerly injected into the agent's context at startup — the agent doesn't need to invoke a skill tool; the instructions are already present. Skills are **opt-in**: agents receive no skills by default, and sub-agents do not inherit skills from the parent. Skill names are resolved from the session-level `skillDirectories`.
+
+```typescript
+const session = await client.createSession({
+    skillDirectories: ["./skills"],
+    customAgents: [
+        {
+            name: "security-auditor",
+            description: "Security-focused code reviewer",
+            prompt: "Focus on OWASP Top 10 vulnerabilities",
+            skills: ["security-scan", "dependency-check"],
+        },
+        {
+            name: "docs-writer",
+            description: "Technical documentation writer",
+            prompt: "Write clear, concise documentation",
+            skills: ["markdown-lint"],
+        },
+    ],
+    onPermissionRequest: async () => ({ kind: "approved" }),
+});
+```
+
+In this example, `security-auditor` starts with `security-scan` and `dependency-check` already injected into its context, while `docs-writer` starts with `markdown-lint`. An agent without a `skills` field receives no skill content.
+
 ## Selecting an Agent at Session Creation
 
 You can pass `agent` in the session config to pre-select which custom agent should be active when the session starts. The value must match the `name` of one of the agents defined in `customAgents`.

docs/features/skills.md

@@ -364,7 +364,7 @@ The markdown body contains the instructions that are injected into the session c
 
 ### Skills + Custom Agents
 
-Skills work alongside custom agents:
+Skills listed in an agent's `skills` field are **eagerly preloaded** — their full content is injected into the agent's context at startup, so the agent has access to the skill instructions immediately without needing to invoke a skill tool. Skill names are resolved from the session-level `skillDirectories`.
 
 ```typescript
 const session = await client.createSession({
@@ -373,10 +373,12 @@ const session = await client.createSession({
         name: "security-auditor",
         description: "Security-focused code reviewer",
         prompt: "Focus on OWASP Top 10 vulnerabilities",
+        skills: ["security-scan", "dependency-check"],
     }],
     onPermissionRequest: async () => ({ kind: "approved" }),
 });
 ```
+> **Note:** Skills are opt-in — when `skills` is omitted, no skill content is injected. Sub-agents do not inherit skills from the parent; you must list them explicitly per agent.
 
 ### Skills + MCP Servers
 

dotnet/src/Types.cs

@@ -1638,6 +1638,16 @@ public class CustomAgentConfig
     /// </summary>
     [JsonPropertyName("infer")]
     public bool? Infer { get; set; }
+
+    /// <summary>
+    /// List of skill names to preload into this agent's context.
+    /// When set, the full content of each listed skill is eagerly injected into
+    /// the agent's context at startup. Skills are resolved by name from the
+    /// session's configured skill directories (<see cref="SessionConfig.SkillDirectories"/>).
+    /// When omitted, no skills are injected (opt-in model).
+    /// </summary>
+    [JsonPropertyName("skills")]
+    public IList<string>? Skills { get; set; }
 }
 
 /// <summary>

dotnet/test/SkillsTests.cs

@@ -87,6 +87,69 @@ public async Task Should_Not_Apply_Skill_When_Disabled_Via_DisabledSkills()
         await session.DisposeAsync();
     }
 
+    [Fact]
+    public async Task Should_Allow_Agent_With_Skills_To_Invoke_Skill()
+    {
+        var skillsDir = CreateSkillDir();
+        var customAgents = new List<CustomAgentConfig>
+        {
+            new CustomAgentConfig
+            {
+                Name = "skill-agent",
+                Description = "An agent with access to test-skill",
+                Prompt = "You are a helpful test agent.",
+                Skills = ["test-skill"]
+            }
+        };
+
+        var session = await CreateSessionAsync(new SessionConfig
+        {
+            SkillDirectories = [skillsDir],
+            CustomAgents = customAgents,
+            Agent = "skill-agent"
+        });
+
+        Assert.Matches(@"^[a-f0-9-]+$", session.SessionId);
+
+        // The agent has Skills = ["test-skill"], so the skill content is preloaded into its context
+        var message = await session.SendAndWaitAsync(new MessageOptions { Prompt = "Say hello briefly using the test skill." });
+        Assert.NotNull(message);
+        Assert.Contains(SkillMarker, message!.Data.Content);
+
+        await session.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task Should_Not_Provide_Skills_To_Agent_Without_Skills_Field()
+    {
+        var skillsDir = CreateSkillDir();
+        var customAgents = new List<CustomAgentConfig>
+        {
+            new CustomAgentConfig
+            {
+                Name = "no-skill-agent",
+                Description = "An agent without skills access",
+                Prompt = "You are a helpful test agent."
+            }
+        };
+
+        var session = await CreateSessionAsync(new SessionConfig
+        {
+            SkillDirectories = [skillsDir],
+            CustomAgents = customAgents,
+            Agent = "no-skill-agent"
+        });
+
+        Assert.Matches(@"^[a-f0-9-]+$", session.SessionId);
+
+        // The agent has no Skills field, so no skill content is injected
+        var message = await session.SendAndWaitAsync(new MessageOptions { Prompt = "Say hello briefly using the test skill." });
+        Assert.NotNull(message);
+        Assert.DoesNotContain(SkillMarker, message!.Data.Content);
+
+        await session.DisposeAsync();
+    }
+
     [Fact(Skip = "See the big comment around the equivalent test in the Node SDK. Skipped because the feature doesn't work correctly yet.")]
     public async Task Should_Apply_Skill_On_Session_Resume_With_SkillDirectories()
     {

go/internal/e2e/skills_test.go

@@ -108,6 +108,83 @@ func TestSkills(t *testing.T) {
 		session.Disconnect()
 	})
 
+	t.Run("should allow agent with skills to invoke skill", func(t *testing.T) {
+		ctx.ConfigureForTest(t)
+		cleanSkillsDir(t, ctx.WorkDir)
+		skillsDir := createTestSkillDir(t, ctx.WorkDir, skillMarker)
+
+		customAgents := []copilot.CustomAgentConfig{
+			{
+				Name:        "skill-agent",
+				Description: "An agent with access to test-skill",
+				Prompt:      "You are a helpful test agent.",
+				Skills:      []string{"test-skill"},
+			},
+		}
+
+		session, err := client.CreateSession(t.Context(), &copilot.SessionConfig{
+			OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+			SkillDirectories:    []string{skillsDir},
+			CustomAgents:        customAgents,
+			Agent:               "skill-agent",
+		})
+		if err != nil {
+			t.Fatalf("Failed to create session: %v", err)
+		}
+
+		// The agent has Skills: ["test-skill"], so the skill content is preloaded into its context
+		message, err := session.SendAndWait(t.Context(), copilot.MessageOptions{
+			Prompt: "Say hello briefly using the test skill.",
+		})
+		if err != nil {
+			t.Fatalf("Failed to send message: %v", err)
+		}
+
+		if md, ok := message.Data.(*copilot.AssistantMessageData); !ok || !strings.Contains(md.Content, skillMarker) {
+			t.Errorf("Expected message to contain skill marker '%s', got: %v", skillMarker, message.Data)
+		}
+
+		session.Disconnect()
+	})
+
+	t.Run("should not provide skills to agent without skills field", func(t *testing.T) {
+		ctx.ConfigureForTest(t)
+		cleanSkillsDir(t, ctx.WorkDir)
+		skillsDir := createTestSkillDir(t, ctx.WorkDir, skillMarker)
+
+		customAgents := []copilot.CustomAgentConfig{
+			{
+				Name:        "no-skill-agent",
+				Description: "An agent without skills access",
+				Prompt:      "You are a helpful test agent.",
+			},
+		}
+
+		session, err := client.CreateSession(t.Context(), &copilot.SessionConfig{
+			OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
+			SkillDirectories:    []string{skillsDir},
+			CustomAgents:        customAgents,
+			Agent:               "no-skill-agent",
+		})
+		if err != nil {
+			t.Fatalf("Failed to create session: %v", err)
+		}
+
+		// The agent has no Skills field, so no skill content is injected
+		message, err := session.SendAndWait(t.Context(), copilot.MessageOptions{
+			Prompt: "Say hello briefly using the test skill.",
+		})
+		if err != nil {
+			t.Fatalf("Failed to send message: %v", err)
+		}
+
+		if md, ok := message.Data.(*copilot.AssistantMessageData); ok && strings.Contains(md.Content, skillMarker) {
+			t.Errorf("Expected message to NOT contain skill marker '%s' when agent has no skills, got: %v", skillMarker, md.Content)
+		}
+
+		session.Disconnect()
+	})
+
 	t.Run("should apply skill on session resume with skillDirectories", func(t *testing.T) {
 		t.Skip("See the big comment around the equivalent test in the Node SDK. Skipped because the feature doesn't work correctly yet.")
 		ctx.ConfigureForTest(t)

go/types.go

@@ -450,6 +450,8 @@ type CustomAgentConfig struct {
 	MCPServers map[string]MCPServerConfig `json:"mcpServers,omitempty"`
 	// Infer indicates whether the agent should be available for model inference
 	Infer *bool `json:"infer,omitempty"`
+	// Skills is the list of skill names to preload into this agent's context at startup (opt-in; omit for none)
+	Skills []string `json:"skills,omitempty"`
 }
 
 // InfiniteSessionConfig configures infinite sessions with automatic context compaction

nodejs/src/types.ts

@@ -1104,6 +1104,14 @@ export interface CustomAgentConfig {
      * @default true
      */
     infer?: boolean;
+    /**
+     * List of skill names to preload into this agent's context.
+     * When set, the full content of each listed skill is eagerly injected into
+     * the agent's context at startup. Skills are resolved by name from the
+     * session's configured skill directories (`skillDirectories`).
+     * When omitted, no skills are injected (opt-in model).
+     */
+    skills?: string[];
 }
 
 /**

nodejs/test/e2e/skills.test.ts

@@ -5,6 +5,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { beforeEach, describe, expect, it } from "vitest";
+import type { CustomAgentConfig } from "../../src/index.js";
 import { approveAll } from "../../src/index.js";
 import { createSdkTestContext } from "./harness/sdkTestContext.js";
 
@@ -92,6 +93,65 @@ IMPORTANT: You MUST include the exact text "${SKILL_MARKER}" somewhere in EVERY
         // Also, if this test runs FIRST and then the "should load and apply skill from skillDirectories" test runs second
         // within the same run (i.e., sharing the same Client instance), then the second test fails too. There's definitely
         // some state being shared or cached incorrectly.
+        it("should allow agent with skills to invoke skill", async () => {
+            const skillsDir = createSkillDir();
+            const customAgents: CustomAgentConfig[] = [
+                {
+                    name: "skill-agent",
+                    description: "An agent with access to test-skill",
+                    prompt: "You are a helpful test agent.",
+                    skills: ["test-skill"],
+                },
+            ];
+
+            const session = await client.createSession({
+                onPermissionRequest: approveAll,
+                skillDirectories: [skillsDir],
+                customAgents,
+                agent: "skill-agent",
+            });
+
+            expect(session.sessionId).toBeDefined();
+
+            // The agent has skills: ["test-skill"], so the skill content is preloaded into its context
+            const message = await session.sendAndWait({
+                prompt: "Say hello briefly using the test skill.",
+            });
+
+            expect(message?.data.content).toContain(SKILL_MARKER);
+
+            await session.disconnect();
+        });
+
+        it("should not provide skills to agent without skills field", async () => {
+            const skillsDir = createSkillDir();
+            const customAgents: CustomAgentConfig[] = [
+                {
+                    name: "no-skill-agent",
+                    description: "An agent without skills access",
+                    prompt: "You are a helpful test agent.",
+                },
+            ];
+
+            const session = await client.createSession({
+                onPermissionRequest: approveAll,
+                skillDirectories: [skillsDir],
+                customAgents,
+                agent: "no-skill-agent",
+            });
+
+            expect(session.sessionId).toBeDefined();
+
+            // The agent has no skills field, so no skill content is injected
+            const message = await session.sendAndWait({
+                prompt: "Say hello briefly using the test skill.",
+            });
+
+            expect(message?.data.content).not.toContain(SKILL_MARKER);
+
+            await session.disconnect();
+        });
+
         it.skip("should apply skill on session resume with skillDirectories", async () => {
             const skillsDir = createSkillDir();
 

python/copilot/client.py

@@ -2156,6 +2156,8 @@ def _convert_custom_agent_to_wire_format(
             wire_agent["mcpServers"] = agent["mcp_servers"]
         if "infer" in agent:
             wire_agent["infer"] = agent["infer"]
+        if "skills" in agent:
+            wire_agent["skills"] = agent["skills"]
         return wire_agent
 
     async def _start_cli_server(self) -> None:

python/copilot/session.py

@@ -777,6 +777,8 @@ class CustomAgentConfig(TypedDict, total=False):
     # MCP servers specific to agent
     mcp_servers: NotRequired[dict[str, MCPServerConfig]]
     infer: NotRequired[bool]  # Whether agent is available for model inference
+    # Skill names to preload into this agent's context at startup (opt-in; omit for none)
+    skills: NotRequired[list[str]]
 
 
 class InfiniteSessionConfig(TypedDict, total=False):