Merge pull request #2474 from dgageot/board/support-boolean-or-array-skills-in-yaml-f97b09f6

Support filtering skills by name in agent YAML (#2404)

Author: dgageot

agent-schema.json

@@ -397,8 +397,26 @@
           "description": "Lifecycle hooks for executing shell commands at various points in the agent's execution"
         },
         "skills": {
-          "type": "boolean",
-          "description": "Enable skills discovery for this agent. When enabled, the agent can discover and load skill files (SKILL.md) from the workspace."
+          "description": "Enable skills discovery for this agent. Set to true to load all discovered skills from local filesystem sources; false disables skills. A list can mix sources (\"local\" or an HTTP/HTTPS URL) and/or skill names to include. If only names are given, local sources are loaded and filtered to just those skills.",
+          "oneOf": [
+            {
+              "type": "boolean",
+              "description": "When true, loads all discovered local skills. When false, skills are disabled."
+            },
+            {
+              "type": "array",
+              "description": "List combining skill sources and/or skill names to include. Items equal to \"local\" or starting with http:// or https:// are treated as sources; any other string is treated as a skill name filter.",
+              "items": {
+                "type": "string"
+              },
+              "examples": [
+                ["local"],
+                ["local", "https://skills.example.com"],
+                ["git", "docker"],
+                ["local", "docker-build"]
+              ]
+            }
+          ]
         }
       },
       "additionalProperties": false

docs/configuration/agents/index.md

@@ -33,7 +33,7 @@ agents:
     max_consecutive_tool_calls: int # Optional: max identical consecutive tool calls
     max_old_tool_call_tokens: int # Optional: token budget for old tool call content
     num_history_items: int # Optional: limit conversation history
-    skills: boolean # Optional: enable skill discovery
+    skills: boolean | [list] # Optional: enable skill discovery (true/false or list of names and/or sources)
     commands: # Optional: named prompts
       name: "prompt text"
     welcome_message: string # Optional: message shown at session start
@@ -78,7 +78,7 @@ agents:
 | `max_old_tool_call_tokens`  | int     | ✗        | Maximum number of tokens to keep from old tool call arguments and results. Older tool calls beyond this budget have their content replaced with a placeholder, saving context space. Tokens are approximated as `len/4`. Set to `-1` to disable truncation (unlimited). Default: `40000`. |
 | `num_history_items`         | int     | ✗        | Limit the number of conversation history messages sent to the model. Useful for managing context window size with long conversations. Default: unlimited (all messages sent). |
 | `rag`                       | array   | ✗        | List of RAG source names to attach to this agent. References sources defined in the top-level `rag` section. See [RAG]({{ '/features/rag/' | relative_url }}).                                       |
-| `skills`                    | boolean | ✗        | Enable automatic skill discovery from standard directories.                                                                                                                   |
+| `skills`                    | bool/array | ✗     | Enable automatic skill discovery. `true` loads all discovered local skills, `false` disables them. A list can mix skill sources (`local` or `https://…` URLs) and skill names to include — see [Skills]({{ '/features/skills/' | relative_url }}).                                                     |
 | `commands`                  | object  | ✗        | Named prompts that can be run with `docker agent run config.yaml /command_name`.                                                                                              |
 | `welcome_message`           | string  | ✗        | Message displayed to the user when a session starts. Useful for providing context or instructions.                                                                            |
 | `handoffs`                  | array   | ✗        | List of agent names this agent can hand off the conversation to. Enables the `handoff` tool. See [Handoffs Routing]({{ '/concepts/multi-agent/#handoffs-routing' | relative_url }}).                  |

docs/features/skills/index.md

@@ -34,6 +34,40 @@ agents:
 
 </div>
 
+## Filtering Skills
+
+The `skills` field also accepts a list, letting you restrict the agent to a specific subset of skills instead of exposing every discovered one. List items are classified automatically:
+
+- `"local"` or any `http://` / `https://` URL → a **source** to load skills from
+- any other string → the **name** of a skill to include
+
+When only names are given, local sources are used by default.
+
+```yaml
+agents:
+  # Load every discovered local skill (same as `skills: true`).
+  full:
+    skills: true
+
+  # Load local skills, but only expose "commit" and "poem".
+  scoped:
+    skills:
+      - commit
+      - poem
+
+  # Combine an explicit source with a name filter.
+  remote_filtered:
+    skills:
+      - https://skills.example.com
+      - commit
+
+  # Disable skills entirely.
+  none:
+    skills: false
+```
+
+A name that doesn't match any discovered skill is logged as a warning at startup but is otherwise ignored.
+
 ## SKILL.md Format
 
 <!-- yaml-lint:skip -->
