{"record":{"id":"6a4ce63b0ea9e64c","repo":"github/spec-kit","slug":"unsupported-agent-agent-name","errorCode":null,"errorMessage":"Unsupported agent: {agent_name}","messagePattern":"Unsupported agent: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/agents.py","lineNumber":648,"sourceCode":"            context_note: Custom context comment for markdown output\n            _resolved_dir: Pre-resolved command directory (internal use\n                only — avoids a second ``_resolve_agent_dir`` call and\n                duplicate deprecation warnings when invoked from\n                ``register_commands_for_all_agents``).\n            link_outputs: If True, write rendered output to a source-local\n                dev cache and symlink the agent command file to it. Falls back\n                to a normal file write when symlinks are unavailable.\n            extension_id: Extension id when rendering extension-owned commands.\n\n        Returns:\n            List of registered command names\n\n        Raises:\n            ValueError: If agent is not supported\n        \"\"\"\n        self._ensure_configs()\n        if agent_name not in self.AGENT_CONFIGS:\n            raise ValueError(f\"Unsupported agent: {agent_name}\")\n\n        agent_config = self.AGENT_CONFIGS[agent_name]\n        commands_dir = _resolved_dir or self._resolve_agent_dir(\n            agent_name, agent_config, project_root,\n        )\n        commands_dir.mkdir(parents=True, exist_ok=True)\n\n        registered = []\n        is_cline_ext = agent_name == \"cline\" and source_id != \"core\"\n        source_root = source_dir.resolve()\n\n        # Resolve the command-reference separator for the file THIS registrar\n        # is about to write.  The separator must match the *output layout* the\n        # registrar produces for this agent — not the project's persisted\n        # ``ai_skills`` flag, and not unrelated sibling directories on disk.  A\n        # skill scaffold (\"/SKILL.md\") uses the skills separator; any\n        # command-layout output (\".md\", \".agent.md\", \".toml\", …) uses the\n        # command separator.","sourceCodeStart":630,"sourceCodeEnd":666,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/agents.py#L630-L666","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Check the key spelling and case — keys are lowercase identifiers like 'claude', 'copilot', 'cursor-agent'.","For a custom agent, add a matching config entry to AGENT_CONFIGS before calling register."],"exampleFix":"# before\nregistrar.register_commands(project_root, \"cursor\", commands)\n# after\nregistrar.register_commands(project_root, \"cursor-agent\", commands)","handlingStrategy":"type-guard","validationCode":"from specify_cli.agents import CommandRegistrar\n\nCommandRegistrar._ensure_configs()\nsupported = set(CommandRegistrar.AGENT_CONFIGS)\nif agent_name not in supported:\n    raise SystemExit(f\"unsupported agent {agent_name!r}; choose from {sorted(supported)}\")","typeGuard":"from specify_cli.agents import CommandRegistrar\n\ndef is_supported_agent(name: str) -> bool:\n    \"\"\"True when name is a key in the registrar's AGENT_CONFIGS.\"\"\"\n    CommandRegistrar._ensure_configs()\n    return name in CommandRegistrar.AGENT_CONFIGS","tryCatchPattern":"try:\n    registrar.register_commands(project_root, agent_name, commands)\nexcept ValueError as exc:\n    if \"Unsupported agent\" in str(exc):\n        # fall back to a known agent or surface supported list to the user\n        raise SystemExit(f\"{exc}; supported: {sorted(CommandRegistrar.AGENT_CONFIGS)}\") from exc\n    raise","preventionTips":["Derive agent names from AGENT_CONFIGS / INTEGRATION_REGISTRY at runtime instead of hardcoding strings.","Keys are lowercase identifiers — never pass display names.","After upgrading spec-kit, re-check the supported key list; keys can be renamed."],"tags":["agents","registry","validation"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}