conductor-oss/conductor · error · IllegalArgumentException

Invalid skill name '{name}'. Use 1-128 characters: letters,

Error message

Invalid skill name '{name}'. Use 1-128 characters: letters, numbers, '.', '_' or '-'.

What it means

validateSkillName throws when the skill name does not fully match `[A-Za-z0-9._-]{1,128}` — i.e. it contains characters outside the allowed set (spaces, slashes, colons, Unicode) or is longer than 128 characters. Names are used as opaque identifiers and in `name@version` keys, so the charset is locked down.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/SkillRegistryService.java:932

    private String normalizeEntryName(String name) {
        String normalized = name.replace('\\', '/');
        while (normalized.startsWith("./")) {
            normalized = normalized.substring(2);
        }
        if (normalized.isBlank() || normalized.startsWith("/") || normalized.contains("\0")) {
            throw new IllegalArgumentException("Invalid skill package path: " + name);
        }
        for (String part : normalized.split("/")) {
            if (part.isBlank() || ".".equals(part) || "..".equals(part)) {
                throw new IllegalArgumentException("Invalid skill package path: " + name);
            }
        }
        return normalized;
    }

    private void validateSkillName(String name) {
        if (!SKILL_NAME_PATTERN.matcher(name).matches()) {
            throw new IllegalArgumentException(
                    "Invalid skill name '"
                            + name
                            + "'. Use 1-128 characters: letters, numbers, '.', '_' or '-'.");
        }
    }

    private void validateVersion(String version) {
        if (!VERSION_PATTERN.matcher(version).matches()) {
            throw new IllegalArgumentException(
                    "Invalid skill version '"
                            + version
                            + "'. Use 1-128 characters: letters, numbers, '.', '_', '+', or '-'.");
        }
    }

    private String sha256Hex(byte[] bytes) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Use a lowercase kebab-case identifier: `my-skill`, `image-resizer-v2`.
2. Trim whitespace and remove disallowed characters.
3. Keep the human-readable title in the `description`/`title` field, not the name.

Example fix

// before
name: "My Cool Skill!"
// after
name: "my-cool-skill"
title: "My Cool Skill"

private static final Pattern SKILL_NAME = Pattern.compile("[A-Za-z0-9._-]{1,128}");
boolean isValidSkillName(String name) {
    return name != null && SKILL_NAME.matcher(name).matches();
}

boolean isSkillName(String s) {
    return s != null && Pattern.compile("[A-Za-z0-9._-]{1,128}").matcher(s).matches();
}

try { skillRegistry.validateName(name); }
catch (IllegalArgumentException e) { return badRequest(e.getMessage()); }

When it happens

Trigger: Publishing or updating a skill whose `name` field is, for example, `my skill` (space), `My/Skill` (slash), `café` (non-ASCII), or longer than 128 chars. The pattern.matches() call returns false.

Common situations: Author used a human-friendly display name with spaces as the identifier; copy-pasted a title with special punctuation; name accidentally includes a trailing newline or whitespace.

Related errors

• Invalid skill version '{version}'. Use 1-128 characters: let
• Missing required field: {key}
• Skill manifest name '{manifestName}' does not match package
• Skill {name} version {version} already exists with a differe
• File path is required

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/f89612fe41967aaf. Report an issue: GitHub.