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>

Author: MackinnonBuck

docs/features/custom-agents.md

@@ -216,7 +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 |
+| `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.
 
@@ -228,7 +228,7 @@ In addition to per-agent configuration above, you can set `agent` on the **sessi
 
 ## 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`.
+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({
@@ -251,7 +251,7 @@ const session = await client.createSession({
 });
 ```
 
-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.
+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
 

docs/features/skills.md

@@ -316,7 +316,7 @@ The markdown body contains the instructions that are injected into the session c
 
 ### Skills + 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`.
+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({
@@ -331,7 +331,7 @@ const session = await client.createSession({
 });
 ```
 
-> **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.
+> **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

@@ -1517,10 +1517,11 @@ public class CustomAgentConfig
     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).
+    /// 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).
     /// </summary>
     [JsonPropertyName("skills")]
     public List<string>? Skills { get; set; }

dotnet/test/SkillsTests.cs

@@ -110,7 +110,7 @@ public async Task Should_Allow_Agent_With_Skills_To_Invoke_Skill()
 
         Assert.Matches(@"^[a-f0-9-]+$", session.SessionId);
 
-        // The agent has Skills = ["test-skill"], so it should be able to invoke the skill
+        // 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);
@@ -140,7 +140,7 @@ public async Task Should_Not_Provide_Skills_To_Agent_Without_Skills_Field()
 
         Assert.Matches(@"^[a-f0-9-]+$", session.SessionId);
 
-        // The agent has no Skills field, so it should NOT have access to skills
+        // 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);

go/internal/e2e/skills_test.go

@@ -131,7 +131,7 @@ func TestSkills(t *testing.T) {
 			t.Fatalf("Failed to create session: %v", err)
 		}
 
-		// The agent has Skills: ["test-skill"], so it should be able to invoke the skill
+		// 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.",
 		})
@@ -168,7 +168,7 @@ func TestSkills(t *testing.T) {
 			t.Fatalf("Failed to create session: %v", err)
 		}
 
-		// The agent has no Skills field, so it should NOT have access to skills
+		// 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.",
 		})

go/types.go

@@ -416,7 +416,7 @@ 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 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"`
 }
 

nodejs/src/types.ts

@@ -1007,10 +1007,11 @@ export interface CustomAgentConfig {
      */
     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).
+     * 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

@@ -112,7 +112,7 @@ IMPORTANT: You MUST include the exact text "${SKILL_MARKER}" somewhere in EVERY
 
             expect(session.sessionId).toBeDefined();
 
-            // The agent has skills: ["test-skill"], so it should be able to invoke the skill
+            // 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.",
             });
@@ -140,7 +140,7 @@ IMPORTANT: You MUST include the exact text "${SKILL_MARKER}" somewhere in EVERY
 
             expect(session.sessionId).toBeDefined();
 
-            // The agent has no skills field, so it should NOT have access to skills
+            // 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.",
             });

python/copilot/session.py

@@ -748,7 +748,7 @@ 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
-    # List of skill names available to this agent (opt-in; omit for no skills)
+    # Skill names to preload into this agent's context at startup (opt-in; omit for none)
     skills: NotRequired[list[str]]
 
 

python/e2e/test_skills.py

@@ -89,7 +89,7 @@ async def test_should_not_apply_skill_when_disabled_via_disabledskills(
         await session.disconnect()
 
     async def test_should_allow_agent_with_skills_to_invoke_skill(self, ctx: E2ETestContext):
-        """Test that an agent with skills can invoke the specified skill"""
+        """Test that an agent with skills gets skill content preloaded into context"""
         skills_dir = create_skill_dir(ctx.work_dir)
         custom_agents: list[CustomAgentConfig] = [
             {
@@ -108,7 +108,7 @@ async def test_should_allow_agent_with_skills_to_invoke_skill(self, ctx: E2ETest
 
         assert session.session_id is not None
 
-        # The agent has skills: ["test-skill"], so it should be able to invoke the skill
+        # The agent has skills: ["test-skill"], so the skill content is preloaded into its context
         message = await session.send_and_wait("Say hello briefly using the test skill.")
         assert message is not None
         assert SKILL_MARKER in message.data.content
@@ -118,7 +118,7 @@ async def test_should_allow_agent_with_skills_to_invoke_skill(self, ctx: E2ETest
     async def test_should_not_provide_skills_to_agent_without_skills_field(
         self, ctx: E2ETestContext
     ):
-        """Test that an agent without skills field gets no skills (opt-in model)"""
+        """Test that an agent without skills field gets no skill content (opt-in model)"""
         skills_dir = create_skill_dir(ctx.work_dir)
         custom_agents: list[CustomAgentConfig] = [
             {
@@ -136,7 +136,7 @@ async def test_should_not_provide_skills_to_agent_without_skills_field(
 
         assert session.session_id is not None
 
-        # The agent has no skills field, so it should NOT have access to skills
+        # The agent has no skills field, so no skill content is injected
         message = await session.send_and_wait("Say hello briefly using the test skill.")
         assert message is not None
         assert SKILL_MARKER not in message.data.content