{"record":{"id":"7e15bc5ac24aab99","repo":"microsoft/aspire","slug":"aspire-skills-bundle-skill-0-skill-md-description-is-1","errorCode":null,"errorMessage":"Aspire skills bundle skill '{0}' SKILL.md description is {1} characters; agent hosts accept at most {2}.","messagePattern":"Aspire skills bundle skill '(.+?)' SKILL\\.md description is (.+?) characters; agent hosts accept at most (.+?)\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Cli/Agents/AspireSkills/AspireSkillsBundleProvider.cs","lineNumber":352,"sourceCode":"\n        if (!string.Equals(frontmatterName, skillName, StringComparison.Ordinal))\n        {\n            throw new InvalidOperationException(string.Format(\n                CultureInfo.InvariantCulture,\n                \"Aspire skills bundle skill '{0}' SKILL.md frontmatter name '{1}' must match its manifest and directory name.\",\n                skillName,\n                frontmatterName));\n        }\n\n        var description = GetFrontmatterValue(content, \"description\");\n        if (string.IsNullOrWhiteSpace(description))\n        {\n            throw new InvalidOperationException(string.Format(CultureInfo.InvariantCulture, \"Aspire skills bundle skill '{0}' must define a frontmatter description in SKILL.md.\", skillName));\n        }\n\n        if (description.Length > MaxSkillDescriptionLength)\n        {\n            throw new InvalidOperationException(string.Format(\n                CultureInfo.InvariantCulture,\n                \"Aspire skills bundle skill '{0}' SKILL.md description is {1} characters; agent hosts accept at most {2}.\",\n                skillName,\n                description.Length,\n                MaxSkillDescriptionLength));\n        }\n    }\n\n    private static string? GetFrontmatterValue(string content, string key)\n    {\n        var normalizedContent = content.ReplaceLineEndings(\"\\n\");\n        if (!normalizedContent.StartsWith(\"---\\n\", StringComparison.Ordinal))\n        {\n            return null;\n        }\n\n        var frontmatterEndIndex = normalizedContent.IndexOf(\"\\n---\\n\", 4, StringComparison.Ordinal);\n        if (frontmatterEndIndex < 0)","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Cli/Agents/AspireSkills/AspireSkillsBundleProvider.cs#L334-L370","documentation":"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.","triggerScenarios":"Calling AspireSkillsBundleProvider.CreateAsync (via ValidateFile/ValidateSkillFileFrontmatter) on a bundle whose SKILL.md frontmatter contains a description longer than 1024 characters.","commonSituations":"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.","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"],"exampleFix":"// before (SKILL.md frontmatter)\ndescription: A very long 1500-character description that explains every detail of the skill, including all parameters, examples, historical notes, and troubleshooting steps...\n// after\ndescription: Runs the Aspire deploy pipeline for the current AppHost.","handlingStrategy":"validation","validationCode":"var description = frontmatter[\"description\"]?.Trim() ?? \"\";\nif (description.Length > 1024)\n    throw new Exception($\"Skill '{name}' description is {description.Length} chars; max is 1024.\");","typeGuard":null,"tryCatchPattern":"try { await provider.CreateAsync(...); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"description is\")) { /* shorten SKILL.md description */ }","preventionTips":["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"],"tags":["skills","frontmatter","validation","cli"],"backgroundTag":"value-out-of-range","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}