Implement remote skills discovery with disk cache and dedicated tools

Add support for remote skill sources via the well-known skills discovery
spec (https://github.com/cloudflare/agent-skills-discovery-rfc). The
skills config now accepts both the existing boolean form and a list of
sources:

  skills: true          # equivalent to ["local"]
  skills:
    - local
    - https://example.com

Remote skills are fetched from /.well-known/skills/index.json, and all
files listed in the index are prefetched into a disk cache under the
XDG cache directory (~/.cache/cagent/skills/ on Linux). Cache-Control
headers are respected for expiry.

Instead of depending on read_file/fetch tools, skills now get their own
dedicated toolset (SkillsToolset) with two tools:
- read_skill: loads a skill's SKILL.md by name
- read_skill_file: loads supporting resources (references, scripts,
  assets) by skill name and relative path

The agent never sees whether a skill is local or remote. The toolset
handles progressive disclosure per the spec: only name+description at
startup, SKILL.md on activation, supporting files on demand.

Other changes:
- Replace Skills *bool config field with SkillsConfig supporting both
  bool and list-of-sources YAML/JSON formats
- Add paths.GetCacheDir() using os.UserCacheDir() for XDG compliance
- Remove skills system prompt injection from session.go (now handled
  by the toolset's Instructable interface)
- Remove filesystem/read_file validation requirement for skills
- Validate skill sources (must be "local" or HTTP/HTTPS URL)

Assisted-By: cagent

Author: rumpl

pkg/agent/agent.go

@@ -38,7 +38,6 @@ type Agent struct {
 	tools                   []tools.Tool
 	commands                types.Commands
 	pendingWarnings         []string
-	skillsEnabled           bool
 	hooks                   *latest.HooksConfig
 	thinkingConfigured      bool // true if thinking_budget was explicitly set in config
 }
@@ -193,11 +192,6 @@ func (a *Agent) Commands() types.Commands {
 	return a.commands
 }
 
-// SkillsEnabled returns whether skills discovery is enabled for this agent.
-func (a *Agent) SkillsEnabled() bool {
-	return a.skillsEnabled
-}
-
 // Hooks returns the hooks configuration for this agent.
 func (a *Agent) Hooks() *latest.HooksConfig {
 	return a.hooks

pkg/agent/opts.go

@@ -147,12 +147,6 @@ func WithLoadTimeWarnings(warnings []string) Opt {
 	}
 }
 
-func WithSkillsEnabled(enabled bool) Opt {
-	return func(a *Agent) {
-		a.skillsEnabled = enabled
-	}
-}
-
 func WithHooks(hooks *latest.HooksConfig) Opt {
 	return func(a *Agent) {
 		a.hooks = hooks

pkg/app/app.go

@@ -172,36 +172,42 @@ func (a *App) CurrentAgentCommands(ctx context.Context) types.Commands {
 
 // CurrentAgentSkills returns the available skills if skills are enabled for the current agent.
 func (a *App) CurrentAgentSkills() []skills.Skill {
-	if a.runtime.CurrentAgentSkillsEnabled() {
-		return skills.Load()
+	st := a.runtime.CurrentAgentSkillsToolset()
+	if st == nil {
+		return nil
 	}
-	return nil
+	return st.Skills()
 }
 
 // ResolveSkillCommand checks if the input matches a skill slash command (e.g. /skill-name args).
-// If matched, it reads the skill file and returns the resolved prompt. Otherwise returns "".
+// If matched, it reads the skill content and returns the resolved prompt. Otherwise returns "".
 func (a *App) ResolveSkillCommand(input string) (string, error) {
 	if !strings.HasPrefix(input, "/") {
 		return "", nil
 	}
 
+	st := a.runtime.CurrentAgentSkillsToolset()
+	if st == nil {
+		return "", nil
+	}
+
 	cmd, arg, _ := strings.Cut(input[1:], " ")
 	arg = strings.TrimSpace(arg)
 
-	for _, skill := range a.CurrentAgentSkills() {
+	for _, skill := range st.Skills() {
 		if skill.Name != cmd {
 			continue
 		}
 
-		content, err := os.ReadFile(skill.FilePath)
+		content, err := st.ReadSkillContent(skill.Name)
 		if err != nil {
 			return "", fmt.Errorf("reading skill %q: %w", skill.Name, err)
 		}
 
 		if arg != "" {
-			return fmt.Sprintf("Use the following skill.\n\nUser's request: %s\n\n<skill name=%q>\n%s\n</skill>", arg, skill.Name, string(content)), nil
+			return fmt.Sprintf("Use the following skill.\n\nUser's request: %s\n\n<skill name=%q>\n%s\n</skill>", arg, skill.Name, content), nil
 		}
-		return fmt.Sprintf("Use the following skill.\n\n<skill name=%q>\n%s\n</skill>", skill.Name, string(content)), nil
+		return fmt.Sprintf("Use the following skill.\n\n<skill name=%q>\n%s\n</skill>", skill.Name, content), nil
 	}
 
 	return "", nil

pkg/app/app_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/docker/cagent/pkg/session"
 	"github.com/docker/cagent/pkg/sessiontitle"
 	"github.com/docker/cagent/pkg/tools"
+	"github.com/docker/cagent/pkg/tools/builtin"
 	mcptools "github.com/docker/cagent/pkg/tools/mcp"
 )
 
@@ -47,7 +48,10 @@ func (m *mockRuntime) SessionStore() session.Store { return nil }
 func (m *mockRuntime) Summarize(ctx context.Context, sess *session.Session, additionalPrompt string, events chan runtime.Event) {
 }
 func (m *mockRuntime) PermissionsInfo() *runtime.PermissionsInfo { return nil }
-func (m *mockRuntime) CurrentAgentSkillsEnabled() bool           { return false }
+func (m *mockRuntime) CurrentAgentSkillsToolset() *builtin.SkillsToolset {
+	return nil
+}
+
 func (m *mockRuntime) CurrentMCPPrompts(context.Context) map[string]mcptools.PromptInfo {
 	return make(map[string]mcptools.PromptInfo)
 }

pkg/config/config.go

@@ -185,43 +185,19 @@ func validateProviderName(name string) error {
 	return nil
 }
 
-// validateSkillsConfiguration ensures that agents with skills enabled have the necessary tools
-func validateSkillsConfiguration(agentName string, agent *latest.AgentConfig) error {
-	// Check if skills are enabled
-	if agent.Skills == nil || !*agent.Skills {
-		return nil
-	}
-
-	// Skills are enabled, validate toolsets
-	hasFilesystemToolset := false
-	hasReadFileTool := false
-
-	for _, toolset := range agent.Toolsets {
-		if toolset.Type == "filesystem" {
-			hasFilesystemToolset = true
-
-			// Check if read_file tool is enabled
-			// If no specific tools are listed, all tools are enabled
-			if len(toolset.Tools) == 0 {
-				hasReadFileTool = true
-				break
-			}
-
-			// Check if read_file is in the tools list
-			if slices.Contains(toolset.Tools, "read_file") {
-				hasReadFileTool = true
-				break
+// validateSkillsConfiguration validates the skills configuration for an agent.
+func validateSkillsConfiguration(_ string, agent *latest.AgentConfig) error {
+	for _, source := range agent.Skills.Sources {
+		switch {
+		case source == latest.SkillSourceLocal:
+			// valid
+		case strings.HasPrefix(source, "http://") || strings.HasPrefix(source, "https://"):
+			if _, err := url.Parse(source); err != nil {
+				return fmt.Errorf("agent '%s' has invalid skills source URL '%s': %w", agent.Name, source, err)
 			}
+		default:
+			return fmt.Errorf("agent '%s' has unknown skills source '%s' (must be 'local' or an HTTP/HTTPS URL)", agent.Name, source)
 		}
 	}
-
-	if !hasFilesystemToolset {
-		return fmt.Errorf("agent '%s' has skills enabled but does not have a 'filesystem' toolset configured", agentName)
-	}
-
-	if !hasReadFileTool {
-		return fmt.Errorf("agent '%s' has skills enabled but the 'filesystem' toolset does not include the 'read_file' tool", agentName)
-	}
-
 	return nil
 }