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>

Author: MackinnonBuck

docs/features/custom-agents.md

@@ -216,6 +216,7 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
 | `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[]` | | List of skill names available to this agent |
 
 > **Tip:** A good `description` helps the runtime match user intent to the right agent. Be specific about the agent's expertise and capabilities.
 
@@ -225,6 +226,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 scope skills to individual agents using the `skills` property. Skills are **opt-in** — agents have no access to skills by default. The skill names listed in `skills` 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` can invoke only `security-scan` and `dependency-check`, while `docs-writer` can invoke only `markdown-lint`. An agent without a `skills` field has no access to any skills.
+
 ## 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

@@ -316,20 +316,23 @@ The markdown body contains the instructions that are injected into the session c
 
 ### Skills + Custom Agents
 
-Skills work alongside custom agents:
+Skills can be scoped to individual custom agents using the `skills` property. Skills are **opt-in** — agents get no skills by default. Skill names are resolved from the session-level `skillDirectories`.
 
 ```typescript
 const session = await client.createSession({
-    skillDirectories: ["./skills/security"],
+    skillDirectories: ["./skills"],
     customAgents: [{
         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:** When `skills` is omitted, the agent has **no** access to skills. This is an opt-in model — you must explicitly list the skills each agent needs.
+
 ### Skills + MCP Servers
 
 Skills can complement MCP server capabilities:

docs/features/streaming-events.md

@@ -618,6 +618,7 @@ A skill was activated for the current conversation.
 | `allowedTools` | `string[]` | | Tools auto-approved while this skill is active |
 | `pluginName` | `string` | | Plugin the skill originated from |
 | `pluginVersion` | `string` | | Plugin version |
+| `agentName` | `string` | | Name of the agent that invoked the skill, when invoked by a custom agent |
 
 ---
 

dotnet/src/Types.cs

@@ -1515,6 +1515,15 @@ public class CustomAgentConfig
     /// </summary>
     [JsonPropertyName("infer")]
     public bool? Infer { get; set; }
+
+    /// <summary>
+    /// List of skill names available to this agent.
+    /// Skills are resolved by name from the session's loaded skill pool (configured via skillDirectories).
+    /// When set, only the listed skills can be invoked by this agent.
+    /// When omitted, the agent has no access to skills (opt-in model).
+    /// </summary>
+    [JsonPropertyName("skills")]
+    public List<string>? Skills { get; set; }
 }
 
 /// <summary>

dotnet/test/SkillsTests.cs

@@ -87,6 +87,67 @@ 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
+        });
+
+        Assert.Matches(@"^[a-f0-9-]+$", session.SessionId);
+
+        // The agent has Skills = ["test-skill"], so it should be able to invoke the skill
+        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
+        });
+
+        Assert.Matches(@"^[a-f0-9-]+$", session.SessionId);
+
+        // The agent has no Skills field, so it should NOT have access to skills
+        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,81 @@ 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,
+		})
+		if err != nil {
+			t.Fatalf("Failed to create session: %v", err)
+		}
+
+		// The agent has Skills: ["test-skill"], so it should be able to invoke the skill
+		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 message.Data.Content == nil || !strings.Contains(*message.Data.Content, skillMarker) {
+			t.Errorf("Expected message to contain skill marker '%s', got: %v", skillMarker, message.Data.Content)
+		}
+
+		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,
+		})
+		if err != nil {
+			t.Fatalf("Failed to create session: %v", err)
+		}
+
+		// The agent has no Skills field, so it should NOT have access to skills
+		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 message.Data.Content != nil && strings.Contains(*message.Data.Content, skillMarker) {
+			t.Errorf("Expected message to NOT contain skill marker '%s' when agent has no skills, got: %v", skillMarker, *message.Data.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

@@ -416,6 +416,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 available to this agent (opt-in; omit for no skills)
+	Skills []string `json:"skills,omitempty"`
 }
 
 // InfiniteSessionConfig configures infinite sessions with automatic context compaction

nodejs/package-lock.json

@@ -1006,6 +1006,13 @@ export interface CustomAgentConfig {
      * @default true
      */
     infer?: boolean;
+    /**
+     * List of skill names available to this agent.
+     * Skills are resolved by name from the session's loaded skill pool (configured via `skillDirectories`).
+     * When set, only the listed skills can be invoked by this agent.
+     * When omitted, the agent has no access to skills (opt-in model).
+     */
+    skills?: string[];
 }
 
 /**