feat: update skills to follow the new design. Make 3 separate skill to avoid the mixing of concerns

Author: l-you

.github/workflows/validate-agent-docs.yml

@@ -19,5 +19,5 @@ jobs:
       - name: Test validator
         run: go test ./scripts/validate-agent-docs.go ./scripts/validate-agent-docs_test.go
 
-      - name: Validate policy docs
+      - name: Validate policy docs and skills
         run: go run ./scripts/validate-agent-docs.go

AGENTS.md

@@ -20,11 +20,12 @@ Current repository layout:
   doc.md                # module routing and load conditions
   awesome/              # enforced utility/library registry by stack or capability
     index.md
-    <stack>.md
+    <name>.md
   shared/               # reusable cross-stack rulesets
     <rule-name>.md
   skills/               # skills used to integrate with these policies
-    <skill-name>.md
+    <skill-name>/
+      SKILL.md
   modules/              # stack-specific guidance
     <module-name>/doc.md
 ```
@@ -41,7 +42,7 @@ Current repository layout:
 - `doc.md` must provide a canonical table with short stack key, full stack name, module path, and `load_when`.
 - `doc.md` must instruct agents to always load baseline modules and load project-specific stacks by `load_when` signals.
 - `doc.md` must define section semantics: `Strict rules` for technical constraints, and `Working Agreements` for user-agent interaction protocol.
-- `doc.md` must define how to load and enforce `awesome/index.md` and stack-specific awesome files.
+- `doc.md` must define how to load and enforce `awesome/index.md` and matching awesome files.
 - Changes to module paths or routing signals must update `doc.md` in the same change.
 - When adding a new stack, update `doc.md` with both the short stack key and full stack name.
 - Root `doc.md` should contain only routing/composition logic and helpers to assemble target `AGENTS.md`.
@@ -53,6 +54,13 @@ Current repository layout:
 - Stack modules must link extracted shared rules by relative path (for module files: `[shared/<rule-name>.md](../../shared/<rule-name>.md)`).
 - Keep shared files concrete and tool-focused; stack modules should keep only stack-specific additions.
 
+## Skills
+- Skills are maintained in `skills/<skill-name>/SKILL.md`.
+- Skills must treat `doc.md` and `awesome/index.md` as the source of truth and must not introduce alternate router filenames.
+- Skills that initialize from scratch or refactor existing repositories must run an architecture interview before selecting modules or refactoring code.
+- Skills must wait for explicit `Accept` before writing `AGENTS.md` or performing architecture-driven refactors.
+- Skills that mutate an existing codebase must propose a phased plan before editing files.
+
 ## Rules combination
 Rules in this project must be combined so a target agent can merge them into a single `AGENTS.md` using the contract defined in `doc.md`.
 

README.md

@@ -5,6 +5,7 @@ Central source for shared AGENTS policies of [RevoTale](https://revotale.com).
 ## Source of Truth
 
 - `AGENTS.md` and `doc.md` are the only policy sources of truth.
+- `skills/` contains operational workflows that must consume those sources of truth rather than redefine them.
 - `README.md` is an informative mirror and must stay aligned with those files.
 
 ## Repository Layout
@@ -16,20 +17,36 @@ Central source for shared AGENTS policies of [RevoTale](https://revotale.com).
 - `shared/<rule-name>.md`: reusable cross-stack rulesets referenced by modules.
 - `modules/common/doc.md`: always-loaded baseline module.
 - `modules/<stack>/doc.md`: stack-specific modules.
-- `skills/init-project-from-agent-docs/`: skill to initialize or refresh target `AGENTS.md`.
+- `skills/<skill-name>/SKILL.md`: operational skills for greenfield init, AGENTS refresh, and guided refactors.
 
-## Install Or Update In A Target Repository
+## Skill Workflows
 
-You can apply `agent-docs` in two ways: use the skill for automated create/update, or update `AGENTS.md` manually.
+Use the skill that matches the repository stage.
 
-### Use The Skill
+### Greenfield Init
 
 Skill path: `skills/init-project-from-agent-docs/SKILL.md`
 
 Example request:
-`Use https://github.com/RevoTale/agent-docs/skills/init-project-from-agent-docs skill to refresh AGENTS.md for this repository.`
+`Use https://github.com/RevoTale/agent-docs/skills/init-project-from-agent-docs skill to design the initial AGENTS.md for this new repository.`
 