@@ -171,11 +205,11 @@ When asked to create a Dockerfile:
 EOF
 ```
 
-The skill will automatically be available to any agent with `skills: true`.
+The skill will automatically be available to any agent with skills enabled (`skills: true`, or a list that targets its name — see [Filtering Skills](#filtering-skills)).
 
 <div class="callout callout-info" markdown="1">
 <div class="callout-title">ℹ️ See also
 </div>
-  <p>Skills are enabled in the <a href="{{ '/configuration/agents/' | relative_url }}">Agent Config</a> with the <code>skills: true</code> property. For tool-based capabilities, see <a href="{{ '/concepts/tools/' | relative_url }}">Tools</a>.</p>
+  <p>Skills are enabled in the <a href="{{ '/configuration/agents/' | relative_url }}">Agent Config</a> with the <code>skills</code> property (boolean or list). For tool-based capabilities, see <a href="{{ '/concepts/tools/' | relative_url }}">Tools</a>.</p>
 
 </div>

examples/skills_filter.yaml

@@ -0,0 +1,29 @@
+#!yaml
+# Skills filter example.
+#
+# The `skills` field accepts either:
+#   - `true` / `false` to enable/disable skills discovery entirely.
+#   - A list combining skill sources and/or skill names to include.
+#
+# Items equal to "local" or starting with http:// or https:// are treated as
+# sources (where to discover skills from). Any other string is treated as the
+# name of a specific skill to expose to the agent. When only skill names are
+# given, the `local` source is used by default.
+#
+# The agent below loads skills from the local workspace but only exposes the
+# `commit` and `poem` skills. Any other discovered skills (including the
+# built-in `bump-go-dependencies`) will be hidden from the model.
+agents:
+  root:
+    model: openai/gpt-4o-mini
+    description: A small agent that demonstrates filtering skills by name.
+    instruction: |
+      You are a helpful assistant. Use the available skills when the user's
+      request matches one.
+    # Only expose the "commit" and "poem" skills from the locally discovered set.
+    skills:
+      - commit
+      - poem
+    toolsets:
+      - type: shell
+      - type: filesystem

pkg/config/config.go

@@ -247,5 +247,10 @@ func validateSkillsConfiguration(_ string, agent *latest.AgentConfig) error {
 			return fmt.Errorf("agent '%s' has unknown skills source '%s' (must be 'local' or an HTTP/HTTPS URL)", agent.Name, source)
 		}
 	}
+	for _, name := range agent.Skills.Include {
+		if strings.TrimSpace(name) == "" {
+			return fmt.Errorf("agent '%s' has an empty skills entry", agent.Name)
+		}
+	}
 	return nil
 }

pkg/config/latest/skills_config_test.go

@@ -54,6 +54,30 @@ func TestSkillsConfig_UnmarshalYAML(t *testing.T) {
 				"http://internal.corp",
 			}},
 		},
+		{
+			name:  "list of skill names implies local source",
+			input: "[git, docker]",
+			expected: SkillsConfig{
+				Sources: []string{"local"},
+				Include: []string{"git", "docker"},
+			},
+		},
+		{
+			name:  "list mixing local source and skill names",
+			input: "[local, git]",
+			expected: SkillsConfig{
+				Sources: []string{"local"},
+				Include: []string{"git"},
+			},
+		},
+		{
+			name:  "list mixing remote source and skill names",
+			input: "[\"https://skills.example.com\", git]",
+			expected: SkillsConfig{
+				Sources: []string{"https://skills.example.com"},
+				Include: []string{"git"},
+			},
+		},
 	}
 
 	for _, tt := range tests {
@@ -92,6 +116,22 @@ func TestSkillsConfig_MarshalYAML(t *testing.T) {
 			input:    SkillsConfig{Sources: []string{"https://example.com"}},
 			expected: "- https://example.com\n",
 		},
+		{
+			name: "include with default local source omits local",
+			input: SkillsConfig{
+				Sources: []string{"local"},
+				Include: []string{"git", "docker"},
+			},
+			expected: "- git\n- docker\n",
+		},
+		{
+			name: "include with explicit remote keeps both",
+			input: SkillsConfig{
+				Sources: []string{"https://example.com"},
+				Include: []string{"git"},
+			},
+			expected: "- https://example.com\n- git\n",
+		},
 	}
 
 	for _, tt := range tests {
@@ -129,6 +169,22 @@ func TestSkillsConfig_UnmarshalJSON(t *testing.T) {
 			input:    `["local", "https://skills.example.com"]`,
 			expected: SkillsConfig{Sources: []string{"local", "https://skills.example.com"}},
 		},
+		{
+			name:  "list with skill names defaults to local",
+			input: `["git", "docker"]`,
+			expected: SkillsConfig{
+				Sources: []string{"local"},
+				Include: []string{"git", "docker"},
+			},
+		},
+		{
+			name:  "list mixing source and names",
+			input: `["local", "git"]`,
+			expected: SkillsConfig{
+				Sources: []string{"local"},
+				Include: []string{"git"},
+			},
+		},
 	}
 
 	for _, tt := range tests {
@@ -162,6 +218,22 @@ func TestSkillsConfig_MarshalJSON(t *testing.T) {
 			input:    SkillsConfig{Sources: []string{"local", "https://example.com"}},
 			expected: `["local","https://example.com"]`,
 		},
+		{
+			name: "include with default local source omits local",
+			input: SkillsConfig{
+				Sources: []string{"local"},
+				Include: []string{"git", "docker"},
+			},
+			expected: `["git","docker"]`,
+		},
+		{
+			name: "include with remote source keeps both",
+			input: SkillsConfig{
+				Sources: []string{"https://example.com"},
+				Include: []string{"git"},
+			},
+			expected: `["https://example.com","git"]`,
+		},
 	}
 
 	for _, tt := range tests {
@@ -268,3 +340,72 @@ toolsets:
 	assert.True(t, agent.Skills.HasLocal())
 	assert.Empty(t, agent.Skills.RemoteURLs())
 }
+
+func TestSkillsConfig_InAgentConfigIncludeOnly(t *testing.T) {
+	yamlInput := `
+model: openai/gpt-4
+skills:
+  - git
+  - docker
+toolsets:
+  - type: filesystem
+`
+	var agent AgentConfig
+	err := yaml.Unmarshal([]byte(yamlInput), &agent)
+	require.NoError(t, err)
+	assert.True(t, agent.Skills.Enabled())
+	assert.True(t, agent.Skills.HasLocal())
+	assert.Equal(t, []string{"git", "docker"}, agent.Skills.Include)
+}
+
+func TestSkillsConfig_InAgentConfigMixedSourcesAndIncludes(t *testing.T) {
+	yamlInput := `
+model: openai/gpt-4
+skills:
+  - local
+  - https://skills.example.com
+  - git
+toolsets:
+  - type: filesystem
+`
+	var agent AgentConfig
+	err := yaml.Unmarshal([]byte(yamlInput), &agent)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"local", "https://skills.example.com"}, agent.Skills.Sources)
+	assert.Equal(t, []string{"git"}, agent.Skills.Include)
+}
+
+func TestSkillsConfig_EmptyListIsDisabled(t *testing.T) {
+	// An empty list (no sources and no names) means disabled, like `skills: false`.
+	var s SkillsConfig
+	require.NoError(t, yaml.Unmarshal([]byte("[]"), &s))
+	assert.False(t, s.Enabled())
+	assert.Empty(t, s.Include)
+
+	s = SkillsConfig{}
+	require.NoError(t, json.Unmarshal([]byte("[]"), &s))
+	assert.False(t, s.Enabled())
+	assert.Empty(t, s.Include)
+}
+
+func TestSkillsConfig_UnmarshalResetsReceiver(t *testing.T) {
+	// Unmarshaling into an already-populated receiver must not leak previous state.
+	t.Run("bool into populated receiver", func(t *testing.T) {
+		s := SkillsConfig{Sources: []string{"https://old"}, Include: []string{"old"}}
+		require.NoError(t, yaml.Unmarshal([]byte("true"), &s))
+		assert.Equal(t, []string{"local"}, s.Sources)
+		assert.Nil(t, s.Include)
+	})
+	t.Run("list into populated receiver", func(t *testing.T) {
+		s := SkillsConfig{Sources: []string{"https://old"}, Include: []string{"old"}}
+		require.NoError(t, yaml.Unmarshal([]byte("[git]"), &s))
+		assert.Equal(t, []string{"local"}, s.Sources)
+		assert.Equal(t, []string{"git"}, s.Include)
+	})
+	t.Run("false into populated receiver", func(t *testing.T) {
+		s := SkillsConfig{Sources: []string{"https://old"}, Include: []string{"old"}}
+		require.NoError(t, json.Unmarshal([]byte("false"), &s))
+		assert.Nil(t, s.Sources)
+		assert.Nil(t, s.Include)
+	})
+}