zylon-ai/private-gpt · error · ValueError

NAME_INVALID_FORMAT

NAME_INVALID_FORMAT

Error message

name must be lowercase alphanumeric with single hyphens only

What it means

SkillFrontmatter's name field validator enforces the skill naming convention (lowercase alphanumeric plus single hyphens) via a full regex match and raises ValueError with code NAME_INVALID_FORMAT when the name does not conform. A second check rejects consecutive hyphens. This mirrors the Claude/agent skill packaging convention so skill names are filesystem- and URL-safe.

Source

Thrown at private_gpt/components/skills/parser.py:40

    )
    license: str | None = Field(default=None)
    compatibility: str | None = Field(default=None)
    metadata: dict[str, str] | None = Field(default=None)
    allowed_tools_raw: str | None = Field(default=None, alias="allowed-tools")

    @property
    def allowed_tools(self) -> list[str] | None:
        raw = self.allowed_tools_raw
        if raw is None:
            return None
        tools = [token.strip() for token in raw.split(" ") if token.strip()]
        return tools or None

    @field_validator("name")
    @classmethod
    def validate_name(cls, value: str) -> str:
        if not _NAME_RE.fullmatch(value):
            raise ValueError(
                "name must be lowercase alphanumeric with single hyphens only"
            )
        if "--" in value:
            raise ValueError("name cannot contain consecutive hyphens")
        return value

    @field_validator("metadata", mode="before")
    @classmethod
    def validate_metadata(
        cls, value: dict[str, object] | None
    ) -> dict[str, str] | None:
        if value is None:
            return value
        return {
            key: str(val) if not isinstance(val, str) else val
            for key, val in value.items()
            if key
        }

View on GitHub (pinned to 4a030776a3)

Solutions

1. Rename to lowercase-alphanumeric-with-single-hyphens: 'data-loader' instead of 'Data_Loader'.
2. Check for consecutive hyphens, leading/trailing hyphens, and stray whitespace in the name value.
3. If generating names from filenames, normalize: `re.sub(r'[^a-z0-9]+', '-', name.lower()).strip('-')` and collapse repeats.
4. Validate names at authoring time with the same regex: ^[a-z0-9]+(-[a-z0-9]+)*$ style pattern.

Example fix

# before (SKILL.md frontmatter)
---
name: Data_Loader
description: loads data
---

# after
---
name: data-loader
description: loads data
---

import re

_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")

def valid_skill_name(name: str) -> bool:
    return bool(_NAME_RE.fullmatch(name)) and "--" not in name

def slugify(name: str) -> str:
    s = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
    return s or "unnamed-skill"

def is_valid_skill_name(value: str) -> bool:
    return (
        isinstance(value, str)
        and bool(_NAME_RE.fullmatch(value))
        and "--" not in value
    )

try:
    doc = parse_skill_markdown(content)
except SkillValidationErrors as e:
    if any(err.code is SkillErrorCode.NAME_INVALID_FORMAT for err in e.errors):
        fix_name_and_revalidate()  # prompt author with slug suggestion
    raise

When it happens

Trigger: Parsing a SKILL.md whose YAML frontmatter has a `name:` value like 'My Skill', 'data_loader', 'Data-Loader', 'a--b', or with leading/trailing hyphens — anything failing _NAME_RE.fullmatch.

Common situations: Hand-authored skills with human-readable names or underscores; names auto-generated from filenames containing spaces or uppercase; porting skills from systems with looser naming; copy-paste introducing invisible whitespace.

Related errors

• MISSING_FRONTMATTER
• INVALID_FRONTMATTER
• 'oneOf' must be an array of schemas
• 'anyOf' must be an array of schemas
• 'allOf' must be an array of schemas

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/78b4ae7ae81e91de. Report an issue: GitHub.