Skill Quality Linter

The Problem

You published 12 skills on Agensi. Three have zero installs. Five have user complaints about "not triggering." You assumed the content was good — the instructions are detailed, the examples are thorough, the code works. But the skill never activates because the description is topic-shaped ("Provides analysis for data tasks") instead of trigger-shaped ("Use when reviewing SQL queries for injection, N+1 patterns, or missing indexes"). The SKILL.md body exceeds 500 lines, overwhelming the context window. The name is duplicated as an H1 heading, wasting tokens. Scripts referenced in the instructions don't exist in the scripts/ directory. You're publishing skills that are technically correct but functionally invisible.

What You Get

• Seven-category audit covering Routing Metadata (description quality, trigger keywords, token budget), Body Structure (section presence, length, examples), Resource Organization (missing scripts/references, inline example bloat), Prohibited Content (dangerous code execution, hardcoded secrets, piped remote execution), Behavioral Safety (permission boundaries, rigid directives), Portability (OS-specific, model-specific, hardcoded paths), and Scope Conflicts (overlapping descriptions, generic names)
• 30 specific defect IDs (R1.1 through R7.3) each with a precise detection rule and line-number citation — not "the description seems vague" but "R1.3: Description is topic-shaped ('Provides analysis') instead of trigger-shaped ('Use when analyzing')"
• Quality scoring — Pass (0 defects), Warn (1-2 warnings, no failures), Fail (any FAIL defect or 3+ warnings) — with a 100-point numeric score calculated as 100 - (fail_count × 20) - (warn_count × 5)
• Remediation recommendations for each defect — R1.3 gets "Rewrite as 'Use when [trigger condition], before [action], to achieve [result]'", R3.2 gets "Move inline examples to references/examples.md", R6.3 gets "Add compatibility field with min agent version and supported platforms"
• Automated structural fixes for mechanical defects: removing duplicate H1 headings, extracting inline examples to references/ directory, adding missing compatibility frontmatter fields
• Benchmarked against the 138K-skill study — your skill is measured against the actual defect distribution found in the largest analysis of published agent skills

Why This Beats Prompting It Yourself

When you manually review your skill description, you evaluate it against your own knowledge of the skill's purpose. But the retrieval matcher doesn't know your purpose — it only knows token overlap with the user's task description. A description that makes perfect sense to you ("Comprehensive database optimization toolkit") triggers on zero of the 15 most common user queries about SQL performance. This skill runs a systematic 30-point audit across every defect category found in the research, producing a score and specific fix recommendations — not vibes-based "this could be better" feedback.

Example Session

You: "Lint my sql-query-reviewer skill before I publish it."

Agent output:

SKILL QUALITY AUDIT — sql-query-reviewer
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CATEGORY R1 — Routing Metadata:
  [PASS] R1.1: Description exists
  [PASS] R1.2: Description > 20 characters
  [FAIL] R1.3: Description is topic-shaped
    Line 4: "Review SQL queries for correctness and performance"
    → Rewrite: "Use when reviewing SQL queries for injection, N+1 patterns,
       missing indexes, or ORM-generated SQL performance issues"
  [PASS] R1.4: Trigger keywords present
  [PASS] R1.5: Name within 64 characters

CATEGORY R2 — Body Structure:
  [WARN] R2.4: Name duplicated as H1 heading
    Line 1: "# SQL Query Reviewer" duplicates name field
  [PASS] R2.5: 3 concrete examples present

CATEGORY R3 — Resource Organization:
  [PASS] R3.1: Referenced scripts exist
  [WARN] R3.2: 7 inline examples (threshold: 5)
    → Move 4 examples to references/examples.md

CATEGORY R4 — Prohibited Content: [PASS] No issues
CATEGORY R5 — Behavioral Safety: [PASS] Permission boundaries documented
CATEGORY R6 — Portability: [PASS] Compatibility field present
CATEGORY R7 — Scope Conflicts: [PASS] Description is specific

SCORE: 85/100
VERDICT: WARN — Good but improvable
FIX PRIORITY:
  1. R1.3: Rewrite description as trigger-shaped (highest impact on activation)
  2. R3.2: Move 4 inline examples to references/
  3. R2.4: Remove duplicate H1 heading

Use Cases

• Pre-publish quality check for any SKILL.md before marketplace submission
• Catalogue audit when a skill has low installs or "not triggering" complaints
• Quality consistency pass across 10+ published skills
• Post-AI-generation audit (AI-marked skills have more safety and portability defects)
• Training skill authors on the 7 defect categories that hurt discoverability

Known Limitations

The audit is based on the 2026 arXiv reusability study's 7 defect categories — it may not cover emerging defect patterns not yet documented in research. Description rewrite suggestions (R1.3/R1.4) are highest-impact but most subjective; the skill generates a suggestion but the author decides the final wording. R7.1 (scope conflict with other skills) requires the full catalogue context — when auditing a single skill, this check is skipped unless the catalogue list is provided. A 100-point score on a very short skill doesn't mean the skill is useful — add a minimum body-length gate (>1000 chars) before interpreting the score.