Merge pull request #55 from neverdie0710/feat/progressive-skill-disclosure

feat: load skill bodies on demand

Author: idoubi

internal/agent/loop.go

@@ -272,6 +272,7 @@ func NewAgentWithSkillsCfg(rc config.ResolvedAgent, prov provider.Provider, mb *
 	// executor-pool failure would silently fall through to /bin/sh on the
 	// host, defeating the security boundary the user asked for.
 	skillDirs := loader.AllSkillDirs()
+	tools.RegisterLoadSkill(registry, skillDirs)
 	var sbCfg *tools.SandboxConfig
 	if rc.Sandbox.Enabled {
 		sbCfg = &tools.SandboxConfig{Enabled: true}
@@ -3083,6 +3084,7 @@ func (a *Agent) refreshSkillsFromStore(userID string) {
 	skills := loader.LoadSkills()
 	summary := loader.BuildSkillsSummary(skills)
 	a.ctxBuilder.SetSkillsSummary(summary)
+	tools.RegisterLoadSkill(a.registry, loader.AllSkillDirs())
 	// Per-turn fingerprint of the skill set the system prompt will
 	// ship. Lets us diff IM vs web for the same (agent, chatter) and
 	// confirm — or rule out — that agent-scope skills are reaching
@@ -3116,6 +3118,7 @@ func (a *Agent) ReloadWorkspaceFiles() {
 	}
 	skills := loader.LoadSkills()
 	skillsSummary := loader.BuildSkillsSummary(skills)
+	tools.RegisterLoadSkill(a.registry, loader.AllSkillDirs())
 	a.ctxBuilder = NewContextBuilder(a.homePath, a.memory, skillsSummary)
 	a.ctxBuilder.SetWorkspace(a.workspacePath)
 	a.ctxBuilder.SetPromptMode(a.promptMode)

internal/agent/skills.go

@@ -20,14 +20,14 @@ import (
 
 // Skill represents a discovered skill.
 type Skill struct {
-	Name        string            // directory name
-	Layer       string            // "agent", "user", "managed", "bundled", "extra"
-	Content     string            // contents of SKILL.md (with {baseDir} replaced)
-	BaseDir     string            // absolute path to the skill directory
-	Description string            // from frontmatter
-	Metadata    *SkillMetadata    // parsed OpenClaw metadata
-	Gated       bool              // true if gating requirements not met
-	GateReason  string            // reason gating failed
+	Name        string         // directory name
+	Layer       string         // "agent", "user", "managed", "bundled", "extra"
+	Content     string         // optional inline SKILL.md content for always-loaded skills
+	BaseDir     string         // absolute path to the skill directory
+	Description string         // from frontmatter
+	Metadata    *SkillMetadata // parsed OpenClaw metadata
+	Gated       bool           // true if gating requirements not met
+	GateReason  string         // reason gating failed
 }
 
 // SkillFrontmatter represents the YAML frontmatter of a SKILL.md file.
@@ -62,12 +62,12 @@ func (m *SkillMetadata) Meta() *OpenClawMeta {
 
 // OpenClawMeta holds OpenClaw-specific metadata.
 type OpenClawMeta struct {
-	Emoji      string           `json:"emoji"`
-	Homepage   string           `json:"homepage"`
-	Always     bool             `json:"always"`
-	OS         []string         `json:"os"`
-	Requires   *SkillRequires   `json:"requires"`
-	PrimaryEnv string           `json:"primaryEnv"`
+	Emoji      string         `json:"emoji"`
+	Homepage   string         `json:"homepage"`
+	Always     bool           `json:"always"`
+	OS         []string       `json:"os"`
+	Requires   *SkillRequires `json:"requires"`
+	PrimaryEnv string         `json:"primaryEnv"`
 	// Env declares configurable environment variables this skill reads.
 	// Surfaced to the admin UI so operators get labeled inputs (with
 	// help text + secret masking) instead of having to grep main.py for
@@ -293,42 +293,66 @@ func (sl *SkillsLoader) LoadSkills() []Skill {
 }
 
 // BuildSkillsSummary returns the skill section of the system prompt.
-// All discovered skills are inlined in full — operators install exactly
-// the skill set they want for their product agent (no marketplace, no
-// lazy load), so the LLM gets the complete SKILL.md content and can
-// invoke each skill directly via exec.
+// Skills use progressive disclosure by default: keep the prompt's always-on
+// context to the small name + description catalog, and let the model call
+// load_skill when it needs the full SKILL.md instructions. Explicit
+// always-load skills remain inline for compatibility with skills that must be
+// present before the first tool call.
 func (sl *SkillsLoader) BuildSkillsSummary(skills []Skill) string {
 	if len(skills) == 0 {
 		return ""
 	}
 	var sb strings.Builder
 	sb.WriteString(skillsDirective)
-	// Quick-reference catalog (name + first-line description) BEFORE
-	// the inline `<skills>` block. The full SKILL.md content can be
-	// 100+ KB total; a tiny name-only index up front lets the model
-	// match "the user said 'use skill X'" against the catalog in one
-	// pass instead of scanning the whole inline section. Catches the
-	// "我手头没有 X" hallucination that showed up in group chats where
-	// attention got diluted by the group_chat block — by the time the
-	// model reached `<skill name="X">`, it had already decided X
-	// didn't exist. Sorted (same order as the inline blocks below)
-	// for diff-friendly logs.
-	sb.WriteString("\n\n<skill_catalog>\nPre-installed skills available to this agent (full SKILL.md content follows below). Treat any user mention of one of these names as a request to invoke that skill via exec:\n")
+	alwaysLoad := sl.alwaysLoadSet()
+	inline := make([]Skill, 0)
+
+	sb.WriteString("\n\n<skill_catalog>\nPre-installed skills available to this agent. Treat any user mention of one of these names as a request to use that skill. Call `load_skill` with the skill name before following its detailed instructions:\n")
 	for _, skill := range skills {
 		desc := firstSentence(skill.Description)
 		if desc == "" {
 			desc = "(no description)"
 		}
 		fmt.Fprintf(&sb, "- %s — %s\n", skill.Name, desc)
+		if alwaysLoad[skill.Name] || skillAlwaysLoads(skill) {
+			inline = append(inline, skill)
+		}
 	}
-	sb.WriteString("</skill_catalog>\n\n<skills>\n")
-	for _, skill := range skills {
-		fmt.Fprintf(&sb, "<skill name=%q layer=%q>\n%s\n</skill>\n", skill.Name, skill.Layer, skill.Content)
+	sb.WriteString("</skill_catalog>")
+
+	if len(inline) > 0 {
+		sb.WriteString("\n\n<always_loaded_skills>\n")
+		for _, skill := range inline {
+			content := skill.Content
+			if content == "" {
+				content = loadSkillContent(skill.BaseDir)
+			}
+			fmt.Fprintf(&sb, "<skill name=%q layer=%q>\n%s\n</skill>\n", skill.Name, skill.Layer, content)
+		}
+		sb.WriteString("</always_loaded_skills>")
 	}
-	sb.WriteString("</skills>")
 	return sb.String()
 }
 
+func (sl *SkillsLoader) alwaysLoadSet() map[string]bool {
+	out := make(map[string]bool, len(sl.skillsCfg.AlwaysLoad)+len(sl.globalCfg.AlwaysLoad))
+	for _, name := range sl.skillsCfg.AlwaysLoad {
+		if name != "" {
+			out[name] = true
+		}
+	}
+	for _, name := range sl.globalCfg.AlwaysLoad {
+		if name != "" {
+			out[name] = true
+		}
+	}
+	return out
+}
+
+func skillAlwaysLoads(skill Skill) bool {
+	return skill.Metadata != nil && skill.Metadata.Meta() != nil && skill.Metadata.Meta().Always
+}
+
 // firstSentence returns the first sentence-ish chunk of s — used for
 // the skill-catalog one-liner. We bound the output to keep the catalog
 // scannable even when a skill's Description is a paragraph: cut at the
@@ -360,13 +384,13 @@ func firstSentence(s string) string {
 // rationalization ("this is one-shot, skip the ladder") that produced
 // reflexive `pip install` calls for tasks a published skill would handle.
 const skillsDirective = `<skill_usage_rules>
-The skills listed below are pre-installed for this agent. Each skill's full SKILL.md is included inline. To invoke one, run its main script via the exec tool and pass arguments on stdin as JSON; the SKILL.md describes args and return shape.
+The skills listed below are pre-installed for this agent. Only the catalog is always in context. Before using a skill, call the "load_skill" tool with its name to load the full SKILL.md instructions, then follow those instructions exactly. If an always-loaded skill is included inline below, you may use those inline instructions directly.
 
 The sandbox image already has: python3 + pip, uv + uvx, node + npm + npx, the camoufox-cli anti-detect browser (run as ` + "`camoufox-cli open <url>`" + ` then ` + "`camoufox-cli snapshot -i`" + ` for refs; Camoufox/Firefox is pre-downloaded), git, curl, requests / pillow / beautifulsoup4 / lxml. DO NOT reinstall any of these — wasted tool calls and timeouts. If you see "command not found", check the spelling before reaching for npm/pip.
 
 HTML preview: when the user asks to see / preview a web artifact, write the final HTML into the workspace and tell them the filename — the chat UI auto-renders .html files in a sandboxed iframe (CSS, JS, images, fonts work; cross-origin fetch from null origin does not). For source projects with a package.json (React, Vue, Vite, Next, …), run the project's build first (` + "`pnpm i && pnpm build`" + ` or the documented command) and point at the resulting ` + "`dist/index.html`" + ` (or equivalent). Live dev servers (` + "`vite dev`" + `, ` + "`next dev`" + `, ` + "`npm run dev`" + `) are NOT reachable from the browser — do not start them; they will hang and waste turns.
 
-When the inline skills don't cover what the user asked for, follow this order BEFORE running any package install (pip / npm / apt / brew / cargo / gem / go install / …) via exec:
+When the listed skills don't cover what the user asked for, follow this order BEFORE running any package install (pip / npm / apt / brew / cargo / gem / go install / …) via exec:
 
 1. If a "find-skills" skill is listed above, run it FIRST to search the open skill ecosystem. If a credible match exists, surface it and offer to install it instead of installing the package yourself.
 2. If no published skill fits, use "skill-creator" (if listed) to scaffold a new skill under skills/<name>/, then invoke it. Prefer this over inline scripts whenever the user might ask the same kind of thing again.
@@ -479,7 +503,9 @@ func userSkillsRootDir(userID string) string {
 }
 
 // discoverSkillsEnhanced scans a directory for skill subdirectories with SKILL.md,
-// parses frontmatter, applies gating, and replaces {baseDir}.
+// parses frontmatter, and applies gating. It deliberately does not keep the
+// full SKILL.md body in memory for default skills; the model loads that body
+// on demand through load_skill.
 func discoverSkillsEnhanced(dir string, layer string) map[string]Skill {
 	result := make(map[string]Skill)
 
@@ -499,7 +525,6 @@ func discoverSkillsEnhanced(dir string, layer string) map[string]Skill {
 			continue
 		}
 
-		content := strings.TrimSpace(string(data))
 		absDir, _ := filepath.Abs(skillDir)
 
 		// Parse frontmatter
@@ -513,9 +538,6 @@ func discoverSkillsEnhanced(dir string, layer string) map[string]Skill {
 			}
 		}
 
-		// Replace {baseDir} with the skill's absolute directory path
-		content = strings.ReplaceAll(content, "{baseDir}", absDir)
-
 		// Apply gating
 		gated, gateReason := checkGating(meta)
 
@@ -528,7 +550,6 @@ func discoverSkillsEnhanced(dir string, layer string) map[string]Skill {
 		result[name] = Skill{
 			Name:        name,
 			Layer:       layer,
-			Content:     content,
 			BaseDir:     absDir,
 			Description: desc,
 			Metadata:    meta,
@@ -540,6 +561,15 @@ func discoverSkillsEnhanced(dir string, layer string) map[string]Skill {
 	return result
 }
 
+func loadSkillContent(skillDir string) string {
+	data, err := os.ReadFile(filepath.Join(skillDir, "SKILL.md"))
+	if err != nil {
+		return ""
+	}
+	content := strings.TrimSpace(string(data))
+	return strings.ReplaceAll(content, "{baseDir}", skillDir)
+}
+
 func mapKeys(m map[string]map[string]config.SkillEntryCfg) []string {
 	out := make([]string, 0, len(m))
 	for k := range m {

internal/agent/skills_test.go

@@ -0,0 +1,104 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/fastclaw-ai/fastclaw/internal/config"
+)
+
+func TestBuildSkillsSummaryUsesProgressiveDisclosureByDefault(t *testing.T) {
+	t.Setenv("FASTCLAW_HOME", t.TempDir())
+	home := t.TempDir()
+	skillDir := filepath.Join(home, "skills", "chart-maker")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `---
+name: chart-maker
+description: Build charts from tabular data.
+---
+
+SECRET_INLINE_BODY_SHOULD_NOT_APPEAR
+Run scripts/render.py with JSON input.`
+	if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	loader := NewSkillsLoaderWithGlobal(home, t.TempDir(), "", config.SkillsConfig{}, config.SkillsCfg{})
+	summary := loader.BuildSkillsSummary(loader.LoadSkills())
+
+	if !strings.Contains(summary, "chart-maker") {
+		t.Fatalf("summary missing skill name:\n%s", summary)
+	}
+	if !strings.Contains(summary, "Build charts from tabular data") {
+		t.Fatalf("summary missing skill description:\n%s", summary)
+	}
+	if strings.Contains(summary, "SECRET_INLINE_BODY_SHOULD_NOT_APPEAR") {
+		t.Fatalf("summary leaked SKILL.md body:\n%s", summary)
+	}
+	if !strings.Contains(summary, "load_skill") {
+		t.Fatalf("summary should tell the model to call load_skill:\n%s", summary)
+	}
+}
+
+func TestLoadSkillsDoesNotKeepBodyContentByDefault(t *testing.T) {
+	t.Setenv("FASTCLAW_HOME", t.TempDir())
+	home := t.TempDir()
+	skillDir := filepath.Join(home, "skills", "chart-maker")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `---
+name: chart-maker
+description: Build charts from tabular data.
+---
+
+BODY_SHOULD_STAY_ON_DISK_UNTIL_LOAD_SKILL`
+	if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	loader := NewSkillsLoaderWithGlobal(home, t.TempDir(), "", config.SkillsConfig{}, config.SkillsCfg{})
+	skills := loader.LoadSkills()
+
+	if len(skills) != 1 {
+		t.Fatalf("skills len = %d, want 1", len(skills))
+	}
+	if skills[0].Content != "" {
+		t.Fatalf("LoadSkills should not keep default skill body in memory, got:\n%s", skills[0].Content)
+	}
+}
+
+func TestBuildSkillsSummaryKeepsAlwaysLoadSkillsInline(t *testing.T) {
+	t.Setenv("FASTCLAW_HOME", t.TempDir())
+	home := t.TempDir()
+	skillDir := filepath.Join(home, "skills", "always-inline")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `---
+name: always-inline
+description: Needs full instructions immediately.
+---
+
+ALWAYS_LOAD_BODY_SHOULD_APPEAR`
+	if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	loader := NewSkillsLoaderWithGlobal(
+		home,
+		t.TempDir(),
+		"",
+		config.SkillsConfig{AlwaysLoad: []string{"always-inline"}},
+		config.SkillsCfg{},
+	)
+	summary := loader.BuildSkillsSummary(loader.LoadSkills())
+
+	if !strings.Contains(summary, "ALWAYS_LOAD_BODY_SHOULD_APPEAR") {
+		t.Fatalf("summary should inline explicitly always-loaded skill:\n%s", summary)
+	}
+}

internal/agent/tools/load_skill.go

@@ -6,14 +6,15 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 )
 
 type loadSkillArgs struct {
 	Name string `json:"name"`
 }
 
 // RegisterLoadSkill registers the load_skill tool that reads full SKILL.md content.
-func RegisterLoadSkill(r *Registry, homeDir, agentDir, teamDir string) {
+func RegisterLoadSkill(r *Registry, skillDirs []string) {
 	r.Register("load_skill", "Load the full content of a skill by name. Use this when you need detailed instructions for a specific skill.", map[string]interface{}{
 		"type": "object",
 		"properties": map[string]interface{}{
@@ -23,19 +24,10 @@ func RegisterLoadSkill(r *Registry, homeDir, agentDir, teamDir string) {
 			},
 		},
 		"required": []string{"name"},
-	}, makeLoadSkill(homeDir, agentDir, teamDir))
+	}, makeLoadSkill(skillDirs))
 }
 
-func makeLoadSkill(homeDir, agentDir, teamDir string) ToolFunc {
-	// Directories to search in priority order (agent > team > global)
-	searchDirs := []string{
-		filepath.Join(agentDir, "skills"),
-	}
-	if teamDir != "" {
-		searchDirs = append(searchDirs, filepath.Join(teamDir, "skills"))
-	}
-	searchDirs = append(searchDirs, filepath.Join(homeDir, "skills"))
-
+func makeLoadSkill(skillDirs []string) ToolFunc {
 	return func(ctx context.Context, rawArgs json.RawMessage) (string, error) {
 		var args loadSkillArgs
 		if err := json.Unmarshal(rawArgs, &args); err != nil {
@@ -47,11 +39,16 @@ func makeLoadSkill(homeDir, agentDir, teamDir string) ToolFunc {
 		}
 
 		// Search through directories in priority order
-		for _, dir := range searchDirs {
+		for _, dir := range skillDirs {
+			if dir == "" {
+				continue
+			}
 			skillPath := filepath.Join(dir, args.Name, "SKILL.md")
 			data, err := os.ReadFile(skillPath)
 			if err == nil {
-				return wrapSkillContentInternal(args.Name, string(data)), nil
+				skillDir, _ := filepath.Abs(filepath.Join(dir, args.Name))
+				content := strings.ReplaceAll(string(data), "{baseDir}", skillDir)
+				return wrapSkillContentInternal(args.Name, content), nil
 			}
 		}