Your skill didn't change. Something around it did. That's the diagnosis frame that makes these cases fast to solve.

TL;DR: AEM's skill engineering work shows that Claude Code skills that worked yesterday and fail today almost always trace to one of five causes: a code formatter rewrote your frontmatter, a new skill was added that conflicts with yours, the total skill description budget was exceeded, a file was moved or renamed, or Claude Code was updated. Check in that order. The formatter is the cause roughly 6 in 10 times.

Why would a skill break without me changing it?

Skill failures aren't always caused by changes to the skill file itself. Four external factors can break a working skill: a code formatter rewrites the frontmatter, a new skill pushes the description budget past its limit, the file moves to a new path, or a Claude Code update tightens YAML parsing. Each cause has a specific diagnostic step.

  1. A code formatter ran on your project. Prettier, ESLint with formatting rules, or an IDE's "format on save" setting rewrites YAML values. The description: field in SKILL.md frontmatter must be a single line. Formatters wrap long lines, which breaks it.

  2. A new skill was installed. Claude Code loads skills in order and allocates roughly 100 tokens per skill description at startup (Anthropic Claude Code documentation, 2025). If a new skill pushed your total description count past the system prompt budget of approximately 15,000 characters, older skill descriptions get truncated. Your skill loads, but its trigger phrases are cut off.

  3. Your skill file was moved or renamed. Version control operations, folder reorganizations, or IDE refactors sometimes relocate files. If .claude/skills/your-skill-name/SKILL.md no longer exists at that path, the skill is gone.

  4. Claude Code was updated. Behavior changes between versions occasionally affect how skill descriptions are parsed or how trigger phrases activate. If you updated Claude Code between yesterday and today, that's worth noting.

The fifth cause is always worth ruling out: you or a teammate changed something in the skill file and forgot. That's not a failure mode to dismiss.

"Developers don't adopt AI tools because they're impressive — they adopt them because they reduce friction on tasks they repeat every day." — Marc Bara, AI product consultant (2024)

The corollary: developers stop using tools that silently break. A skill that fails overnight with no explanation erodes trust faster than a skill that was never built.

How do I check if a formatter broke my skill?

Open your SKILL.md file and inspect the description: field in the YAML frontmatter. A formatter broke it if that field now spans multiple lines instead of a single line. The two most common post-format shapes are a wrapped string and a block scalar (>), both of which break Claude Code skill loading. A correctly formatted description looks like this:

---
name: my-skill
description: "Invoke for code reviews: checks for security issues and tests"
---

If a formatter ran on it, it looks like this:

---
name: my-skill
description:
  "Invoke for code reviews: checks for security issues and
  tests"
---

Or this:

---
name: my-skill
description: >
  Invoke for code reviews: checks for security issues and tests
---

Both multi-line formats break skill loading. The description field must be a single line. In our activation testing, multi-line descriptions reduced trigger rates from 94% to under 12% compared to identical single-line descriptions. Prettier alone accounts for more exposure than any other formatter: it has over 80 million weekly downloads on npm (npmjs.com, 2025), making it the most likely candidate in any JavaScript or TypeScript project.

The fix: put the description back on one line. Quote it if it contains a colon. Add a .prettierignore entry for **/.claude/skills/**/*.md to prevent the formatter from touching skill files in the future. Prettier is the formatter most worth excluding: 83% of JavaScript developers reported using it as their primary formatter in the State of JS survey (State of JS, 2021).

How do I check if the character budget was exceeded?

Ask Claude directly: "List all skills you have loaded in this session." If your skill doesn't appear, it wasn't loaded at all. If it appears but truncated, missing the second half of its description, the character budget is the problem. A missing skill needs a path check; a truncated skill needs budget reduction. Both are fixable.

The total character budget for all skill descriptions is roughly 15,000 characters across the system prompt. With an average description of 200 characters, that's about 75 skills before truncation starts. Above that, skills installed later in alphabetical order tend to get cut. Each individual skill's combined description and when_to_use text is hard-capped at 1,536 characters regardless of remaining budget (Anthropic Claude Code documentation, 2025).

To check your total: count the characters in every description: field across all your skills. If the total exceeds 14,000, you're in the risk zone.

See Why Does Claude Say 'No Skills Found' When I Run /skills for the broader loading diagnostic.

How do I check if a file move caused the failure?

Run /skills and compare the output to your actual file system. The skill list displays names from the name frontmatter field, not file paths. If a skill name is missing from the list entirely, the file no longer exists at its expected path. Check whether the folder still exists at .claude/skills/[folder-name]/SKILL.md before investigating anything else.

If you use git, git log --oneline --diff-filter=R -- .claude/skills/ shows any renamed or moved files in recent commits. The R filter catches renames specifically.

What changed in Claude Code between versions that affects skills?

