Support full skill folder structure (br#26) (#28)

Add folder awareness to skill show, list, and validate commands.
Skills can now bundle helper scripts and assets alongside SKILL.md,
with validation warning about missing referenced files.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: devrimcavusoglu

docs/concepts/registry.md

@@ -15,6 +15,10 @@ Project-scoped skills live in `.skern/skills/` within your project directory. Th
       SKILL.md
     deploy/
       SKILL.md
+      scripts/
+        deploy.sh
+      config/
+        targets.json
 ```
 
 Initialize the project registry with:
@@ -32,6 +36,8 @@ User-scoped skills live in `~/.skern/skills/` and are available across all proje
   skills/
     global-lint/
       SKILL.md
+      scripts/
+        lint-rules.js
 ```
 
 ### Scope Selection

docs/concepts/skill-format.md

@@ -47,6 +47,24 @@ The markdown body contains the skill's instructions. This is what the agent read
 
 Skills track author metadata and an optional `modified-by` history. `skern skill show` displays the full provenance chain when present, including editor name, type (human/agent), platform, and date.
 
+## Folder Structure
+
+Skills can include additional files alongside `SKILL.md` — helper scripts, templates, configuration files, and other assets. When a skill is installed to a platform, the entire directory is copied.
+
+```
+my-skill/
+├── SKILL.md
+├── scripts/
+│   ├── convert.py
+│   └── setup.sh
+└── assets/
+    └── template.json
+```
+
+The `scripts/` directory is language-agnostic — skills can include Python, shell, JavaScript, or any other scripts. The agent decides which language is appropriate for the skill.
+
+Use `skern skill show <name>` to see which files are bundled with a skill, and `skern skill validate <name>` to check that files referenced in the skill body actually exist.
+
 ## Creating Skills
 
 Use `skern skill create` to scaffold a new skill:

docs/reference/validation.md

@@ -30,6 +30,10 @@ If `allowed-tools` is specified in the frontmatter, no entries may be empty stri
 - **Author type** — must be `human` or `agent`
 - **Version** — should follow [semantic versioning](https://semver.org) (e.g., `1.0.0`)
 
+### Folder Integrity
+
+When a skill body references files (via backtick-enclosed paths like `` `scripts/run.py` `` or markdown links like `[script](scripts/run.py)`), validation checks that those files exist in the skill directory. Missing references produce **warnings**, not errors — the skill remains valid since references may be aspirational or provided at runtime.
+
 ## Exit Codes
 
 | Code | Meaning |

internal/cli/skill_helpers.go

@@ -86,13 +86,17 @@ func formatSkillTable(skills []output.SkillResult) string {
 	}
 
 	var b strings.Builder
-	fmt.Fprintf(&b, "%-30s %-10s %-40s\n", "NAME", "SCOPE", "DESCRIPTION")
+	fmt.Fprintf(&b, "%-30s %-10s %-7s %-40s\n", "NAME", "SCOPE", "FILES", "DESCRIPTION")
 	for _, s := range skills {
 		desc := s.Description
 		if len(desc) > 40 {
 			desc = desc[:37] + "..."
 		}
-		fmt.Fprintf(&b, "%-30s %-10s %-40s\n", s.Name, s.Scope, desc)
+		fileCount := "-"
+		if len(s.Files) > 0 {
+			fileCount = fmt.Sprintf("%d", len(s.Files))
+		}
+		fmt.Fprintf(&b, "%-30s %-10s %-7s %-40s\n", s.Name, s.Scope, fileCount, desc)
 	}
 	return b.String()
 }
@@ -117,6 +121,12 @@ func formatSkillShow(s output.SkillResult) string {
 	if len(s.AllowedTools) > 0 {
 		fmt.Fprintf(&b, "Tools:       %s\n", strings.Join(s.AllowedTools, ", "))
 	}
+	if len(s.Files) > 0 {
+		b.WriteString("Files:\n")
+		for _, f := range s.Files {
+			fmt.Fprintf(&b, "  - %s\n", f)
+		}
+	}
 	if len(s.ModifiedBy) > 0 {
 		b.WriteString("Modified-by:\n")
 		for _, m := range s.ModifiedBy {

internal/cli/skill_list.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"github.com/devrimcavusoglu/skern/internal/output"
 	"github.com/devrimcavusoglu/skern/internal/overlap"
+	"github.com/devrimcavusoglu/skern/internal/registry"
 	"github.com/devrimcavusoglu/skern/internal/skill"
 	"github.com/spf13/cobra"
 )
@@ -22,32 +23,35 @@ func newSkillListCmd() *cobra.Command {
 
 			var skillResults []output.SkillResult
 
+			var discovered []registry.DiscoveredSkill
+
 			if scope == "all" {
-				discovered, err := reg.ListAll()
+				discovered, err = reg.ListAll()
 				if err != nil {
 					return err
 				}
-				for _, d := range discovered {
-					skillResults = append(skillResults, toDiscoveredSkillResult(d))
-				}
 			} else {
 				scopeVal, err := parseScope(scope)
 				if err != nil {
 					return err
 				}
-				skills, err := reg.List(scopeVal)
+				all, err := reg.ListAll()
 				if err != nil {
 					return err
 				}
-				dir := ""
-				if scopeVal == skill.ScopeUser {
-					dir = "user"
-				} else {
-					dir = "project"
+				for _, d := range all {
+					if d.Scope == scopeVal {
+						discovered = append(discovered, d)
+					}
 				}
-				for _, s := range skills {
-					skillResults = append(skillResults, toSkillResult(&s, dir, ""))
+			}
+
+			for _, d := range discovered {
+				r := toDiscoveredSkillResult(d)
+				if files, err := skill.ListFiles(d.Path); err == nil && len(files) > 0 {
+					r.Files = files
 				}
+				skillResults = append(skillResults, r)
 			}
 
 			// Pairwise dedup detection

internal/cli/skill_show.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"github.com/devrimcavusoglu/skern/internal/skill"
 	"github.com/spf13/cobra"
 )
 
@@ -25,6 +26,9 @@ func newSkillShowCmd() *cobra.Command {
 			}
 
 			result := toSkillResult(s, string(foundScope), path)
+			if files, err := skill.ListFiles(path); err == nil && len(files) > 0 {
+				result.Files = files
+			}
 			text := formatSkillShow(result)
 			printer.PrintResult(result, text)
 			return nil

internal/cli/skill_test.go

@@ -473,6 +473,91 @@ func TestSkillList_NoDedupHints(t *testing.T) {
 
 // --- author provenance (modified-by) ---
 
+// --- skill show with files ---
+
+func TestSkillShow_WithFiles(t *testing.T) {
+	setupTestRegistry(t)
+
+	_, err := runCmd(t, "skill", "create", "file-skill", "--description", "A skill with files")
+	require.NoError(t, err)
+
+	// Get the skill path
+	showOut, err := runCmd(t, "skill", "show", "file-skill", "--json")
+	require.NoError(t, err)
+
+	var initial output.SkillResult
+	require.NoError(t, json.Unmarshal([]byte(showOut), &initial))
+
+	// Add extra files to the skill directory
+	scriptsDir := filepath.Join(initial.Path, "scripts")
+	require.NoError(t, os.MkdirAll(scriptsDir, 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(scriptsDir, "convert.py"), []byte("# python"), 0o644))
+	require.NoError(t, os.WriteFile(filepath.Join(initial.Path, "config.json"), []byte("{}"), 0o644))
+
+	// Show again — should include files
+	out, err := runCmd(t, "skill", "show", "file-skill", "--json")
+	require.NoError(t, err)
+
+	var result output.SkillResult
+	require.NoError(t, json.Unmarshal([]byte(out), &result))
+	assert.Len(t, result.Files, 2)
+	assert.Contains(t, result.Files, "config.json")
+	assert.Contains(t, result.Files, filepath.Join("scripts", "convert.py"))
+}
+
+// --- skill validate folder warning ---
+
+func TestSkillValidate_FolderWarning(t *testing.T) {
+	setupTestRegistry(t)
+
+	_, err := runCmd(t, "skill", "create", "ref-skill", "--description", "A skill with refs", "--author", "alice")
+	require.NoError(t, err)
+
+	// Get the skill path
+	showOut, err := runCmd(t, "skill", "show", "ref-skill", "--json")
+	require.NoError(t, err)
+
+	var initial output.SkillResult
+	require.NoError(t, json.Unmarshal([]byte(showOut), &initial))
+
+	// Overwrite SKILL.md with a body referencing a missing file
+	skillMdPath := filepath.Join(initial.Path, "SKILL.md")
+	content := `---
+name: ref-skill
+description: A skill with refs
+metadata:
+  author:
+    name: alice
+    type: human
+  version: "0.1.0"
+---
+## Instructions
+
+Run ` + "`scripts/run.py`" + ` to process data.
+`
+	require.NoError(t, os.WriteFile(skillMdPath, []byte(content), 0o644))
+
+	// Validate — should warn about missing file
+	out, err := runCmd(t, "skill", "validate", "ref-skill", "--json")
+	require.NoError(t, err)
+
+	var result output.SkillValidateResult
+	require.NoError(t, json.Unmarshal([]byte(out), &result))
+	assert.True(t, result.Valid, "should still be valid (warnings only)")
+	assert.Equal(t, 1, result.Warns)
+
+	// Find the folder warning
+	found := false
+	for _, issue := range result.Issues {
+		if issue.Field == "folder" {
+			found = true
+			assert.Equal(t, "warning", issue.Severity)
+			assert.Contains(t, issue.Message, "scripts/run.py")
+		}
+	}
+	assert.True(t, found, "should have a folder warning")
+}
+
 func TestSkillShow_ModifiedBy(t *testing.T) {
 	setupTestRegistry(t)
 

internal/cli/skill_validate.go

@@ -24,12 +24,13 @@ func newSkillValidateCmd() *cobra.Command {
 				return err
 			}
 
-			s, _, _, err := resolveSkill(reg, name, scope)
+			s, skillDir, _, err := resolveSkill(reg, name, scope)
 			if err != nil {
 				return err
 			}
 
 			issues := skill.Validate(s)
+			issues = append(issues, skill.ValidateFolder(s, skillDir)...)
 			result := toValidateResult(name, issues)
 			text := formatValidateResult(result)
 			printer.PrintResult(result, text)

internal/output/output.go

@@ -143,6 +143,7 @@ type SkillResult struct {
 	Scope        string             `json:"scope,omitempty"`
 	Path         string             `json:"path,omitempty"`
 	AllowedTools []string           `json:"allowed_tools,omitempty"`
+	Files        []string           `json:"files,omitempty"`
 	ModifiedBy   []ModifiedByResult `json:"modified_by,omitempty"`
 }
 

internal/skill/folder.go

@@ -0,0 +1,74 @@
+package skill
+
+import (
+	"io/fs"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// ListFiles walks the skill directory and returns relative paths of all files
+// except SKILL.md. Returns an empty slice for directories containing only SKILL.md.
+func ListFiles(skillDir string) ([]string, error) {
+	var files []string
+
+	err := filepath.WalkDir(skillDir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+
+		rel, err := filepath.Rel(skillDir, path)
+		if err != nil {
+			return err
+		}
+
+		if rel != "SKILL.md" {
+			files = append(files, rel)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return files, nil
+}
+
+var (
+	// Matches backtick-enclosed paths that contain a slash (to avoid false positives like `v1.0.0`).
+	backtickPathRe = regexp.MustCompile("`([^`]+/[^`]+)`")
+	// Matches markdown link targets, excluding URLs (http) and anchors (#).
+	mdLinkRe = regexp.MustCompile(`\]\(([^)]+)\)`)
+)
+
+// ExtractFileReferences extracts path-like references from a markdown body.
+// It looks for backtick-enclosed paths containing '/' and markdown link targets
+// that are not URLs or anchors.
+func ExtractFileReferences(body string) []string {
+	seen := make(map[string]bool)
+	var refs []string
+
+	for _, m := range backtickPathRe.FindAllStringSubmatch(body, -1) {
+		p := m[1]
+		if !seen[p] {
+			seen[p] = true
+			refs = append(refs, p)
+		}
+	}
+
+	for _, m := range mdLinkRe.FindAllStringSubmatch(body, -1) {
+		p := m[1]
+		if strings.HasPrefix(p, "http") || strings.HasPrefix(p, "#") {
+			continue
+		}
+		if !seen[p] {
+			seen[p] = true
+			refs = append(refs, p)
+		}
+	}
+
+	return refs
+}