Validate plugin content files in CLI

Author: SqlRush

cmd/claude/main.go

@@ -506,7 +506,17 @@ func runPluginValidateCLI(state *bootstrap.State, args []string, stdout io.Write
 		return 2
 	}
 	writePluginValidationResult(stdout, result)
-	if !result.Success {
+	allSuccess := result.Success
+	if pluginRoot, ok := pluginCLIValidationContentRoot(result); ok {
+		for _, contentResult := range pluginpkg.ValidatePluginContents(pluginRoot) {
+			fmt.Fprintln(stdout)
+			writePluginValidationResult(stdout, contentResult)
+			if !contentResult.Success {
+				allSuccess = false
+			}
+		}
+	}
+	if !allSuccess {
 		return 1
 	}
 	return 0
@@ -887,7 +897,7 @@ func writePluginUninstallResult(stdout io.Writer, result pluginpkg.PluginUninsta
 
 func writePluginValidationResult(stdout io.Writer, result pluginpkg.ManifestValidationResult) {
 	lines := []string{
-		fmt.Sprintf("Validating %s manifest: %s", result.FileType, result.FilePath),
+		pluginCLIValidationHeader(result),
 		"",
 	}
 	if len(result.Errors) > 0 {
@@ -958,6 +968,26 @@ func pluginCLIValidationMessagePath(path string) string {
 	return path
 }
 
+func pluginCLIValidationHeader(result pluginpkg.ManifestValidationResult) string {
+	switch result.FileType {
+	case "plugin", "marketplace":
+		return fmt.Sprintf("Validating %s manifest: %s", result.FileType, result.FilePath)
+	default:
+		return fmt.Sprintf("Validating %s: %s", result.FileType, result.FilePath)
+	}
+}
+
+func pluginCLIValidationContentRoot(result pluginpkg.ManifestValidationResult) (string, bool) {
+	if result.FileType != "plugin" {
+		return "", false
+	}
+	manifestDir := filepath.Dir(result.FilePath)
+	if !strings.EqualFold(filepath.Base(manifestDir), ".claude-plugin") {
+		return "", false
+	}
+	return filepath.Dir(manifestDir), true
+}
+
 func pluginCLISettingsFromFiles(cwd string) (contracts.Settings, error) {
 	userSettings, err := pluginCLILoadOptionalSettings(config.UserSettingsPath())
 	if err != nil {

cmd/claude/main_test.go

@@ -2202,6 +2202,54 @@ func TestRunPluginValidateCLI(t *testing.T) {
 			t.Fatalf("stdout missing %q: %q", want, stdout.String())
 		}
 	}
+
+	officialPlugin := filepath.Join(project, "official-plugin")
+	officialManifestDir := filepath.Join(officialPlugin, ".claude-plugin")
+	if err := os.MkdirAll(officialManifestDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	expectedOfficialManifestDir, err := filepath.EvalSymlinks(officialManifestDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(officialPlugin, "skills", "audit"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(officialPlugin, "hooks"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(officialManifestDir, "plugin.json"), []byte(`{
+		"name": "official-plugin",
+		"version": "1.0.0",
+		"description": "Official layout plugin",
+		"author": {"name": "Team"}
+	}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(officialPlugin, "skills", "audit", "SKILL.md"), []byte("Audit."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(officialPlugin, "hooks", "hooks.json"), []byte(`{"hooks":`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	stdout.Reset()
+	stderr.Reset()
+	code = run([]string{"--cwd", project, "plugin", "validate", "official-plugin"}, strings.NewReader(""), &stdout, &stderr)
+	if code != 1 {
+		t.Fatalf("exit=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	for _, want := range []string{
+		"Validating plugin manifest: " + filepath.Join(expectedOfficialManifestDir, "plugin.json"),
+		"Validating skill:",
+		"frontmatter: No frontmatter block found",
+		"Validating hooks:",
+		"json: Invalid JSON syntax",
+		"Validation failed",
+	} {
+		if !strings.Contains(stdout.String(), want) {
+			t.Fatalf("stdout missing %q: %q", want, stdout.String())
+		}
+	}
 }
 
 func TestRunPluginUninstallCLI(t *testing.T) {

docs/cc-100-roadmap.md

@@ -43,7 +43,7 @@ M8 补充：`/plugin help|--help|-h` 已输出官方插件命令用法，`/plugi
 
 M8 补充：`/plugin uninstall|remove|rm [--scope project|user|local] <plugin>` 已接入 no-query 安全卸载路径，只允许删除 installed plugin directory 枚举出的插件 root，输出 removed path/scope/status，并刷新 plugin MCP server app-state。
 
-M8 补充：`/plugin validate <path>` 与 CLI `plugin validate <path>` 已接入共享 manifest 验证 API，支持官方 `.claude-plugin/marketplace.json` 优先目录检测、`.claude-plugin/plugin.json`、当前 Go root `marketplace.json`/`plugin.json` 兼容、未知文件内容推断、JSON/类型/unknown-key/path-traversal 诊断、plugin author/version/description/kebab-case warning 和 marketplace plugin count/duplicate/source 诊断；slash 路径不请求模型。
+M8 补充：`/plugin validate <path>` 与 CLI `plugin validate <path>` 已接入共享 manifest 验证 API，支持官方 `.claude-plugin/marketplace.json` 优先目录检测、`.claude-plugin/plugin.json`、当前 Go root `marketplace.json`/`plugin.json` 兼容、未知文件内容推断、JSON/类型/unknown-key/path-traversal 诊断、plugin author/version/description/kebab-case warning 和 marketplace plugin count/duplicate/source 诊断；CLI 在官方 `.claude-plugin/plugin.json` 布局下还会扫描默认 skills/agents/commands markdown frontmatter 和 hooks/hooks.json；slash 路径不请求模型。
 
 M8 补充：CLI `plugin uninstall|remove|rm [--scope user|project|local] [--keep-data] <plugin>` 现在复用共享安全卸载 API，默认按官方 CLI 使用 user scope，输出 removed path/scope/status，并保留 `--keep-data` 兼容参数。
 

docs/claude-code-go-rewrite-plan.md

@@ -899,7 +899,7 @@ test/parity/                 # golden tests against TS/official behavior
 
 - 本轮补充：`/plugin help|--help|-h` 现在输出官方 Plugin Command Usage 文案，`/plugin manage` 复用已安装 plugin summary，`/plugin i` 作为 install alias 接入同一安装路径，builtin command registry 同步声明官方 `/plugins` 与 `/marketplace` 顶层别名。
 - 本轮补充：`/plugin uninstall|remove|rm [--scope project|user|local] <plugin>` 现在有 no-query 安全卸载路径，只删除 installed plugin directory 枚举出的插件 root，输出 removed path/scope/status，并刷新 plugin MCP server app-state。
-- 本轮补充：`/plugin validate <path>` 现在走 no-query 本地 manifest 验证路径，并与 CLI `plugin validate <path>` 共享 `internal/plugins` 验证 API；目录输入会按官方优先级检测 `.claude-plugin/marketplace.json` 再 `.claude-plugin/plugin.json`，同时兼容当前 Go root `marketplace.json`/`plugin.json` 布局，输出 JSON/类型/unknown-key/path-traversal 诊断、plugin warning 和 marketplace plugin summary。
+- 本轮补充：`/plugin validate <path>` 现在走 no-query 本地 manifest 验证路径，并与 CLI `plugin validate <path>` 共享 `internal/plugins` 验证 API；目录输入会按官方优先级检测 `.claude-plugin/marketplace.json` 再 `.claude-plugin/plugin.json`，同时兼容当前 Go root `marketplace.json`/`plugin.json` 布局，输出 JSON/类型/unknown-key/path-traversal 诊断、plugin warning 和 marketplace plugin summary；CLI 在官方 `.claude-plugin/plugin.json` 布局下还会扫描默认 skills/agents/commands markdown frontmatter 和 hooks/hooks.json。
 - 本轮补充：CLI `plugin uninstall|remove|rm [--scope user|project|local] [--keep-data] <plugin>` 现在复用共享安全卸载 API，默认 user scope，支持 remove/rm alias 和 `--keep-data` 兼容参数。
 
 - 本轮补充：bridge-safe 内置本地命令 `/summary`、`/release-notes`、`/files` 现在已注册并接入 no-query runner 路径；`/summary` 输出确定性的会话/历史消息计数、工具使用计数、估算 token 和最近用户/助手预览，`/files` 只读列出当前工作目录第一层条目而不读取文件内容，`/release-notes` 明确报告当前 Go runtime 未打包 release notes。完整 local-jsx UI surface 和其它本地命令 parity 仍需继续补。

docs/first-second-parity-audit.md

@@ -89,7 +89,7 @@ Anthropic API 和 conversation：
 - `/mcp <server-name>` now takes the no-query local server-detail path used by `/mcp show <server-name>` when the name matches a configured settings or plugin MCP server, while unknown one-word subcommands still report unsupported.
 - `/plugin help|--help|-h` now returns the official plugin command usage text without querying the model, `/plugin manage` reuses the installed-plugin summary path, `/plugin i` aliases install, and the built-in command registry now exposes the official `/plugins` and `/marketplace` aliases.
 - `/plugin uninstall|remove|rm [--scope project|user|local] <plugin>` now takes a no-query safe uninstall path that only removes plugin roots discovered from installed plugin directories, reports removed path/scope, and refreshes plugin MCP server app-state.
-- `/plugin validate <path>` now takes a no-query local validation path backed by a shared plugin manifest validator also used by CLI `plugin validate <path>`, covering official `.claude-plugin` marketplace/plugin directory detection, current Go root manifest layouts, JSON/type/unknown-key/path-traversal diagnostics, common plugin warnings, and marketplace entry summaries.
+- `/plugin validate <path>` now takes a no-query local validation path backed by a shared plugin manifest validator also used by CLI `plugin validate <path>`, covering official `.claude-plugin` marketplace/plugin directory detection, current Go root manifest layouts, JSON/type/unknown-key/path-traversal diagnostics, common plugin warnings, marketplace entry summaries, and CLI-side official-layout content scans for skills/agents/commands frontmatter plus hooks/hooks.json.
 - CLI `plugin uninstall|remove|rm [--scope user|project|local] [--keep-data] <plugin>` now reuses the same safe uninstall API, defaults to user scope like the official CLI, and reports removed path/scope/status.
 - `/plugin <plugin-name>` now takes the no-query local plugin-detail path used by `/plugin show <plugin-name>` when the name matches a local plugin manifest, while unknown one-word subcommands still report unsupported.
 - `/model show`, `/model info`, and `/model current` now take the no-query current-model path instead of treating those words as custom model names and mutating the runner model.

internal/conversation/run.go

@@ -3581,7 +3581,7 @@ func (r Runner) validatePluginSummary(path string) string {
 
 func formatPluginValidationResult(result pluginpkg.ManifestValidationResult) string {
 	lines := []string{
-		fmt.Sprintf("Validating %s manifest: %s", result.FileType, result.FilePath),
+		pluginValidationHeader(result),
 		"",
 	}
 	if len(result.Errors) > 0 {
@@ -3636,6 +3636,15 @@ func formatPluginValidationResult(result pluginpkg.ManifestValidationResult) str
 	return strings.TrimRight(strings.Join(lines, "\n"), "\n")
 }
 
+func pluginValidationHeader(result pluginpkg.ManifestValidationResult) string {
+	switch result.FileType {
+	case "plugin", "marketplace":
+		return fmt.Sprintf("Validating %s manifest: %s", result.FileType, result.FilePath)
+	default:
+		return fmt.Sprintf("Validating %s: %s", result.FileType, result.FilePath)
+	}
+}
+
 func pluginValidationPlural(count int, singular string) string {
 	if count == 1 {
 		return singular

internal/plugins/validate.go

@@ -7,6 +7,8 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+
+	"ccgo/internal/memory"
 )
 
 type ManifestValidationMessage struct {
@@ -26,6 +28,32 @@ type ManifestValidationResult struct {
 	MarketplaceIDs []string
 }
 
+func ValidatePluginContents(pluginDir string) []ManifestValidationResult {
+	pluginDir = cleanAbs(pluginDir)
+	var results []ManifestValidationResult
+	for _, item := range []struct {
+		fileType string
+		dir      string
+		skills   bool
+	}{
+		{fileType: "skill", dir: filepath.Join(pluginDir, "skills"), skills: true},
+		{fileType: "agent", dir: filepath.Join(pluginDir, "agents")},
+		{fileType: "command", dir: filepath.Join(pluginDir, "commands")},
+	} {
+		for _, path := range collectPluginMarkdownFiles(item.dir, item.skills) {
+			result := validatePluginComponentFile(path, item.fileType)
+			if len(result.Errors) > 0 || len(result.Warnings) > 0 {
+				results = append(results, result)
+			}
+		}
+	}
+	hooksResult, ok := validatePluginHooksJSON(filepath.Join(pluginDir, "hooks", "hooks.json"))
+	if ok {
+		results = append(results, hooksResult)
+	}
+	return results
+}
+
 func ValidateManifestPath(path string, cwd string) (ManifestValidationResult, error) {
 	path = strings.TrimSpace(path)
 	if path == "" {
@@ -498,3 +526,100 @@ func stringFromValidationMap(values map[string]any, key string) string {
 	value, _ := values[key].(string)
 	return strings.TrimSpace(value)
 }
+
+func collectPluginMarkdownFiles(dir string, skills bool) []string {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil
+	}
+	sort.SliceStable(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
+	var out []string
+	if skills {
+		for _, entry := range entries {
+			if entry.IsDir() {
+				path := filepath.Join(dir, entry.Name(), "SKILL.md")
+				if info, err := os.Stat(path); err == nil && !info.IsDir() {
+					out = append(out, path)
+				}
+			}
+		}
+		return out
+	}
+	for _, entry := range entries {
+		path := filepath.Join(dir, entry.Name())
+		if entry.IsDir() {
+			out = append(out, collectPluginMarkdownFiles(path, false)...)
+			continue
+		}
+		if entry.Type().IsRegular() && strings.EqualFold(filepath.Ext(entry.Name()), ".md") {
+			out = append(out, path)
+		}
+	}
+	return out
+}
+
+func validatePluginComponentFile(path string, fileType string) ManifestValidationResult {
+	result := ManifestValidationResult{
+		Success:  true,
+		FilePath: cleanAbs(path),
+		FileType: fileType,
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		result.Success = false
+		result.Errors = append(result.Errors, ManifestValidationMessage{Path: "file", Message: "Failed to read: " + err.Error()})
+		return result
+	}
+	content := string(data)
+	if !strings.HasPrefix(strings.TrimLeft(content, "\ufeff"), "---") {
+		result.Warnings = append(result.Warnings, ManifestValidationMessage{Path: "frontmatter", Message: "No frontmatter block found. Add YAML frontmatter between --- delimiters at the top of the file to set description and other metadata."})
+		return result
+	}
+	frontmatter, body := memory.ParseFrontmatter(content)
+	if body == "" && len(frontmatter) == 0 {
+		result.Success = false
+		result.Errors = append(result.Errors, ManifestValidationMessage{Path: "frontmatter", Message: "Frontmatter block is not closed or could not be parsed."})
+		return result
+	}
+	if strings.TrimSpace(frontmatter["description"]) == "" {
+		result.Warnings = append(result.Warnings, ManifestValidationMessage{Path: "description", Message: fmt.Sprintf("No description in frontmatter. A description helps users and Claude understand when to use this %s.", fileType)})
+	}
+	if shell := strings.TrimSpace(frontmatter["shell"]); shell != "" {
+		normalized := strings.ToLower(shell)
+		if normalized != "bash" && normalized != "powershell" {
+			result.Success = false
+			result.Errors = append(result.Errors, ManifestValidationMessage{Path: "shell", Message: fmt.Sprintf("shell must be 'bash' or 'powershell', got %q.", shell)})
+		}
+	}
+	result.Success = len(result.Errors) == 0
+	return result
+}
+
+func validatePluginHooksJSON(path string) (ManifestValidationResult, bool) {
+	result := ManifestValidationResult{
+		Success:  true,
+		FilePath: cleanAbs(path),
+		FileType: "hooks",
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return ManifestValidationResult{}, false
+		}
+		result.Success = false
+		result.Errors = append(result.Errors, ManifestValidationMessage{Path: "file", Message: "Failed to read file: " + err.Error()})
+		return result, true
+	}
+	var raw any
+	if err := json.Unmarshal(data, &raw); err != nil {
+		result.Success = false
+		result.Errors = append(result.Errors, ManifestValidationMessage{Path: "json", Message: "Invalid JSON syntax: " + err.Error() + ". At runtime this breaks the entire plugin load."})
+		return result, true
+	}
+	if hooks := rawHooksFromAny(raw); len(hooks) == 0 {
+		result.Success = false
+		result.Errors = append(result.Errors, ManifestValidationMessage{Path: "hooks", Message: "hooks.json must contain a hooks object with at least one hook event."})
+		return result, true
+	}
+	return result, false
+}

internal/plugins/validate_test.go

@@ -136,6 +136,42 @@ func TestValidateManifestPathReportsWarningsAndTraversal(t *testing.T) {
 	}
 }
 
+func TestValidatePluginContentsReportsComponentWarningsAndHookErrors(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "skills", "audit"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "commands"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(root, "hooks"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "skills", "audit", "SKILL.md"), []byte("Audit."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "commands", "deploy.md"), []byte("---\nshell: fish\n---\nDeploy."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "hooks", "hooks.json"), []byte(`{"hooks":`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	results := ValidatePluginContents(root)
+	if len(results) != 3 {
+		t.Fatalf("results = %#v", results)
+	}
+	if !validationContains(results[0].Warnings, "frontmatter", "No frontmatter") {
+		t.Fatalf("skill result = %#v", results[0])
+	}
+	if !validationContains(results[1].Errors, "shell", "shell must be") {
+		t.Fatalf("command result = %#v", results[1])
+	}
+	if !validationContains(results[2].Errors, "json", "Invalid JSON syntax") {
+		t.Fatalf("hooks result = %#v", results[2])
+	}
+}
+
 func validationContains(messages []ManifestValidationMessage, path string, text string) bool {
 	for _, message := range messages {
 		if message.Path == path && strings.Contains(message.Message, text) {