-### Update Manually
+### Existing Repo AGENTS Refresh
+
+Skill path: `skills/refresh-project-agents-from-agent-docs/SKILL.md`
+
+Example request:
+`Use https://github.com/RevoTale/agent-docs/skills/refresh-project-agents-from-agent-docs skill to refresh AGENTS.md for this repository.`
+
+### Existing Repo Refactor
+
+Skill path: `skills/refactor-project-to-agent-docs/SKILL.md`
+
+Example request:
+`Use https://github.com/RevoTale/agent-docs/skills/refactor-project-to-agent-docs skill to align this repository with the recommended stack after an architecture interview.`
+
+## Update Manually
+
+You can still update `AGENTS.md` manually when automation is not desired.
 
 1. Create a root `AGENTS.md` if missing.
 2. Add `https://github.com/RevoTale/agent-docs/blob/main/doc.md` under `Base Policy Links (Load First)`.

scripts/validate-agent-docs.go

@@ -11,12 +11,14 @@ import (
 )
 
 const (
-	routerDocPath   = "doc.md"
-	rootPolicyPath  = "AGENTS.md"
-	moduleDocGlob   = "modules/*/doc.md"
+	routerDocPath    = "doc.md"
+	rootPolicyPath   = "AGENTS.md"
+	moduleDocGlob    = "modules/*/doc.md"
 	moduleLegacyGlob = "modules/*/AGENTS.md"
 	awesomeIndexPath = "awesome/index.md"
 	awesomeDocGlob   = "awesome/*.md"
+	skillsDirPath    = "skills"
+	skillDocGlob     = "skills/*/SKILL.md"
 
 	sectionStrictRules      = "Strict rules"
 	sectionWorkingAgreement = "Working Agreements"
@@ -30,8 +32,10 @@ var (
 	bulletPattern       = regexp.MustCompile(`^\s*-\s+`)
 	normativeBullet     = regexp.MustCompile(`^\s*-\s+(MUST|SHOULD|MAY)(\s|$)`)
 	registryRowPattern  = regexp.MustCompile(`^\|\s*[^|]+\|\s*[^|]+\|\s*modules/[^|]+\|`)
-	awesomeRowPattern   = regexp.MustCompile(`^\|\s*[^|]+\|\s*\.?/?.*\.md\s*\|`)
+	awesomeRowPattern   = regexp.MustCompile(`^\|\s*[^|]+\|\s*(\[[^]]+\]\([^)]*\.md\)|\.?/?.*\.md)\s*\|`)
 	awesomeStatusRow    = regexp.MustCompile(`^\|\s*[^|]+\|\s*(required|preferred|banned)\s*\|`)
+	skillNamePattern    = regexp.MustCompile(`^name:\s*(.+?)\s*$`)
+	skillDescPattern    = regexp.MustCompile(`^description:\s*(.+?)\s*$`)
 	waForbiddenPatterns = []*regexp.Regexp{
 		regexp.MustCompile(`(?i)task\s+(gen(:check|:code-diff)?|fix|validate|test)(\s|$)`),
 		regexp.MustCompile(`(?i)bun\s+(run|install)(\s|$)`),
@@ -54,6 +58,12 @@ type validator struct {
 	failures []string
 }
 
+type skillDoc struct {
+	name        string
+	description string
+	body        string
+}
+
 func (v *validator) failf(format string, args ...any) {
 	v.failures = append(v.failures, fmt.Sprintf(format, args...))
 }
@@ -189,6 +199,45 @@ func isCodeFence(line string) bool {
 	return strings.HasPrefix(strings.TrimSpace(line), "```")
 }
 
+func parseSkillDoc(path string) (skillDoc, error) {
+	lines, err := readLines(path)
+	if err != nil {
+		return skillDoc{}, err
+	}
+
+	if len(lines) < 3 || strings.TrimSpace(lines[0]) != "---" {
+		return skillDoc{}, fmt.Errorf("missing YAML frontmatter")
+	}
+
+	frontmatterEnd := -1
+	for idx := 1; idx < len(lines); idx++ {
+		if strings.TrimSpace(lines[idx]) == "---" {
+			frontmatterEnd = idx
+			break
+		}
+	}
+	if frontmatterEnd == -1 {
+		return skillDoc{}, fmt.Errorf("frontmatter closing delimiter not found")
+	}
+
+	doc := skillDoc{
+		body: strings.Join(lines[frontmatterEnd+1:], "\n"),
+	}
+
+	for _, line := range lines[1:frontmatterEnd] {
+		trimmed := strings.TrimSpace(line)
+		if matches := skillNamePattern.FindStringSubmatch(trimmed); matches != nil {
+			doc.name = strings.Trim(strings.TrimSpace(matches[1]), `"'`)
+			continue
+		}
+		if matches := skillDescPattern.FindStringSubmatch(trimmed); matches != nil {
+			doc.description = strings.Trim(strings.TrimSpace(matches[1]), `"'`)
+		}
+	}
+
+	return doc, nil
+}
+
 func checkNormativeBullets(v *validator, filePath string, sectionTitle string) {
 	lines, err := readLines(filePath)
 	if err != nil {
@@ -295,6 +344,88 @@ func checkAwesomeFile(v *validator, awesomePath string) {
 	}
 }
 
+func checkSkillsLayout(v *validator) {
+	entries, err := os.ReadDir(skillsDirPath)
+	if err != nil {
+		v.failf("%s cannot be read: %v", skillsDirPath, err)
+		return
+	}
+
+	if len(entries) == 0 {
+		v.failf("%s must contain at least one skill directory", skillsDirPath)
+		return
+	}
+
+	for _, entry := range entries {
+		entryPath := filepath.Join(skillsDirPath, entry.Name())
+		if strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		if !entry.IsDir() {
+			v.failf("%s must contain only skill directories; found file: %s", skillsDirPath, entryPath)
+			continue
+		}
+
+		skillPath := filepath.Join(entryPath, "SKILL.md")
+		if _, statErr := os.Stat(skillPath); statErr != nil {
+			v.failf("Skill directory is missing SKILL.md: %s", skillPath)
+		}
+	}
+}
+
+func checkSkillFile(v *validator, skillPath string) {
+	doc, err := parseSkillDoc(skillPath)
+	if err != nil {
+		v.failf("%s is invalid: %v", skillPath, err)
+		return
+	}
+
+	folderName := filepath.Base(filepath.Dir(skillPath))
+	if doc.name == "" {
+		v.failf("%s must define frontmatter field: name", skillPath)
+	}
+	if doc.description == "" {
+		v.failf("%s must define frontmatter field: description", skillPath)
+	}
+	if doc.name != "" && doc.name != folderName {
+		v.failf("%s frontmatter name must match its folder name (%s)", skillPath, folderName)
+	}
+
+	fullText := strings.Join([]string{doc.name, doc.description, doc.body}, "\n")
+	lowerText := strings.ToLower(fullText)
+
+	if strings.Contains(fullText, "AGENTS.router.md") {
+		v.failf("%s must reference doc.md instead of deprecated AGENTS.router.md", skillPath)
+	}
+
+	switch folderName {
+	case "init-project-from-agent-docs":
+		if !strings.Contains(lowerText, "interview") {
+			v.failf("%s must require an architecture interview", skillPath)
+		}
+		if !strings.Contains(fullText, "Accept") {
+			v.failf("%s must require explicit Accept before writing", skillPath)
+		}
+	case "refresh-project-agents-from-agent-docs":
+		if !strings.Contains(lowerText, "signal") {
+			v.failf("%s must describe repository-signal based selection", skillPath)
+		}
+		if !strings.Contains(fullText, "Accept") {
+			v.failf("%s must require explicit Accept before writing", skillPath)
+		}
+	case "refactor-project-to-agent-docs":
+		if !strings.Contains(lowerText, "interview") {
+			v.failf("%s must require an architecture interview", skillPath)
+		}
+		if !strings.Contains(lowerText, "plan") {
+			v.failf("%s must require a refactor plan before edits", skillPath)
+		}
+		if !strings.Contains(fullText, "Accept") {
+			v.failf("%s must require explicit Accept before refactoring", skillPath)
+		}
+	}
+}
+
 func main() {
 	v := &validator{}
 
@@ -327,7 +458,7 @@ func main() {
 		os.Exit(1)
 	}
 	if len(awesomeRegistryPaths) == 0 {
-		v.failf("No awesome stack files found in %s table", awesomeIndexPath)
+		v.failf("No awesome files found in %s table", awesomeIndexPath)
 	}
 
 	registrySet := make(map[string]struct{}, len(registryPaths))
@@ -387,6 +518,23 @@ func main() {
 		}
 	}
 
+	checkSkillsLayout(v)
+
+	skillDocs, err := filepath.Glob(skillDocGlob)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "ERROR: skill glob failure: %v\n", err)
+		os.Exit(1)
+	}
+	sort.Strings(skillDocs)
+
+	if len(skillDocs) == 0 {
+		v.failf("No skill files found in %s", skillDocGlob)
+	}
+
+	for _, skillPath := range skillDocs {
+		checkSkillFile(v, skillPath)
+	}
+
 	filesToCheck := make([]string, 0, len(moduleDocs)+2)
 	filesToCheck = append(filesToCheck, rootPolicyPath, routerDocPath)
 	filesToCheck = append(filesToCheck, moduleDocs...)