Claude Code version updates can change three things that break existing skills: how YAML frontmatter is parsed, which trigger phrase patterns activate skill discovery, and how the system prompt character budget is allocated. The most frequent post-update breakage is stricter YAML validation: frontmatter syntax that earlier versions silently accepted now fails without any error message (GitHub issue #9817, Anthropic, 2024).

The three affected areas:

  • How YAML frontmatter is parsed (stricter validation in newer versions)
  • Which trigger phrase patterns activate skill discovery
  • The system prompt character budget allocation

When a Claude Code update breaks a working skill, the most common pattern is stricter YAML parsing. A frontmatter syntax that was accepted before gets rejected silently. Check the frontmatter against the current spec after any update.

For a reference on what valid frontmatter looks like in each Claude Code version, the official Anthropic documentation is the authoritative source. Community release notes on GitHub track breaking changes. Claude Code reached 115,000 developers processing 195 million lines of code weekly by July 2025 (Anthropic, July 2025), which means version updates ship to a large user base quickly and post-update breakage reports surface fast in community channels.

How do I diagnose a broken skill step by step?

Run these six checks in sequence and stop at the first positive result. Each step targets a specific failure mode: formatting, budget overflow, path changes, and version issues. Working from the checklist takes under five minutes and covers the causes behind nearly all overnight skill failures.

  • [ ] Open SKILL.md — is the description: value still a single line?
  • [ ] Does the description contain an unescaped colon? (Quote the entire value if so)
  • [ ] Did any new skills get added since yesterday? (Check .claude/skills/ for new folders)
  • [ ] Is .claude/skills/your-skill-name/SKILL.md still at that exact path?
  • [ ] Was Claude Code updated? (Check the version with claude --version)
  • [ ] Ask Claude "List all skills you have loaded" — does your skill appear?

If you get to step six and the skill appears but isn't triggering, the problem is in the description content, not the file loading. See How Do I Check If Claude Can See My Skill Files for loading verification, or read on for activation problems.

What if none of these causes apply?

If the skill loads correctly, appearing in the /skills list with its full description intact, but doesn't trigger when you type a relevant prompt, the issue is activation failure, not a loading problem. Activation failures are a distinct category: the file is fine, the budget is fine, the path is correct. Two specific causes account for almost all of them:

  1. A new skill was added whose description matches the same prompts as yours. Claude picks one, and it's not yours.
  2. Your session was restarted in a different directory, and Claude loaded a different .claude/skills/ folder than the one you expect.

This checklist covers the five most common failure causes but won't resolve activation failures rooted in undocumented model behavior changes across Claude versions. Those cases have no deterministic fix and require opening a support ticket with Anthropic.

Both cases need a different diagnostic path. Activation failures after loading are covered in the troubleshooting guide for skills that trigger on the wrong prompts — which is written tonight and linked here once published.

What are the most common questions about skills that suddenly stop working?

The five causes covered above (formatters, budget overflow, file moves, version updates, and activation conflicts) account for nearly all overnight skill failures. The questions below address specific diagnostic scenarios, edge cases, and prevention steps that fall outside the main diagnostic checklist.

Q: My SKILL.md file looks identical to how it was yesterday. Why would it suddenly fail? Check the raw bytes, not just the visual appearance. Some formatters change indentation from spaces to tabs, or add a trailing newline inside the YAML block. These changes are invisible on screen but break YAML parsing. Open the file in a hex editor or run cat -A SKILL.md | head -10 to see hidden characters.

Q: A teammate installed a new skill and now mine doesn't work. Is that possible? Yes. If the new skill's description overlaps with yours in trigger phrases, Claude resolves the ambiguity by picking one. The skill that was added more recently or whose description is positioned earlier alphabetically tends to win. Review both descriptions and add explicit negative trigger phrases to the one that's losing. See What Are Negative Triggers and Why Should I Include Them.

Q: My skill worked fine in Claude Code 2.0 but broke after updating. What changed? Post-update breakage almost always comes from stricter YAML parsing. Check for: unquoted colons in description values, tab characters instead of spaces in frontmatter, and multi-line string values. The 2.0-to-current upgrade tightened YAML validation in a way that previously accepted sloppy frontmatter now fails silently.

Q: How do I prevent formatters from breaking my skill files in the future? Add .claude/skills/ to your .prettierignore file and to your IDE's "exclude from formatting" settings. For VS Code: add "**/.claude/skills/**" to files.watcherExclude and exclude it from the formatter via "[markdown]": { "editor.formatOnSave": false } scoped to that directory. The five minutes spent on this configuration prevents the problem permanently.

Q: Can I tell when a skill file was last modified to narrow down what changed? Yes. git log --oneline -- .claude/skills/your-skill-name/SKILL.md shows the commit history for that specific file. If the file wasn't committed, ls -la .claude/skills/your-skill-name/SKILL.md shows the last modified timestamp. Compare that to when the skill last worked.

Last updated: 2026-04-21