SKILL.mdの衝突と壊れた参照をCIで検出するリンタを自作した話A custom linter was built to detect conflicting trigger conditions and broken…

A developer has published an account of building a custom linter that scans SKILL.md files for two recurring failure modes — conflicting trigger conditions and broken internal references — and runs those checks automatically inside a continuous integration pipeline. The motivation is practical: as teams accumulate more Claude skills, subtle definition errors can cause an agent to invoke the wrong skill or fail silently, and such misfires are notoriously hard to reproduce and debug after the fact.

SKILL.md is the file format at the heart of Anthropic's Agent Skills, a mechanism for packaging reusable instructions, scripts, and resources that Claude can load on demand. Each skill is described by a Markdown file with a YAML frontmatter block that typically includes a name and a description. The description matters more than it might appear, because Claude relies on it to decide when a skill is relevant. Under the progressive disclosure model, the model first reads only the lightweight metadata across all available skills, then pulls in the full body of a skill when it judges that the task matches. In effect, the description functions as a trigger condition.

That design creates a specific class of problem the linter targets. When two or more SKILL.md files carry descriptions that overlap in intent — for example, one skill for "generating SQL queries" and another for "writing database queries" — the model may face ambiguity about which to load. The author frames this as a conflicting trigger condition and argues that catching such overlaps statically is more reliable than discovering them through inconsistent runtime behavior. The linter appears to compare descriptions across the skill set and flag pairs that look too similar or explicitly collide, prompting authors to disambiguate the wording or consolidate the skills.

The second check addresses broken references. A skill body often points to supporting files, such as helper scripts, templates, or additional Markdown documents that are meant to be loaded alongside the instructions. If a file is renamed, moved, or deleted without updating the SKILL.md, the reference dangles, and the skill can degrade or fail when Claude tries to follow it. The linter validates that referenced paths actually resolve within the repository, turning what would otherwise be a silent, production-time error into a visible failure during review.

Running these checks in CI is the key operational idea. By wiring the linter into a pipeline, every pull request that touches a skill definition is validated before it merges. This shifts skill quality control leftward, closer to authoring, and gives teams a repeatable gate rather than relying on manual inspection. The approach mirrors how projects already treat configuration and documentation: tools such as markdownlint, ESLint, and schema validators enforce structure automatically, and this linter extends that discipline to the newer surface of agent skill definitions.

The broader context is that skill and agent configuration files are becoming a meaningful part of many codebases. Alongside SKILL.md, developers increasingly maintain files like CLAUDE.md and agents.md, custom slash commands, and connections defined through the Model Context Protocol. As these artifacts multiply, they inherit the same maintenance burdens as ordinary source code, including drift, duplication, and stale references. Purpose-built tooling to keep them consistent is a natural response, and this project is an example of the wider trend often described as treating prompts and agent instructions as code.

Some caveats are worth noting. Detecting conflicting triggers reliably is inherently harder than checking file paths, because judging whether two natural-language descriptions overlap is a matter of degree rather than a clean pass-or-fail test. A linter based on textual similarity is likely to produce both false positives and misses, so its warnings are probably best read as prompts for human judgment rather than absolute verdicts. The details of the implementation, and how well the heuristics generalize beyond the author's own repository, are not fully established from the summary alone.

Even so, the underlying lesson is broadly applicable. Anyone maintaining a growing library of Claude skills can benefit from encoding basic invariants — unique, well-separated triggers and valid references — as automated checks. Whether teams adopt this specific linter or build their own, moving such validation into CI is a pragmatic way to prevent hard-to-diagnose skill misfires from reaching users.