Audit Skill Conflicts

audit-skill-conflicts — Pack coherence, not product QA

Degree of freedom: MIXED — Phases 0–1 [HIGH freedom]; Phase 2 routing dry-run [LOW freedom] — skip explicitly if the harness cannot show selection. Never write audit-responsive-layout.

Read-only. Most other audit-* skills inspect an app or repository you ship. This one inspects the skill pack it lives in.

npm run validate:skills checks each file in isolation (name = dir, description ≤320, body <500). It cannot see two skills giving opposite advice, six descriptions all matching "audit my UI", a handoff to a renamed skill, or a greedy description that fires constantly and burns context.

A skill collection is a system. Its failure modes are between files.

Present findings. Rewrite nothing until approved. Highest-leverage first: description rewrites (routing) — they change which skill fires without changing any skill's behavior.

This skill vs neighbors

Do not fire for "create a skill" → meta-skill-creator. Do not fire for "audit my app's UI" → audit-ux / audit-responsive / audit-ui-states (this skill would flag that cluster).

How to reason

1. Observe — quote both descriptions (or rule vs skill) that appear to collide
2. Interpret — can one user phrase honor both, or do they contradict / steal routing?
3. Classify — contradiction / trigger overlap / stale ref / bloat / correct carve-out
4. Severity — opposite stance on the same situation, or a greedy description, first

Worked example

Observe: "audit my UI" matches audit-ux, audit-responsive, audit-ui-states with no carve-out in two of the three descriptions. Interpret: the agent cannot know whether to score heuristics, breakpoints, or empty states. Classify: trigger overlap without disambiguation. Severity: major — wrong skill fires; wasted context. Fix: each description names when it wins (layout vs heuristics vs states).

Phase 0 — Load the corpus [HIGH freedom]

Enumerate:

• skills/*/SKILL.md and skills-cursor/*/SKILL.md
• commands/*.md and commands-portable/*.md
• agents/*.md
• rules/*.mdc and .cursor/rules/*.mdc — highest-risk. Always-on rules silently override a skill's intent.

For each skill extract: name, description (routing surface), claimed triggers, cross-referenced skills, core directives (read-only vs apply-fixes, plan-first vs edit, hard always/never). One index. Compare the set, not pairwise guesswork.

House skill name in this repo is audit-responsive. audit-responsive-layout is retired. /responsive-audit is a valid command alias, but bare/backticked responsive-audit is not a skill handoff.

Phase 1 — Conflict and drift [HIGH freedom]

Contradictory directives — Opposite behavior for an overlapping situation (e.g. "fix inline" vs "never edit in the audit pass"). Rules-vs-skill is worst. List every pair that cannot both be honored.

Trigger overlap / mis-routing — Phrases that match many skills. Example cluster in this pack:

"audit my UI" → audit-ux, audit-uiux-design-system, audit-responsive, audit-ui-states, thirdparty-web-interface-guidelines, plan-uiux-unification

Overlap is fine if each description carves out when it, specifically, applies. Flag members that do not disambiguate.

Duplicated guidance — The same block copy-pasted across skills. Drift risk. Name an extraction target (shared rule or one canonical skill).

Stale cross-references — Handoff to a renamed/removed skill. Resolve every backtick skill name against the live directory list.

Scope gaps & double-coverage — Two skills claiming the same task with no delineation, or a chain step no skill owns. This is pack coverage, not product gaps.

Context-budget bloat — Over-broad descriptions (narrow skill, greedy triggers). Bodies near the 500-line cap that a 60-line skill could hold. Headroom exists because context is scarce; the pack should respect that.

Convention drift — Family-placement (audit-and-fix under enhance-* is OK when called out, like enhance-email-deliverability). Inconsistent read-only/plan-only semantics inside a family. Description-voice drift.

Phase 2 — Routing dry-run (optional) [LOW freedom — skip honestly]

If a harness can show which skill the agent selects for a phrase, feed realistic user lines and record matches. Ambiguous phrases that should map to one skill but match several confirm Phase 1 empirically.

Cursor / Claude Code usually do not expose selection. Skip this phase explicitly; static description analysis still stands. Do not pretend a dry-run ran.

Definition of Done

• Corpus indexed: skills + commands + subagents + rules
• Contradictory-directive pairs listed (rules-vs-skill included)
• Trigger-overlap clusters identified; carve-outs checked
• Duplicated blocks + extraction targets named
• Cross-refs resolved; dangling listed (incl. retired audit-responsive-layout and bare responsive-audit skill handoffs)
• Double-coverage and handoff gaps surfaced
• Bloat / convention drift noted
• Routing dry-run run or explicitly skipped
• Nothing edited without approval

Self-critique before reporting [LOW freedom — do not skip]

1. Quoted pair — every contradiction cites both texts
2. Dry-run honesty — skipped if no harness; do not pretend it ran
3. Name hygiene — retired audit-responsive-layout and bare responsive-audit skill handoffs listed; /responsive-audit command kept
4. Right owner — how to write a skill → meta-skill-creator; how to upgrade prompts → enhance-skill-prompts
5. Nothing rewritten until approved; description fixes first (routing)

Output format

1. Conflict table — A | B (or rule) | type | why they can't coexist | severity
2. Trigger-overlap clusters — phrase | skills | who should win | description fix
3. Dangling references — skill | broken ref | correct target
4. Coverage map — double-coverage + gaps
5. Bloat / convention — item | issue | fix
6. Fix plan — description rewrites first, then dedupe/extraction, then convention. Propose only.

Related

• meta-skill-creator — write a new SKILL.md
• enhance-skill-prompts — upgrade an existing skill's prompt (T1–T6), not its behavior
• validate:skills — per-file spec after description edits
• enhance-agent-guardrails — app-repo policy, not pack coherence
• plan-docs-sync — docs vs code
• audit-responsive / audit-ux / audit-ui-states — the UI-audit cluster this skill is expected to flag