microsoft/aspire · error · InvalidOperationException

Aspire skills bundle skill

Error message

Aspire skills bundle skill '{0}' SKILL.md description is {1} characters; agent hosts accept at most {2}.

What it means

Aspire.Cli validates every SKILL.md in a skills bundle before installing it. The frontmatter 'description' field is required and must be at most 1024 characters (MaxSkillDescriptionLength), because agent hosts (Claude Code, Codex, etc.) reject longer descriptions. This InvalidOperationException is thrown when a skill's description exceeds that limit.

Solutions

Shorten the 'description' field in the skill's SKILL.md frontmatter to 1024 characters or fewer
Move long instructions from the description into the SKILL.md body, keeping the description as a short summary
Run the bundle validation locally after editing frontmatter to confirm it passes

Example fix

// before (SKILL.md frontmatter)
description: A very long 1500-character description that explains every detail of the skill, including all parameters, examples, historical notes, and troubleshooting steps...
// after
description: Runs the Aspire deploy pipeline for the current AppHost.

Defensive patterns

Strategy: validation

Validate before calling

var description = frontmatter["description"]?.Trim() ?? "";
if (description.Length > 1024)
    throw new Exception($"Skill '{name}' description is {description.Length} chars; max is 1024.");

Try / catch

try { await provider.CreateAsync(...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("description is")) { /* shorten SKILL.md description */ }

Prevention

Keep SKILL.md descriptions under ~200 chars as a habit; the hard limit is 1024
Add a lint step in CI that parses frontmatter and checks description length
Put detailed guidance in the skill body, not the description

When it happens

Trigger: Calling AspireSkillsBundleProvider.CreateAsync (via ValidateFile/ValidateSkillFileFrontmatter) on a bundle whose SKILL.md frontmatter contains a description longer than 1024 characters.

Common situations: Hand-authored skill files with verbose descriptions; AI-generated SKILL.md files that ramble; editing a description to add usage notes without checking length; copying long documentation into the description field.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/7e15bc5ac24aab99. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Cli/Agents/AspireSkills/AspireSkillsBundleProvider.cs:352

        if (!string.Equals(frontmatterName, skillName, StringComparison.Ordinal))
        {
            throw new InvalidOperationException(string.Format(
                CultureInfo.InvariantCulture,
                "Aspire skills bundle skill '{0}' SKILL.md frontmatter name '{1}' must match its manifest and directory name.",
                skillName,
                frontmatterName));
        }

        var description = GetFrontmatterValue(content, "description");
        if (string.IsNullOrWhiteSpace(description))
        {
            throw new InvalidOperationException(string.Format(CultureInfo.InvariantCulture, "Aspire skills bundle skill '{0}' must define a frontmatter description in SKILL.md.", skillName));
        }

        if (description.Length > MaxSkillDescriptionLength)
        {
            throw new InvalidOperationException(string.Format(
                CultureInfo.InvariantCulture,
                "Aspire skills bundle skill '{0}' SKILL.md description is {1} characters; agent hosts accept at most {2}.",
                skillName,
                description.Length,
                MaxSkillDescriptionLength));
        }
    }

    private static string? GetFrontmatterValue(string content, string key)
    {
        var normalizedContent = content.ReplaceLineEndings("\n");
        if (!normalizedContent.StartsWith("---\n", StringComparison.Ordinal))
        {
            return null;
        }

        var frontmatterEndIndex = normalizedContent.IndexOf("\n---\n", 4, StringComparison.Ordinal);
        if (frontmatterEndIndex < 0)

View on GitHub (pinned to 25830f84bd)