github/spec-kit · error · ExtensionError

Unsupported agent: {agent_name}

Error message

Unsupported agent: {agent_name}

What it means

ExtensionManager.register_commands_for_agent refuses to install an extension's commands for an agent name that is not a key in the class-level AGENT_CONFIGS mapping. The mapping is the closed set of agents the extension command registrar knows how to write command files for.

Source

Thrown at src/specify_cli/extensions/__init__.py:3530

    def _render_toml_command(self, frontmatter, body, ext_id):
        # Preserve extension-specific context comments for backward compatibility
        base = self._registrar.render_toml_command(frontmatter, body, ext_id)
        context_lines = (
            f"# Extension: {ext_id}\n# Config: .specify/extensions/{ext_id}/\n"
        )
        return base.rstrip("\n") + "\n" + context_lines

    def register_commands_for_agent(
        self,
        agent_name: str,
        manifest: ExtensionManifest,
        extension_dir: Path,
        project_root: Path,
        link_outputs: bool = False,
    ) -> List[str]:
        """Register extension commands for a specific agent."""
        if agent_name not in self.AGENT_CONFIGS:
            raise ExtensionError(f"Unsupported agent: {agent_name}")
        context_note = f"\n<!-- Extension: {manifest.id} -->\n<!-- Config: .specify/extensions/{manifest.id}/ -->\n"
        return self._registrar.register_commands(
            agent_name,
            manifest.commands,
            manifest.id,
            extension_dir,
            project_root,
            context_note=context_note,
            link_outputs=link_outputs,
            extension_id=manifest.id,
        )

    def register_commands_for_all_agents(
        self,
        manifest: ExtensionManifest,
        extension_dir: Path,
        project_root: Path,
        link_outputs: bool = False,

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Print the supported set and use one of those keys: `python -c "from specify_cli.extensions import ExtensionManager; print(ExtensionManager.AGENT_CONFIGS.keys())"`
2. Fix typos/casing: keys are exact identifiers like 'claude', 'gemini', 'copilot', not display names
3. If you added a new integration, add its key to AGENT_CONFIGS alongside the registrar config
4. Upgrade specify_cli if the agent is supported in a newer release

Example fix

# before
manager.register_commands_for_agent("Claude Code", manifest, ext_dir, project_root)

# after
manager.register_commands_for_agent("claude", manifest, ext_dir, project_root)

from specify_cli.extensions import ExtensionManager

def is_supported_agent(name: str) -> bool:
    return name in ExtensionManager.AGENT_CONFIGS

agent = "claude"
assert is_supported_agent(agent)

from specify_cli.extensions import ExtensionManager

def assert_supported_agent(name: str) -> None:
    """Type-guard: raise early with the valid key set on unknown agents."""
    if name not in ExtensionManager.AGENT_CONFIGS:
        raise ValueError(
            f"Unsupported agent {name!r}; "
            f"expected one of {sorted(ExtensionManager.AGENT_CONFIGS)}"
        )

When it happens

Trigger: Calling register_commands_for_agent(agent_name, ...) with a name absent from ExtensionManager.AGENT_CONFIGS — e.g. a typo ('claude-code' vs 'claude'), a newly added integration key that was never added to AGENT_CONFIGS, or a removed/renamed agent key.

Common situations: Adding a new integration to the CLI registry but forgetting the extensions layer's AGENT_CONFIGS; scripts passing a user-supplied agent name straight through; version skew between a tool that lists integrations and the installed specify_cli version.

Related errors

• Unknown event '{event_name}': must be one of {sorted(CANONIC
• Event '{event_name}' handler missing required non-empty 'com
• Event '{event_name}' handler has invalid 'matcher': must be
• Manifest must be a YAML mapping, got {type(data).__name__}:
• Missing required field: {field}

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