feat: add project skill helpers

Author: cmilesio

go.mod

@@ -1,10 +1,10 @@
 module github.com/goforj/atlas
 
-go 1.25.5
+go 1.25.0
 
 require (
 	github.com/go-git/go-git/v5 v5.19.1
-	github.com/mark3labs/mcp-go v0.54.1
+	github.com/mark3labs/mcp-go v0.48.0
 )
 
 require (
@@ -23,7 +23,6 @@ require (
 	github.com/kevinburke/ssh_config v1.2.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
 	github.com/pjbgf/sha1cd v0.6.0 // indirect
-	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect
 	github.com/skeema/knownhosts v1.3.1 // indirect
 	github.com/spf13/cast v1.7.1 // indirect
@@ -32,6 +31,5 @@ require (
 	golang.org/x/crypto v0.50.0 // indirect
 	golang.org/x/net v0.53.0 // indirect
 	golang.org/x/sys v0.43.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 )

go.sum

@@ -16,8 +16,6 @@ github.com/cyphar/filepath-securejoin v0.6.1/go.mod h1:A8hd4EnAeyujCJRrICiOWqjS1
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
-github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/elazarl/goproxy v1.7.2 h1:Y2o6urb7Eule09PjlhQRGNsqRfPmYI3KKQLFpCAV3+o=
 github.com/elazarl/goproxy v1.7.2/go.mod h1:82vkLNir0ALaW14Rc399OTTjyNREgmdL2cVoIbS6XaE=
 github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc=
@@ -55,8 +53,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/mark3labs/mcp-go v0.54.1 h1:Ap/ptEB9FtWzFKM8NDsTA7QDxerQOC06eZigrTldVj0=
-github.com/mark3labs/mcp-go v0.54.1/go.mod h1:+8WclSK1ZUweCP3hvktSji8n8ABG/95QaEkeVE/Uwas=
+github.com/mark3labs/mcp-go v0.48.0 h1:o+MXuGW/HCeR2ny5LcAcZQn2bo6I2xaZMEHnpRG+dtw=
+github.com/mark3labs/mcp-go v0.48.0/go.mod h1:JKTC7R2LLVagkEWK7Kwu7DbmA6iIvnNAod6yrHiQMag=
 github.com/onsi/gomega v1.34.1 h1:EUMJIKUjM8sKjYbtxQI9A4z2o+rruxnzNvpknOXie6k=
 github.com/onsi/gomega v1.34.1/go.mod h1:kU1QgUvBDLXBJq618Xvm2LUX6rSAfRaFRTcdOeDLwwY=
 github.com/pjbgf/sha1cd v0.6.0 h1:3WJ8Wz8gvDz29quX1OcEmkAlUg9diU4GxJHqs0/XiwU=
@@ -67,8 +65,6 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
-github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 h1:n661drycOFuPLCN3Uc8sB6B/s6Z4t2xvBgU1htSHuq8=
 github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
 github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=

guidelines/composer.go

@@ -29,6 +29,10 @@ func Compose(p project.Project) string {
 	out.WriteString("- Update app registration and Wire files through the selected app's composition points.\n")
 	out.WriteString("- Keep MCP and Atlas operations read-only unless an explicit write feature is added later.\n")
 	out.WriteString("- For GoForj framework validation renders, use `/tmp`, never the GoForj repo directory.\n\n")
+	out.WriteString("## Capturing Project Knowledge\n\n")
+	out.WriteString("- When the user teaches a durable repo-specific convention, workflow, command, or review expectation, briefly ask whether it should become a project-owned Atlas skill in `.ai/skills/<name>/SKILL.md`.\n")
+	out.WriteString("- Suggest this only for patterns likely to matter again; do not suggest skills for one-off preferences or temporary debugging steps.\n")
+	out.WriteString("- Keep project-owned skills short, specific, and focused on what agents should do differently in this codebase.\n\n")
 
 	out.WriteString("## Apps\n\n")
 	for _, app := range p.Apps {

mcp/server.go

@@ -34,8 +34,6 @@ func New(cfg Server) *server.MCPServer {
 		cfg.Version,
 		server.WithToolCapabilities(false),
 		server.WithRecovery(),
-		server.WithStrictInputSchemaDefault(),
-		server.WithInputSchemaValidation(),
 	)
 	cfg.register(s)
 	return s

mcp/tools.go

@@ -34,8 +34,8 @@ func toolProjectLayout() mcpgo.Tool {
 func toolSearchDocs() mcpgo.Tool {
 	return baseTool("search-docs", "Searches version-aware GoForj documentation.",
 		mcpgo.WithString("query", mcpgo.Description("Search query."), mcpgo.Required()),
-		mcpgo.WithInteger("limit", mcpgo.Description("Maximum number of results.")),
-		mcpgo.WithInteger("token_limit", mcpgo.Description("Maximum words per snippet.")),
+		mcpgo.WithNumber("limit", mcpgo.Description("Maximum number of results.")),
+		mcpgo.WithNumber("token_limit", mcpgo.Description("Maximum words per snippet.")),
 	)
 }
 
@@ -44,7 +44,7 @@ func toolReadDocSection() mcpgo.Tool {
 	return baseTool("read-doc-section", "Reads one bounded Markdown section.",
 		mcpgo.WithString("path", mcpgo.Description("Document path."), mcpgo.Required()),
 		mcpgo.WithString("heading", mcpgo.Description("Heading to read.")),
-		mcpgo.WithInteger("token_limit", mcpgo.Description("Maximum words to return.")),
+		mcpgo.WithNumber("token_limit", mcpgo.Description("Maximum words to return.")),
 	)
 }
 
@@ -53,9 +53,9 @@ func toolReadDocNeighborhood() mcpgo.Tool {
 	return baseTool("read-doc-neighborhood", "Reads one Markdown section plus nearby sections.",
 		mcpgo.WithString("path", mcpgo.Description("Document path."), mcpgo.Required()),
 		mcpgo.WithString("heading", mcpgo.Description("Heading to read."), mcpgo.Required()),
-		mcpgo.WithInteger("before", mcpgo.Description("Sections before.")),
-		mcpgo.WithInteger("after", mcpgo.Description("Sections after.")),
-		mcpgo.WithInteger("token_limit", mcpgo.Description("Maximum words per section.")),
+		mcpgo.WithNumber("before", mcpgo.Description("Sections before.")),
+		mcpgo.WithNumber("after", mcpgo.Description("Sections after.")),
+		mcpgo.WithNumber("token_limit", mcpgo.Description("Maximum words per section.")),
 	)
 }
 
@@ -105,15 +105,15 @@ func toolDatabaseQuery() mcpgo.Tool {
 	return baseTool("database-query", "Runs a bounded read-only database query.",
 		mcpgo.WithString("connection", mcpgo.Description("Database connection name."), mcpgo.Required()),
 		mcpgo.WithString("sql", mcpgo.Description("Read-only SQL query."), mcpgo.Required()),
-		mcpgo.WithInteger("limit", mcpgo.Description("Maximum rows to return.")),
+		mcpgo.WithNumber("limit", mcpgo.Description("Maximum rows to return.")),
 	)
 }
 
 // toolReadLogEntries defines the recent log reader tool.
 func toolReadLogEntries() mcpgo.Tool {
 	return baseTool("read-log-entries", "Returns recent framework log entries.",
 		appArg(),
-		mcpgo.WithInteger("limit", mcpgo.Description("Maximum entries to return.")),
+		mcpgo.WithNumber("limit", mcpgo.Description("Maximum entries to return.")),
 	)
 }
 
@@ -134,7 +134,7 @@ func toolGetAbsoluteURL() mcpgo.Tool {
 func toolBrowserLogs() mcpgo.Tool {
 	return baseTool("browser-logs", "Returns recent browser console logs captured during local development.",
 		appArg(),
-		mcpgo.WithInteger("limit", mcpgo.Description("Maximum entries to return.")),
+		mcpgo.WithNumber("limit", mcpgo.Description("Maximum entries to return.")),
 	)
 }
 

skills/project.go

@@ -0,0 +1,110 @@
+package skills
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+var projectSkillNamePattern = regexp.MustCompile(`^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`)
+
+// ProjectSkill describes a repo-owned Atlas skill under .ai/skills.
+type ProjectSkill struct {
+	Name string
+	Path string
+	File bool
+}
+
+// ProjectSkills returns repo-owned Atlas skills from .ai/skills.
+func ProjectSkills(root string) ([]ProjectSkill, error) {
+	sourceRoot := filepath.Join(firstNonEmpty(root, "."), ".ai", "skills")
+	entries, err := os.ReadDir(sourceRoot)
+	if os.IsNotExist(err) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	projectSkills := []ProjectSkill{}
+	for _, entry := range entries {
+		path := filepath.Join(sourceRoot, entry.Name())
+		if entry.IsDir() {
+			skillPath := filepath.Join(path, "SKILL.md")
+			if !fileExists(skillPath) {
+				continue
+			}
+			projectSkills = append(projectSkills, ProjectSkill{
+				Name: entry.Name(),
+				Path: skillPath,
+			})
+			continue
+		}
+		if strings.HasSuffix(entry.Name(), ".md") {
+			projectSkills = append(projectSkills, ProjectSkill{
+				Name: strings.TrimSuffix(entry.Name(), ".md"),
+				Path: path,
+				File: true,
+			})
+		}
+	}
+
+	sort.Slice(projectSkills, func(i int, j int) bool {
+		return projectSkills[i].Name < projectSkills[j].Name
+	})
+	return projectSkills, nil
+}
+
+// ScaffoldProjectSkill creates a repo-owned Atlas skill template.
+func ScaffoldProjectSkill(root string, name string) (string, error) {
+	name = strings.TrimSpace(name)
+	if !projectSkillNamePattern.MatchString(name) {
+		return "", fmt.Errorf("invalid skill name %q; use lowercase kebab-case such as checkout-rules", name)
+	}
+
+	path := filepath.Join(firstNonEmpty(root, "."), ".ai", "skills", name, "SKILL.md")
+	if fileExists(path) {
+		return "", fmt.Errorf("project skill %q already exists at %s", name, path)
+	}
+	content := projectSkillTemplate(name)
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return "", err
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+// firstNonEmpty returns the first non-blank value.
+func firstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return value
+		}
+	}
+	return ""
+}
+
+func projectSkillTemplate(name string) string {
+	title := title(name)
+	return fmt.Sprintf(`# %s
+
+Describe the durable repo-specific convention, workflow, command, or review expectation this agent should remember.
+
+Use this skill when:
+
+- the task touches this project's specific rules
+- the user asks for behavior covered by this convention
+- the agent is about to generate, review, or modify related code
+
+Guidance:
+
+- Keep changes consistent with the convention.
+- Prefer concrete project commands and paths over broad advice.
+- If the convention no longer applies, ask before following it.
+`, title)
+}

skills/writer.go

@@ -104,69 +104,46 @@ func writeCopilot(opts WriteOptions) ([]string, error) {
 
 // copyUserSkills preserves project-owned skills alongside generated Atlas skills.
 func copyUserSkills(projectRoot string, targetRoot string) ([]string, error) {
-	sourceRoot := filepath.Join(projectRoot, ".ai", "skills")
-	entries, err := os.ReadDir(sourceRoot)
-	if os.IsNotExist(err) {
-		return nil, nil
-	}
+	projectSkills, err := ProjectSkills(projectRoot)
 	if err != nil {
 		return nil, err
 	}
 
 	paths := []string{}
-	for _, entry := range entries {
-		source := filepath.Join(sourceRoot, entry.Name())
-		target := filepath.Join(targetRoot, entry.Name())
-		if entry.IsDir() {
-			copied, err := copyDir(source, target)
-			if err != nil {
+	for _, skill := range projectSkills {
+		if skill.File {
+			target := filepath.Join(targetRoot, filepath.Base(skill.Path))
+			if err := copyFile(skill.Path, target); err != nil {
 				return nil, err
 			}
-			paths = append(paths, copied...)
+			paths = append(paths, target)
 			continue
 		}
-		if strings.HasSuffix(entry.Name(), ".md") {
-			if err := copyFile(source, target); err != nil {
-				return nil, err
-			}
-			paths = append(paths, target)
+		source := filepath.Dir(skill.Path)
+		target := filepath.Join(targetRoot, skill.Name)
+		copied, err := copyDir(source, target)
+		if err != nil {
+			return nil, err
 		}
+		paths = append(paths, copied...)
 	}
 	return paths, nil
 }
 
 // writeCopilotUserSkills adapts project-owned SKILL.md files to Copilot instructions.
 func writeCopilotUserSkills(projectRoot string, targetRoot string) ([]string, error) {
-	sourceRoot := filepath.Join(projectRoot, ".ai", "skills")
-	entries, err := os.ReadDir(sourceRoot)
-	if os.IsNotExist(err) {
-		return nil, nil
-	}
+	projectSkills, err := ProjectSkills(projectRoot)
 	if err != nil {
 		return nil, err
 	}
 
 	paths := []string{}
-	for _, entry := range entries {
-		if entry.IsDir() {
-			source := filepath.Join(sourceRoot, entry.Name(), "SKILL.md")
-			if !fileExists(source) {
-				continue
-			}
-			target := filepath.Join(targetRoot, entry.Name()+".instructions.md")
-			if err := copyFile(source, target); err != nil {
-				return nil, err
-			}
-			paths = append(paths, target)
-			continue
-		}
-		if strings.HasSuffix(entry.Name(), ".md") {
-			target := filepath.Join(targetRoot, strings.TrimSuffix(entry.Name(), ".md")+".instructions.md")
-			if err := copyFile(filepath.Join(sourceRoot, entry.Name()), target); err != nil {
-				return nil, err
-			}
-			paths = append(paths, target)
+	for _, skill := range projectSkills {
+		target := filepath.Join(targetRoot, skill.Name+".instructions.md")
+		if err := copyFile(skill.Path, target); err != nil {
+			return nil, err
 		}
+		paths = append(paths, target)
 	}
 	return paths, nil
 }

skills/writer_test.go

@@ -67,9 +67,52 @@ func TestWriteCopilotMapsUserSkillsToInstructions(t *testing.T) {
 	assertFile(t, filepath.Join(root, ".github", "instructions", "local-skill.instructions.md"))
 }
 
+func TestProjectSkillsListsDirectoriesAndMarkdownFiles(t *testing.T) {
+	root := t.TempDir()
+	writeSkillTestFile(t, filepath.Join(root, ".ai", "skills", "local-skill", "SKILL.md"), "# Local Skill\n")
+	writeSkillTestFile(t, filepath.Join(root, ".ai", "skills", "runbook.md"), "# Runbook\n")
+	writeSkillTestFile(t, filepath.Join(root, ".ai", "skills", "draft", "notes.md"), "# Ignored\n")
+
+	projectSkills, err := ProjectSkills(root)
+	if err != nil {
+		t.Fatalf("project skills: %v", err)
+	}
+	if len(projectSkills) != 2 {
+		t.Fatalf("expected 2 project skills, got %#v", projectSkills)
+	}
+	if projectSkills[0].Name != "local-skill" || projectSkills[1].Name != "runbook" {
+		t.Fatalf("unexpected project skills %#v", projectSkills)
+	}
+}
+
+func TestScaffoldProjectSkill(t *testing.T) {
+	root := t.TempDir()
+	path, err := ScaffoldProjectSkill(root, "checkout-rules")
+	if err != nil {
+		t.Fatalf("scaffold project skill: %v", err)
+	}
+	assertFile(t, path)
+	if _, err := ScaffoldProjectSkill(root, "checkout-rules"); err == nil {
+		t.Fatal("expected duplicate skill error")
+	}
+	if _, err := ScaffoldProjectSkill(root, "CheckoutRules"); err == nil {
+		t.Fatal("expected invalid skill name error")
+	}
+}
+
 func assertFile(t *testing.T, path string) {
 	t.Helper()
 	if _, err := os.Stat(path); err != nil {
 		t.Fatalf("expected file %s: %v", path, err)
 	}
 }
+
+func writeSkillTestFile(t *testing.T, path string, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("mkdir %s: %v", path, err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}