{"record":{"id":"78ee704d5198b580","repo":"cli/cli","slug":"unknown-agent-q-valid-agents-s","errorCode":null,"errorMessage":"unknown agent %q, valid agents: %s","messagePattern":"unknown agent %q, valid agents: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/skills/registry/registry.go","lineNumber":356,"sourceCode":"\t\tProjectDir: sharedProjectSkillsDir,\n\t\tUserDir:    \".agents/skills\",\n\t},\n\t{\n\t\tID:         \"zencoder\",\n\t\tName:       \"Zencoder\",\n\t\tProjectDir: \".zencoder/skills\",\n\t\tUserDir:    \".zencoder/skills\",\n\t},\n}\n\n// FindByID returns the agent host with the given ID, or an error if not found.\nfunc FindByID(id string) (*AgentHost, error) {\n\tfor i := range Agents {\n\t\tif Agents[i].ID == id {\n\t\t\treturn &Agents[i], nil\n\t\t}\n\t}\n\treturn nil, fmt.Errorf(\"unknown agent %q, valid agents: %s\", id, ValidAgentIDs())\n}\n\n// ValidAgentIDs returns a comma-separated list of valid agent IDs.\nfunc ValidAgentIDs() string {\n\treturn strings.Join(AgentIDs(), \", \")\n}\n\n// AgentIDs returns the IDs of all known agents as a slice.\nfunc AgentIDs() []string {\n\tids := make([]string, len(Agents))\n\tfor i, h := range Agents {\n\t\tids[i] = h.ID\n\t}\n\treturn ids\n}\n\n// AgentHelpList returns a newline-separated bulleted list of agents for help text.\nfunc AgentHelpList() string {","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/cli/cli/blob/0eeec0b92edbe70199f9768522f831d3534f41ad/internal/skills/registry/registry.go#L338-L374","documentation":"registry.FindByID looks up an agent host (claude-code, codex, cursor, etc.) by ID in the package-level Agents slice. When the requested ID matches no entry, it returns this error listing all valid IDs via ValidAgentIDs(). This is an input-validation error for the --agent flag / agent selection, not an environment problem.","triggerScenarios":"Passing a misspelled or unsupported agent ID to any registry API that resolves a host, e.g. FindByID(\"cluade-code\") or FindByID(\"vscode\") when the ID is not registered; IDs are case-sensitive.","commonSituations":"Typos in scripts or CI configuration; users assuming an editor name (e.g. \"neovim\", \"windsurf\") is supported when only registered hosts are; casing mistakes like \"Claude-Code\".","solutions":["Read the error text - it lists every valid ID; use one of those exactly","Check spelling and case against the registry entries in internal/skills/registry/registry.go","If a new agent should be supported, add an AgentHost entry to the Agents slice and retest"],"exampleFix":"// before\nhost, err := registry.FindByID(\"cluade-code\") // typo -> error\n\n// after\nhost, err := registry.FindByID(\"claude-code\")","handlingStrategy":"validation","validationCode":"func validAgentID(id string) bool {\n\tfor _, v := range registry.AgentIDs() {\n\t\tif v == id {\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}\n// if !validAgentID(want) { show registry.ValidAgentIDs() to the user }","typeGuard":null,"tryCatchPattern":"host, err := registry.FindByID(id)\nif err != nil {\n\treturn fmt.Errorf(\"choose one of: %s\", registry.ValidAgentIDs())\n}","preventionTips":["Drive agent selection from registry.AgentIDs() output (e.g. a picker) instead of free text","Pin scripts to exact agent IDs and re-verify them after upgrading gh"],"tags":["skills","registry","validation","agent-id"],"backgroundTag":null,"analyzedSha":"0eeec0b92edbe70199f9768522f831d3534f41ad","analyzedAt":"2026-08-15T12:31:05.478Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}