cli/cli · error

unknown agent %q, valid agents: %s

Error message

unknown agent %q, valid agents: %s

What it means

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.

Source

Thrown at internal/skills/registry/registry.go:356

		ProjectDir: sharedProjectSkillsDir,
		UserDir:    ".agents/skills",
	},
	{
		ID:         "zencoder",
		Name:       "Zencoder",
		ProjectDir: ".zencoder/skills",
		UserDir:    ".zencoder/skills",
	},
}

// FindByID returns the agent host with the given ID, or an error if not found.
func FindByID(id string) (*AgentHost, error) {
	for i := range Agents {
		if Agents[i].ID == id {
			return &Agents[i], nil
		}
	}
	return nil, fmt.Errorf("unknown agent %q, valid agents: %s", id, ValidAgentIDs())
}

// ValidAgentIDs returns a comma-separated list of valid agent IDs.
func ValidAgentIDs() string {
	return strings.Join(AgentIDs(), ", ")
}

// AgentIDs returns the IDs of all known agents as a slice.
func AgentIDs() []string {
	ids := make([]string, len(Agents))
	for i, h := range Agents {
		ids[i] = h.ID
	}
	return ids
}

// AgentHelpList returns a newline-separated bulleted list of agents for help text.
func AgentHelpList() string {

View on GitHub (pinned to 0eeec0b92e)

Solutions

1. Read the error text - it lists every valid ID; use one of those exactly
2. Check spelling and case against the registry entries in internal/skills/registry/registry.go
3. If a new agent should be supported, add an AgentHost entry to the Agents slice and retest

Example fix

// before
host, err := registry.FindByID("cluade-code") // typo -> error

// after
host, err := registry.FindByID("claude-code")

func validAgentID(id string) bool {
	for _, v := range registry.AgentIDs() {
		if v == id {
			return true
		}
	}
	return false
}
// if !validAgentID(want) { show registry.ValidAgentIDs() to the user }

host, err := registry.FindByID(id)
if err != nil {
	return fmt.Errorf("choose one of: %s", registry.ValidAgentIDs())
}

When it happens

Trigger: 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.

Common situations: 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".

Related errors

• invalid scope %q
• invalid skill name %q
• invalid skill name %q in %s
• could not determine project root directory
• could not determine home directory

AI-assisted analysis of cli/cli@0eeec0b92e (2026-08-15). Data as JSON: /api/errors/78ee704d5198b580. Report an issue: GitHub.