[andhie]

Problem

The description in SKILL.md contains <important if>, which triggers:

SKILL.md description cannot contain XML tags

claude.ai saves the description with the angle brackets removed, while Claude Code reads the original text from the file. The two products end up with different descriptions, which can change when the skill triggers.

Why descriptions can't contain XML-like tags

Skill names and descriptions are loaded into the system prompt at startup, and the Agent Skills standard recommends an XML format for Claude models, roughly:

<available_skills>
  <skill>
    <name>improve-claude-md</name>
    <description>...</description>
  </skill>
</available_skills>

Anthropic doesn't document the reason for the rule, but a raw tag like <important if> inside that block would read as markup rather than text. In practice, claude.ai strips the brackets while Claude Code keeps them, so the two products end up with different descriptions. Removing the tag avoids both problems.

Why it matters

Anthropic's skill authoring guide lists "Cannot contain XML tags" as a requirement for description (alongside non-empty and max 1,024 characters). The description is loaded into the system prompt at startup and is what Claude uses to decide whether to trigger the skill, so it needs to be valid and identical everywhere.

Change

• Replaced <important if> with "important if" in the frontmatter description.
• Rewrote the description in third person and added when-to-use triggers, following the same guide.
• The skill body is unchanged. <important if> blocks are still valid there, since the rule applies only to frontmatter fields.

Reference

https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#skill-structure

[CLAassistant]

All committers have signed the CLA.