refine skills prompt

SKILLS_PROMPT.md

@@ -34,6 +34,38 @@ Code:
 - Documentation → `documentation`, `notes`
 - Knowledge management → `knowledge`, `learning`
 
+## Proactive Role Discovery
+
+**When user assigns you a specialized identity or requests specialized expertise**, discover and load relevant roles:
+
+Examples:
+- "You are an API tester" → search for "API testing" role
+- "I need help testing an API" → search for "API testing" role
+- "Help me design a database schema" → search for "database" or "backend architect" role
+- "Review this code for security issues" → search for "security" role
+
+1. Search for roles by **specific task keywords**:
+```
+Tool: execute_code
+Language: bash
+Code:
+bash <(9p read agent/tools/mcp/discover_role.sh) <specific-keyword>
+```
+
+2. Load role content:
+```
+Tool: execute_code
+Language: bash
+Code:
+9p read agent/roles/<focus-area>/<role-filename>.md
+```
+
+3. Adopt the role's persona and expertise for your response
+
+**Use specific keywords, not broad categories:**
+- ✓ "API testing", "backend architect", "security audit" (specific)
+- ✗ "testing", "engineering", "QA" (too broad)
+
 ## Tool Discovery
 
 For ANY AnviLLM task (sessions, messages, beads, agents, etc.):

claude/agent/anvillm-agent.md

@@ -66,6 +66,38 @@ Code:
 - Documentation → `documentation`, `notes`
 - Knowledge management → `knowledge`, `learning`
 
+## Proactive Role Discovery
+
+**When user assigns you a specialized identity or requests specialized expertise**, discover and load relevant roles:
+
+Examples:
+- "You are an API tester" → search for "API testing" role
+- "I need help testing an API" → search for "API testing" role
+- "Help me design a database schema" → search for "database" or "backend architect" role
+- "Review this code for security issues" → search for "security" role
+
+1. Search for roles by **specific task keywords**:
+```
+Tool: execute_code
+Language: bash
+Code:
+bash <(9p read agent/tools/mcp/discover_role.sh) <specific-keyword>
+```
+
+2. Load role content:
+```
+Tool: execute_code
+Language: bash
+Code:
+9p read agent/roles/<focus-area>/<role-filename>.md
+```
+
+3. Adopt the role's persona and expertise for your response
+
+**Use specific keywords, not broad categories:**
+- ✓ "API testing", "backend architect", "security audit" (specific)
+- ✗ "testing", "engineering", "QA" (too broad)
+
 ## Tool Discovery
 
 For ANY AnviLLM task (sessions, messages, beads, agents, etc.):

internal/p9/roles.go

@@ -68,6 +68,7 @@ func parseRoleFrontMatter(rolePath string, derivedFocusAreas []string) (*RoleMet
 	scanner := bufio.NewScanner(f)
 	inFrontMatter := false
 	hasFrontMatterFocusAreas := false
+	hasDescription := false
 
 	for scanner.Scan() {
 		line := scanner.Text()
@@ -95,11 +96,17 @@ func parseRoleFrontMatter(rolePath string, derivedFocusAreas []string) (*RoleMet
 			}
 		} else if desc, ok := strings.CutPrefix(line, "description:"); ok {
 			meta.Description = strings.TrimSpace(desc)
+			hasDescription = true
 		} else if name, ok := strings.CutPrefix(line, "name:"); ok {
 			meta.DisplayName = strings.TrimSpace(name)
 		}
 	}
 
+	// If missing description, exclude from list
+	if !hasDescription {
+		return nil, fmt.Errorf("missing description")
+	}
+
 	// If no frontmatter focus-areas and no derived, add "uncategorized"
 	if !hasFrontMatterFocusAreas && len(derivedFocusAreas) == 0 {
 		meta.FocusAreas = []string{"uncategorized"}
@@ -210,7 +217,7 @@ func (r *RolesFS) listRolesInFocusArea(focusArea string) ([]*RoleMeta, error) {
 	return result, nil
 }
 
-// generateHelp creates aggregated index: focus-area/role-name\tdescription
+// generateHelp creates aggregated index: focus-area/role-filename.md\tDisplayName\tDescription
 func (r *RolesFS) generateHelp() (string, error) {
 	roles, err := r.listAllRoles()
 	if err != nil {
@@ -224,7 +231,7 @@ func (r *RolesFS) generateHelp() (string, error) {
 			displayName = role.Name
 		}
 		for _, fa := range role.FocusAreas {
-			line := fmt.Sprintf("%s/%s\t%s", fa, displayName, role.Description)
+			line := fmt.Sprintf("%s/%s.md\t%s\t%s", fa, role.Name, displayName, role.Description)
 			lines = append(lines, line)
 		}
 	}

internal/p9/skills.go

@@ -67,6 +67,8 @@ func parseSkillFrontMatter(skillDir string) (*SkillMeta, error) {
 
 	scanner := bufio.NewScanner(f)
 	inFrontMatter := false
+	hasName := false
+	hasDescription := false
 
 	for scanner.Scan() {
 		line := scanner.Text()
@@ -91,11 +93,20 @@ func parseSkillFrontMatter(skillDir string) (*SkillMeta, error) {
 					meta.Intents = append(meta.Intents, i)
 				}
 			}
+		} else if name, ok := strings.CutPrefix(line, "name:"); ok {
+			meta.Name = strings.TrimSpace(name)
+			hasName = true
 		} else if desc, ok := strings.CutPrefix(line, "description:"); ok {
 			meta.Description = strings.TrimSpace(desc)
+			hasDescription = true
 		}
 	}
 
+	// If missing name or description, return nil to exclude from list
+	if !hasName || !hasDescription {
+		return nil, fmt.Errorf("missing name or description")
+	}
+
 	return meta, nil
 }