Claude Code plugins have a maintenance problem that normal code tooling barely sees: the Markdown files can directly control runtime behavior.

The study analyzes 8,351 plugins and 77,773 plugin-touching commits.

In a manual sample, 74% of commits labeled docs actually changed instructions Claude reads at runtime.

After reclassification, the true docs share fell from 10.3% to 1.7%.

And then there's the problem of inside skills.

When scripts and Markdown changed together, 78% of sampled pull requests were functionally coupled. A new flag, changed model name, renamed path, or different script behavior often required the paired SKILL.md to change too.

That creates a failure mode ordinary documentation checks miss.

A stale SKILL.md can tell Claude to call an interface that no longer exists, and there is no compiler to catch the mismatch.

For plugin builders, instruction files should be treated as maintained runtime interfaces, with automated checks that keep them synchronized with scripts.

– arxiv. org/abs/2608.28497

Title: "On the Maintenance and Co-evolution of Agent Plugins: An Empirical Study of Claude Code Plugin Marketplaces"