Skill Compliance Enforcer

The Problem

You published a SKILL.md with 20 detailed instructions. Your agent loads it, acknowledges it, then does whatever it wants. You've seen GitHub issues with 100% failure rates across multiple worktrees — 20M+ tokens wasted on skills the agent reads but never follows. The root cause isn't content quality; it's structural. Instructions placed late in the document have exponentially lower compliance rates, and the agent's attention window narrows as it processes each section.

What You Get

• 20-check compliance audit organized into four categories: Attention Window (5 checks on description matching, constraint density, section count, instruction ratio, dead zones), Constraint Enforcement (5 checks on blocking directives, consequences, anti-memory patterns, pre-commitment, output locks), Structural Integrity (5 checks on step sequences, decision points, file size, repetition, abstract-to-concrete ratio), and Trigger & Invocation (5 checks on invocation patterns, negative triggers, memory override, verification commands, agent portability)
• Compliance score (0-100) with each check producing PASS (5 points), WARN (3 points), or FAIL (0 points) and specific fix recommendations
• Priority fix ordering ranked by compliance impact — tells you exactly what to change first for maximum effect
• Root cause diagnosis — distinguishes between "never triggers" (Description Match failure), "triggers but ignores" (Constraint Enforcement failure), and "partially follows" (Structural Integrity failure)
• Auto-fix generation — optionally produces a patched version of the SKILL.md with compliance fixes applied, preserving the original as backup
• Dead zone detection — identifies sections over 500 words with no actionable instruction that dilute agent attention

Why This Beats Prompting It Yourself

"Write better instructions" is the generic advice. But the research shows the problem is structural: the same instructions at 200 words deep have 70% compliance; at 500 words deep, they drop to 30%. Suggestions have near-zero compliance; blocking directives with consequences hit 85%. This skill applies the 20 structural patterns derived from real-world failure data to tell you exactly what's wrong with your SKILL.md's structure — not its content.

Example Session

You: "Why does my code-review skill get ignored?"

Agent: "SKILL COMPLIANCE ENFORCER — AUDIT REPORT Skill: code-review File: ~/.hermes/skills/code-review/SKILL.md Date: 2026-07-15

COMPLIANCE SCORE: 41/100

CRITICAL ISSUES (must fix before publishing): A2 FAIL: First-Paragraph Constraint Density — your most important rule ('MUST check for hardcoded secrets') is in section 4, 1,200 words deep. MOVE to first 200 words. Fix: add 'NEVER skip security checks' to the opening paragraph.

B1 FAIL: Blocking Directive Count — zero blocking directives found. All instructions are phrased as suggestions ('Consider checking...', 'You may want to review...'). Change to 'MUST', 'NEVER', 'DO NOT'. Fix: convert at least 3 critical rules to blocking directives.

B5 FAIL: Output Format Lock — no output template defined. Agent has no format to follow, so it invents its own. Fix: add a concrete report template with placeholders.

WARNINGS (fix for best results): A3 WARN: 14 sections — >12 sections dilutes attention. Merge related sections. A4 WARN: 35% imperative sentences — mostly descriptive. Rewrite as actionable instructions. D1 WARN: No explicit invocation pattern — agent doesn't know when to activate this skill.

OVERALL ASSESSMENT: This skill is NOT ready to publish. The #1 fix: move your security-checking constraint to the first 200 words and convert suggestion language to blocking directives. Expected score after fixes: 75+/100."

Use Cases

• Pre-publishing audit before adding a skill to a marketplace
• Debugging why a specific skill never triggers in your agent
• Quality assurance on skills your team writes for internal use
• Batch auditing an entire skills directory for compliance readiness
• Refactoring a long SKILL.md that partially works but isn't reliable

Known Limitations

This skill analyzes SKILL.md structural patterns — it does not test whether the skill works at runtime in an actual agent session. Some compliance improvements may need iteration based on real-world testing. The scoring system is calibrated on documented failure cases; edge cases in highly specialized skills may produce different compliance dynamics.