🎨 Support loading bundled Skill resource files (#19031)

* ✨ Support bundled Skill resources

* 🎨 Clarify Skill resource variable handling

* 🐛 Reject non-UTF-8 skill resources

Author: frostime

kernel/mcp/server_test.go

@@ -22,11 +22,14 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
 	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/siyuan-note/siyuan/kernel/mcp/tools"
+	"github.com/siyuan-note/siyuan/kernel/util"
 )
 
 func newTestHTTPServer(t *testing.T) (*mcpsdk.Server, *httptest.Server) {
@@ -392,6 +395,44 @@ func TestToolInputAndOutputValidation(t *testing.T) {
 	}
 }
 
+func TestSkillResourceContentSurvivesMCPConversion(t *testing.T) {
+	originalDataDir, originalHomeDir := util.DataDir, util.HomeDir
+	root := t.TempDir()
+	util.DataDir = filepath.Join(root, "workspace", "data")
+	util.HomeDir = filepath.Join(root, "home")
+	t.Cleanup(func() {
+		util.DataDir, util.HomeDir = originalDataDir, originalHomeDir
+	})
+
+	skillDir := filepath.Join(util.SkillsDir(), "transport-skill")
+	if err := os.MkdirAll(filepath.Join(skillDir, "references"), 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"),
+		[]byte("---\nname: transport-skill\ndescription: transport test\n---\nbody"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(skillDir, "references", "valid.txt"), []byte("中文内容"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	result, err := tools.SkillTool.Handler(map[string]any{
+		"action": "load",
+		"name":   "transport-skill/references/valid.txt",
+	})
+	if err != nil || result.IsError || len(result.Content) != 1 {
+		t.Fatalf("unexpected Skill resource result: %#v, %v", result, err)
+	}
+	converted, err := convertContentItem(result.Content[0])
+	if err != nil {
+		t.Fatal(err)
+	}
+	text, ok := converted.(*mcpsdk.TextContent)
+	if !ok || text.Text != "<skill_resource skill=\"transport-skill\" path=\"references/valid.txt\">\n\n中文内容\n\n</skill_resource>" {
+		t.Fatalf("Skill resource changed during MCP conversion: %#v", converted)
+	}
+}
+
 func TestNonTextToolContentIsPreserved(t *testing.T) {
 	server, httpServer := newTestHTTPServer(t)
 	var imageContent tools.ContentItem

kernel/mcp/tools/skill.go

@@ -19,6 +19,7 @@ package tools
 import (
 	"fmt"
 	"html"
+	"path/filepath"
 	"strings"
 
 	"github.com/siyuan-note/siyuan/kernel/model"
@@ -27,12 +28,15 @@ import (
 
 var SkillTool = &Tool{
 	Name:        "skill",
-	Description: "Skill operations: load(name), save(name, content), install(url), remove(name), rename(name, new_name), list().\n\n" + skillListDesc(),
+	Description: "Skill operations: load(name) loads Skill instructions; load(name/resource-path) loads a bundled text resource; save(name, content), install(url), remove(name), rename(name, new_name), list().\n\n" + skillListDesc(),
 	InputSchema: ToolSchema{
 		Type: "object",
 		Properties: map[string]Property{
-			"action":   {Type: "string", Description: "Operation", Enum: []string{"load", "save", "install", "remove", "rename", "list"}},
-			"name":     {Type: "string", Description: "Skill name (directory name)"},
+			"action": {Type: "string", Description: "Operation", Enum: []string{"load", "save", "install", "remove", "rename", "list"}},
+			"name": {
+				Type:        "string",
+				Description: "Skill name. For load, use <skill-name> for instructions or <skill-name>/<relative-resource-path> for a bundled text resource",
+			},
 			"content":  {Type: "string", Description: "SKILL.md full content with YAML frontmatter (for save)"},
 			"url":      {Type: "string", Description: "Skill source for install: 'owner/repo' shorthand (e.g. Tencent/WeChatReading), a full GitHub URL, a raw SKILL.md URL, or a release zip URL"},
 			"new_name": {Type: "string", Description: "New skill name (for rename)"},
@@ -87,23 +91,78 @@ func skillLoad(args map[string]any) (CallToolResult, error) {
 		}, nil
 	}
 
-	content := util.LoadSkillContent(name, model.EnabledUserSkills())
-	if content == "" {
+	loaded, err := util.LoadSkill(name, model.EnabledUserSkills())
+	if err != nil {
 		return CallToolResult{
-			Content: []ContentItem{{Type: "text", Text: fmt.Sprintf("skill not found: %s", name)}},
+			Content: []ContentItem{{Type: "text", Text: err.Error()}},
 			IsError: true,
 		}, nil
 	}
 
-	// 变量（非敏感）在技能正文注入对话时解析，让 LLM 看到实际值；密钥不进上下文。
-	content = model.Conf.Variables.Resolve(content)
-
-	result := "<skill_content name=\"" + html.EscapeString(name) + "\">\n\n" + content + "\n\n</skill_content>"
+	var result string
+	if loaded.ResourcePath == "" {
+		// Variables.Resolve 还会匹配 $NAME 和 ${NAME}。
+		// 资源可能包含脚本或模板，因此只解析技能正文，避免误改资源内容。
+		loaded.Content = model.Conf.Variables.Resolve(loaded.Content)
+		result = formatSkillContent(loaded)
+	} else {
+		result = formatSkillResource(loaded)
+	}
 	return CallToolResult{
 		Content: []ContentItem{{Type: "text", Text: result}},
 	}, nil
 }
 
+func formatSkillContent(loaded *util.SkillLoadResult) string {
+	var sb strings.Builder
+	sb.WriteString(`<skill_content name="`)
+	sb.WriteString(html.EscapeString(loaded.Name))
+	sb.WriteString("\">\n\n")
+	sb.WriteString(loaded.Content)
+
+	if len(loaded.Resources) > 0 || loaded.ResourcesTruncated {
+		sb.WriteString("\n\n<skill_resources")
+		if loaded.ResourcesTruncated {
+			sb.WriteString(` truncated="true"`)
+		}
+		sb.WriteString(">\n")
+		for _, resource := range loaded.Resources {
+			sb.WriteString("  <file>")
+			sb.WriteString(html.EscapeString(resource))
+			sb.WriteString("</file>\n")
+		}
+		sb.WriteString("</skill_resources>")
+	}
+
+	if location := workspaceSkillLocation(loaded.SkillDir); location != "" {
+		sb.WriteString("\n\n<skill_location path=\"")
+		sb.WriteString(html.EscapeString(location))
+		sb.WriteString("\">\n")
+		sb.WriteString("  For this skill directory, use the `file` tool's read-only actions: `read`, `list`, `grep`, and `find`.\n")
+		sb.WriteString("</skill_location>")
+	}
+
+	sb.WriteString("\n\n</skill_content>")
+	return sb.String()
+}
+
+func formatSkillResource(loaded *util.SkillLoadResult) string {
+	return `<skill_resource skill="` + html.EscapeString(loaded.Name) + `" path="` +
+		html.EscapeString(loaded.ResourcePath) + "\">\n\n" + loaded.Content + "\n\n</skill_resource>"
+}
+
+func workspaceSkillLocation(skillDir string) string {
+	location, err := filepath.Rel(util.WorkspaceDir, skillDir)
+	if err != nil {
+		return ""
+	}
+	location = filepath.ToSlash(location)
+	if _, err = resolvePath(location); err != nil {
+		return ""
+	}
+	return location
+}
+
 func skillSave(args map[string]any) (CallToolResult, error) {
 	name, _ := args["name"].(string)
 	if name == "" {

kernel/mcp/tools/skill_test.go

@@ -0,0 +1,119 @@
+// SiYuan - From thought to insight, with agents
+// Copyright (c) 2020-present, b3log.org
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+package tools
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	kernelConf "github.com/siyuan-note/siyuan/kernel/conf"
+	"github.com/siyuan-note/siyuan/kernel/model"
+	"github.com/siyuan-note/siyuan/kernel/util"
+)
+
+func setSkillToolTestEnvironment(t *testing.T) string {
+	t.Helper()
+	originalWorkspaceDir, originalDataDir := util.WorkspaceDir, util.DataDir
+	originalHomeDir, originalConfDir := util.HomeDir, util.ConfDir
+	originalConf := model.Conf
+
+	root := t.TempDir()
+	util.WorkspaceDir = filepath.Join(root, "workspace")
+	util.DataDir = filepath.Join(util.WorkspaceDir, "data")
+	util.HomeDir = filepath.Join(root, "home")
+	util.ConfDir = filepath.Join(util.WorkspaceDir, "conf")
+	model.Conf = model.NewAppConf()
+	model.Conf.Variables = &kernelConf.Variables{Items: []*kernelConf.Variable{{Name: "VALUE", Value: "resolved"}}}
+	t.Cleanup(func() {
+		util.WorkspaceDir, util.DataDir = originalWorkspaceDir, originalDataDir
+		util.HomeDir, util.ConfDir = originalHomeDir, originalConfDir
+		model.Conf = originalConf
+	})
+	return util.SkillsDir()
+}
+
+func writeSkillToolTestFile(t *testing.T, file, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(file), 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(file, []byte(content), 0644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestSkillLoadResolvesVariablesOnlyInInstructions(t *testing.T) {
+	skillsRoot := setSkillToolTestEnvironment(t)
+	skillDir := filepath.Join(skillsRoot, "skill-dir")
+	writeSkillToolTestFile(t, filepath.Join(skillDir, "SKILL.md"),
+		"---\nname: A&B\ndescription: description\n---\nbody {{vars.VALUE}}")
+	writeSkillToolTestFile(t, filepath.Join(skillDir, "references", "spec&notes.md"), "{{vars.VALUE}}\n")
+
+	activation, err := skillLoad(map[string]any{"name": "A&B"})
+	if err != nil || activation.IsError {
+		t.Fatalf("skillLoad(activation) = %#v, %v", activation, err)
+	}
+	activationText := activation.Content[0].Text
+	for _, expected := range []string{
+		`<skill_content name="A&amp;B">`,
+		"body resolved",
+		"<file>references/spec&amp;notes.md</file>",
+		`<skill_location path="data/storage/ai/agent/skills/skill-dir">`,
+		"use the `file` tool's read-only actions: `read`, `list`, `grep`, and `find`",
+	} {
+		if !strings.Contains(activationText, expected) {
+			t.Errorf("activation output is missing %q:\n%s", expected, activationText)
+		}
+	}
+
+	resource, err := skillLoad(map[string]any{"name": "A&B/references/spec&notes.md"})
+	if err != nil || resource.IsError {
+		t.Fatalf("skillLoad(resource) = %#v, %v", resource, err)
+	}
+	resourceText := resource.Content[0].Text
+	if !strings.Contains(resourceText, `<skill_resource skill="A&amp;B" path="references/spec&amp;notes.md">`) ||
+		!strings.Contains(resourceText, "{{vars.VALUE}}") {
+		t.Fatalf("unexpected resource output:\n%s", resourceText)
+	}
+	for _, excluded := range []string{"<skill_resources", "<skill_location", "resolved"} {
+		if strings.Contains(resourceText, excluded) {
+			t.Errorf("resource output unexpectedly contains %q:\n%s", excluded, resourceText)
+		}
+	}
+
+	truncated := formatSkillContent(&util.SkillLoadResult{Name: "truncated", ResourcesTruncated: true})
+	if !strings.Contains(truncated, `<skill_resources truncated="true">`) {
+		t.Fatalf("truncated empty manifest is not reported:\n%s", truncated)
+	}
+}
+
+func TestSkillContentOmitsLocationForWorkspaceSymlinkEscape(t *testing.T) {
+	skillsRoot := setSkillToolTestEnvironment(t)
+	externalSkill := filepath.Join(t.TempDir(), "external-skill")
+	writeSkillToolTestFile(t, filepath.Join(externalSkill, "SKILL.md"),
+		"---\nname: external\ndescription: description\n---\nbody")
+	if err := os.MkdirAll(skillsRoot, 0755); err != nil {
+		t.Fatal(err)
+	}
+	linkedSkill := filepath.Join(skillsRoot, "external")
+	if err := os.Symlink(externalSkill, linkedSkill); err != nil {
+		t.Skipf("symlinks are unavailable: %v", err)
+	}
+
+	loaded, err := util.LoadSkill("external", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	output := formatSkillContent(loaded)
+	if strings.Contains(output, "<skill_location") {
+		t.Fatalf("symlinked external skill exposed a file location:\n%s", output)
+	}
+}