alibaba/spring-ai-alibaba · error · IllegalStateException

Skill description is required

Error message

Skill description is required

What it means

SkillMetadata.Builder.build() validates that a skill loaded from a SKILL.md frontmatter has a non-empty description and throws IllegalStateException when it is missing or empty. The library requires every registered skill to advertise what it does, since descriptions are used by the model to decide when to invoke a skill. This is a fail-fast invariant check during skill metadata construction.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/skills/SkillMetadata.java:169

			return this;
		}

		public Builder fullContent(String fullContent) {
			metadata.fullContent = fullContent;
			return this;
		}

		public Builder allowedTools(List<String> allowedTools) {
			metadata.allowedTools = allowedTools == null ? List.of() : List.copyOf(allowedTools);
			return this;
		}

		public SkillMetadata build() {
			if (metadata.name == null || metadata.name.isEmpty()) {
				throw new IllegalStateException("Skill name is required");
			}
			if (metadata.description == null || metadata.description.isEmpty()) {
				throw new IllegalStateException("Skill description is required");
			}
			if (metadata.skillPath == null || metadata.skillPath.isEmpty()) {
				throw new IllegalStateException("Skill path is required");
			}
			if (metadata.allowedTools == null) {
				metadata.allowedTools = List.of();
			}
			return metadata;
		}
	}
}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add a non-empty 'description:' field to the skill's SKILL.md YAML frontmatter
2. Verify frontmatter delimiters (---) are intact so the description is actually parsed
3. Set description explicitly via SkillMetadata.builder().description("...") when building programmatically

Example fix

// before (SKILL.md)
---
name: my-skill
---
// after
---
name: my-skill
description: Performs X when the user asks for Y
---

String desc = frontmatter.get("description");
if (desc == null || desc.isBlank()) throw new IllegalArgumentException("SKILL.md must define a non-empty description");

boolean hasDescription(SkillMetadata m) { return m.getDescription() != null && !m.getDescription().isEmpty(); }

try { metadata = builder.build(); } catch (IllegalStateException e) { log.error("Invalid skill metadata: {}", e.getMessage()); skipSkill(); }

When it happens

Trigger: Calling SkillMetadata.builder()...build() (directly or via a registry loading SKILL.md files) when the parsed frontmatter lacks the 'description' field or it is an empty string.

Common situations: A SKILL.md file in the skills directory omits the YAML frontmatter 'description:' key, has an empty description value, or malformed frontmatter caused the parser to leave description null.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Skill path is required
• Skill path cannot be null or empty
• INVALID_PARAMS
• Oauth2UserNotFound
• InvalidParameter

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/6d983ee005931ff6. Report an issue: GitHub.