What causes "Invalid skill reference. Use the format @org/name." in crewAIInc/crewAI?

Add the `@` prefix: `crewai skill install @org/name`.

crewAIInc/crewAI · error · SystemExit

Invalid skill reference. Use the format @org/name.

Error message

Invalid skill reference. Use the format @org/name.

What it means

`crewai skill install <ref>` validates that the reference starts with `@`. A reference without the leading `@` fails immediately with SystemExit(1) before any network call, because the registry API is keyed by the `@org/name` format.

Source

Thrown at lib/cli/src/crewai_cli/skills/main.py:86

        console.print(
            f"[green]Created skill [bold]{name}[/bold] at [bold]{skill_dir}[/bold].[/green]"
        )
        console.print(f"Edit [bold]{skill_md}[/bold] to define the skill instructions.")

    def install(self, ref: str) -> None:
        """Download and install a registry skill.

        Format: @org/name

        Inside a crew project (pyproject.toml present): installs to ./skills/{name}/
        Outside a project: installs to ~/.crewai/skills/{org}/{name}/
        """
        if not ref.startswith("@"):
            console.print(
                "[red]Invalid skill reference. Use the format @org/name.[/red]"
            )
            raise SystemExit(1)

        without_at = ref[1:]
        if without_at.count("/") != 1:
            console.print(
                "[red]Invalid skill reference. Use the format @org/name.[/red]"
            )
            raise SystemExit(1)

        org, name = without_at.split("/", 1)
        if (
            not org
            or not name
            or org.startswith(".")
            or name.startswith(".")
            or len(Path(org).parts) != 1
            or len(Path(name).parts) != 1
        ):
            console.print(

View on GitHub (pinned to 754d7323be)

Solutions

Add the `@` prefix: `crewai skill install @org/name`.
Confirm the exact published name via `crewai skill list` or the registry UI before retrying.

Example fix

# before
crewai skill install crewai/writing
# after
crewai skill install @crewai/writing

Defensive patterns

Strategy: validation

Validate before calling

import re

def is_valid_skill_ref(ref: str) -> bool:
    return bool(re.match(r"^@[^/\s]+/[^/\s]+$", ref))

assert is_valid_skill_ref("@org/name")      # True
assert not is_valid_skill_ref("org/name")    # missing @

Type guard

def is_skill_ref(ref: str) -> bool:
    """Narrow a CLI argument to a valid @org/name registry reference."""
    return isinstance(ref, str) and is_valid_skill_ref(ref)

Prevention

Always type the ref as `@org/name` — the `@` is mandatory.
Validate refs with the regex before shelling out to the CLI so failures surface in your code, not the CLI's.
Keep a canonical list of installed skill refs in your project docs to copy from.

When it happens

Trigger: Passing `crewai skill install org/name` (missing `@`), `crewai skill install https://crewai.com/...`, or a bare skill name like `crewai skill install researcher`. The check is literally `ref.startswith("@")`.

Common situations: Copying a skill URL or a plain `org/name` string from docs, chat, or a README that omits the `@`; muscle memory from other package managers (pip/npm style names without sigils).

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/7f807cd40adbb193. Report an issue: GitHub.