github/spec-kit · error · ValueError

Unsupported integration type '{normalized_type}'. Use one of

Error message

Unsupported integration type '{normalized_type}'. Use one of: {supported}.

What it means

scaffold_integration validates integration_type.strip().lower() against the _TEMPLATES map, whose keys are exactly 'markdown', 'toml', 'yaml', 'skills' (the values returned by supported_integration_scaffold_types()). Any other string aborts scaffolding before any file is touched. The message lists the accepted values so the fix is usually a one-word correction.

Source

Thrown at src/specify_cli/integration_scaffold.py:213

    try:
        target.parent.resolve().relative_to(root_resolved)
    except (OSError, ValueError):
        raise ValueError(
            f"Refusing to scaffold outside the repository root: {target}"
        ) from None


def scaffold_integration(
    project_root: Path,
    key: str,
    integration_type: str,
) -> IntegrationScaffoldResult:
    """Create a minimal built-in integration package and test skeleton."""
    clean_key = _clean_key(key)
    normalized_type = integration_type.strip().lower()
    if normalized_type not in _TEMPLATES:
        supported = ", ".join(supported_integration_scaffold_types())
        raise ValueError(
            f"Unsupported integration type '{normalized_type}'. Use one of: {supported}."
        )

    integrations_root = project_root / "src" / "specify_cli" / "integrations"
    tests_root = project_root / "tests" / "integrations"
    if not _is_spec_kit_repo_root(project_root):
        raise ValueError("Run this command from the Spec Kit repository root.")

    package_name = _package_name(clean_key)
    class_name = _class_name(clean_key)
    integration_dir = integrations_root / package_name
    integration_file = integration_dir / "__init__.py"
    test_file = tests_root / f"test_integration_{package_name}.py"

    for target in (integration_file, test_file):
        _assert_safe_scaffold_target(project_root, target)

    existing = [path for path in (integration_file, test_file) if path.exists()]

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Use one of the four supported types: markdown, toml, yaml, or skills — e.g. `markdown` for $ARGUMENTS-based agents, `yaml` for Goose-style recipes.
2. If unsure in code, derive the choices from the API: `from specify_cli.integration_scaffold import supported_integration_scaffold_types`.
3. Check for typos, extra characters, or passing the agent key instead of the base-class family.

Example fix

# before
scaffold_integration(root, "my-agent", "md")
# after
scaffold_integration(root, "my-agent", "markdown")

from specify_cli.integration_scaffold import supported_integration_scaffold_types

ITYPE = "markdown"
assert ITYPE in supported_integration_scaffold_types(), (
    f"{ITYPE!r} not in {supported_integration_scaffold_types()}"
)

from typing import Literal

ScaffoldType = Literal["markdown", "toml", "yaml", "skills"]

def is_scaffold_type(value: str) -> bool:
    return value in {"markdown", "toml", "yaml", "skills"}

try:
    scaffold_integration(root, key, itype)
except ValueError as exc:
    if "Unsupported integration type" in str(exc):
        itype = "markdown"  # or prompt the user with the listed options
        scaffold_integration(root, key, itype)
    else:
        raise

When it happens

Trigger: Calling scaffold_integration with integration_type values like 'Markdown', 'md', 'python', 'goose', 'cli', or trailing junk ('markdown ') — note strip().lower() handles case and whitespace, so genuinely unknown words are the trigger; passing a registrar format or agent key instead of the template family also triggers it.

Common situations: Confusing the integration key (e.g. 'goose') with the template type (goose is 'yaml'); assuming a 'python' or 'custom' template exists because --script py exists; typos like 'tomal' or 'skill' (singular).

Related errors

• Run this command from the Spec Kit repository root.
• Refusing to scaffold outside the repository root: {target}
• specify event ${{command}} (${{event}}) failed: ${{(e as Err
• errors.join('; ')
• Error: --number requires a value

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