github/spec-kit · error · ValueError

Unsupported agent: {agent_name}

Error message

Unsupported agent: {agent_name}

What it means

CommandRegistrar.register_commands() only accepts agent names present in the class-level AGENT_CONFIGS mapping (populated after _ensure_configs()). Any other name raises ValueError('Unsupported agent: ...') before any files are written.

Source

Thrown at src/specify_cli/agents.py:648

            context_note: Custom context comment for markdown output
            _resolved_dir: Pre-resolved command directory (internal use
                only — avoids a second ``_resolve_agent_dir`` call and
                duplicate deprecation warnings when invoked from
                ``register_commands_for_all_agents``).
            link_outputs: If True, write rendered output to a source-local
                dev cache and symlink the agent command file to it. Falls back
                to a normal file write when symlinks are unavailable.
            extension_id: Extension id when rendering extension-owned commands.

        Returns:
            List of registered command names

        Raises:
            ValueError: If agent is not supported
        """
        self._ensure_configs()
        if agent_name not in self.AGENT_CONFIGS:
            raise ValueError(f"Unsupported agent: {agent_name}")

        agent_config = self.AGENT_CONFIGS[agent_name]
        commands_dir = _resolved_dir or self._resolve_agent_dir(
            agent_name, agent_config, project_root,
        )
        commands_dir.mkdir(parents=True, exist_ok=True)

        registered = []
        is_cline_ext = agent_name == "cline" and source_id != "core"
        source_root = source_dir.resolve()

        # Resolve the command-reference separator for the file THIS registrar
        # is about to write.  The separator must match the *output layout* the
        # registrar produces for this agent — not the project's persisted
        # ``ai_skills`` flag, and not unrelated sibling directories on disk.  A
        # skill scaffold ("/SKILL.md") uses the skills separator; any
        # command-layout output (".md", ".agent.md", ".toml", …) uses the
        # command separator.

View on GitHub (pinned to bf88c9f9a8)

Solutions

  1. Print the supported keys first: python -c "from specify_cli.agents import CommandRegistrar; print(list(CommandRegistrar.AGENT_CONFIGS))" and use one of those exact strings.
  2. Check the key spelling and case — keys are lowercase identifiers like 'claude', 'copilot', 'cursor-agent'.
  3. For a custom agent, add a matching config entry to AGENT_CONFIGS before calling register.

Example fix

# before
registrar.register_commands(project_root, "cursor", commands)
# after
registrar.register_commands(project_root, "cursor-agent", commands)
Defensive patterns

Strategy: type-guard

Validate before calling

from specify_cli.agents import CommandRegistrar

CommandRegistrar._ensure_configs()
supported = set(CommandRegistrar.AGENT_CONFIGS)
if agent_name not in supported:
    raise SystemExit(f"unsupported agent {agent_name!r}; choose from {sorted(supported)}")

Type guard

from specify_cli.agents import CommandRegistrar

def is_supported_agent(name: str) -> bool:
    """True when name is a key in the registrar's AGENT_CONFIGS."""
    CommandRegistrar._ensure_configs()
    return name in CommandRegistrar.AGENT_CONFIGS

Try / catch

try:
    registrar.register_commands(project_root, agent_name, commands)
except ValueError as exc:
    if "Unsupported agent" in str(exc):
        # fall back to a known agent or surface supported list to the user
        raise SystemExit(f"{exc}; supported: {sorted(CommandRegistrar.AGENT_CONFIGS)}") from exc
    raise

Prevention

When it happens

Trigger: Calling register_commands(agent_name='cursor') when the registry key is 'cursor-agent'; passing a display name like 'GitHub Copilot' instead of the key 'copilot'; passing an agent that exists only in newer/older versions of the library; calling before AGENT_CONFIGS was extended via _ensure_configs() in a fork.

Common situations: Version drift: code written against one spec-kit version using an agent key renamed in another; typos and case errors ('Claude' vs 'claude'); custom integrations registered in INTEGRATION_REGISTRY but invoked through the legacy registrar without adding an AGENT_CONFIGS entry.

Related errors

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/6a4ce63b0ea9e64c. Report an issue: GitHub.