Evaluation Methodology
Unverified●30/40Claude Code◐PartialHas SKILL.md but declares no allowed-tools — Claude Code will ask for permission each time
Cursor·UnknownWe have not crawled the repo tree, so we will not guess
Codex·UnknownWe have not crawled the repo tree, so we will not guess
Gemini CLI·UnknownThe spec defines no detection rule for Gemini
Copilot·UnknownWe have not crawled the repo tree, so we will not guess
npx agentalley add evaluation-methodologyWho is stuck, and on what
PluginEval quality methodology — dimensions, rubrics, statistical methods, and scoring formulas. Use this skill when understanding how plugin quality is measured, when interpreting a low score on a specific dimension, when deciding how to improve a skill's triggering accuracy or orchestration fitness, when calibrating scoring thresholds for your marketplace, or when explaining quality badges to external partners like Neon.
The whole source
Frontmatter — 2 properties
| name | evaluation-methodology |
|---|---|
| description | PluginEval quality methodology — dimensions, rubrics, statistical methods, and scoring formulas. Use this skill when understanding how plugin quality is measured, when interpreting a low score on a specific dimension, when deciding how to improve a skill's triggering accuracy or orchestration fitness, when calibrating scoring thresholds for your marketplace, or when explaining quality badges to external partners like Neon. |
| 1 | --- |
| 2 | name: evaluation-methodology |
| 3 | description: "PluginEval quality methodology — dimensions, rubrics, statistical methods, and scoring formulas. Use this skill when understanding how plugin quality is measured, when interpreting a low score on a specific dimension, when deciding how to improve a skill's triggering accuracy or orchestration fitness, when calibrating scoring thresholds for your marketplace, or when explaining quality badges to external partners like Neon." |
| 4 | ---A5 — No allowed-tools declared — no way to tell what this skill may touch |
| 5 | |
| 6 | # Evaluation Methodology |
| 7 | |
| 8 | This document is the authoritative reference for how PluginEval measures plugin and skill quality. |
| 9 | It covers the three evaluation layers, all ten scoring dimensions, the composite formula, badge |
| 10 | thresholds, anti-pattern flags, Elo ranking, and actionable improvement tips. |
| 11 | |
| 12 | Related: [Full rubric anchors](references/rubrics.md) |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## The Three Evaluation Layers |
| 17 | |
| 18 | PluginEval stacks three complementary layers. Each layer produces a score between 0.0 and 1.0 for |
| 19 | each applicable dimension, and later layers override or blend with earlier ones according to |
| 20 | per-dimension blend weights. |
| 21 | |
| 22 | ### Layer 1 — Static Analysis |
| 23 | |
| 24 | **Speed:** < 2 seconds. No LLM calls. Deterministic. |
| 25 | |
| 26 | The static analyzer (`layers/static.py`) runs six sub-checks directly against the parsed SKILL.md: |
| 27 | |
| 28 | | Sub-check | What it measures | |
| 29 | |---|---| |
| 30 | | `frontmatter_quality` | Name presence, description length, trigger-phrase quality | |
| 31 | | `orchestration_wiring` | Output/input documentation, code block count, orchestrator anti-pattern | |
| 32 | | `progressive_disclosure` | Line count vs. sweet-spot (200–600 lines), references/ and assets/ bonuses | |
| 33 | | `structural_completeness` | Heading density, code blocks, examples section, troubleshooting section | |
| 34 | | `token_efficiency` | MUST/NEVER/ALWAYS density, duplicate-line repetition ratio | |
| 35 | | `ecosystem_coherence` | Cross-references to other skills/agents, "related"/"see also" mentions | |
| 36 | |
| 37 | These six sub-checks feed directly into six of the ten final dimensions (via `STATIC_TO_DIMENSION` |
| 38 | mapping). The remaining four dimensions — `output_quality`, `scope_calibration`, |
| 39 | `robustness`, and part of `triggering_accuracy` — receive no static contribution and rely |
| 40 | entirely on Layer 2 and/or Layer 3. |
| 41 | |
| 42 | **Anti-pattern penalty** is applied multiplicatively to the Layer 1 score: |
| 43 | |
| 44 | ``` |
| 45 | penalty = max(0.5, 1.0 − 0.05 × anti_pattern_count) |
| 46 | ``` |
| 47 | |
| 48 | Each additional detected anti-pattern reduces the score by 5%, flooring at 50%. |
| 49 | |
| 50 | ### Layer 2 — LLM Judge |
| 51 | |
| 52 | **Speed:** 30–90 seconds. One or more LLM calls (Sonnet by default). Non-deterministic. |
| 53 | |
| 54 | The `eval-judge` agent reads the SKILL.md and any `references/` files, then scores four |
| 55 | dimensions using anchored rubrics (see [references/rubrics.md](references/rubrics.md)): |
| 56 | |
| 57 | 1. **Triggering accuracy** — F1 score derived from 10 mental test prompts |
| 58 | 2. **Orchestration fitness** — Worker purity assessment (0–1 rubric) |
| 59 | 3. **Output quality** — Simulates 3 realistic tasks; assesses instruction quality |
| 60 | 4. **Scope calibration** — Judges depth and breadth relative to the skill's category |
| 61 | |
| 62 | The judge returns a structured JSON object (no markdown fences) that the eval engine merges |
| 63 | into the composite. When `judges > 1`, scores are averaged and Cohen's kappa is reported as |
| 64 | an inter-judge agreement metric. |
| 65 | |
| 66 | ### Layer 3 — Monte Carlo Simulation |
| 67 | |
| 68 | **Speed:** 5–20 minutes. N=50 simulated Agent SDK invocations (default). Statistical. |
| 69 | |
| 70 | Monte Carlo runs `N` real prompts through the skill and records: |
| 71 | |
| 72 | - **Activation rate** — Fraction of prompts that triggered the skill |
| 73 | - **Output consistency** — Coefficient of variation (CV) across quality scores |
| 74 | - **Failure rate** — Error/crash fraction with Clopper-Pearson exact CIs |
| 75 | - **Token efficiency** — Median token count, IQR, outlier count |
| 76 | |
| 77 | The Layer 3 composite formula: |
| 78 | |
| 79 | ``` |
| 80 | mc_score = 0.40 × activation_rate |
| 81 | + 0.30 × (1 − min(1.0, CV)) |
| 82 | + 0.20 × (1 − failure_rate) |
| 83 | + 0.10 × efficiency_norm |
| 84 | ``` |
| 85 | |
| 86 | where `efficiency_norm = max(0, 1 − median_tokens / 8000)`. |
| 87 | |
| 88 | --- |
| 89 | |
| 90 | ## Composite Scoring Formula |
| 91 | |
| 92 | The final score is a weighted blend across all three layers for each dimension, then summed: |
| 93 | |
| 94 | ``` |
| 95 | composite = Σ(dimension_weight × blended_dimension_score) × 100 × anti_pattern_penalty |
| 96 | ``` |
| 97 | |
| 98 | ### Dimension Weights |
| 99 | |
| 100 | | Dimension | Weight | Why it matters | |
| 101 | |---|---|---| |
| 102 | | `triggering_accuracy` | 0.25 | A skill that never fires — or fires incorrectly — has no value | |
| 103 | | `orchestration_fitness` | 0.20 | Skills must be pure workers; supervisor logic belongs in agents | |
| 104 | | `output_quality` | 0.15 | Correct, complete output is the primary deliverable | |
| 105 | | `scope_calibration` | 0.12 | Neither a stub nor a bloated monster | |
| 106 | | `progressive_disclosure` | 0.10 | SKILL.md is lean; detail lives in references/ | |
| 107 | | `token_efficiency` | 0.06 | Minimal context waste per invocation | |
| 108 | | `robustness` | 0.05 | Handles edge cases without crashing | |
| 109 | | `structural_completeness` | 0.03 | Correct sections in the right order | |
| 110 | | `code_template_quality` | 0.02 | Working, copy-paste-ready examples | |
| 111 | | `ecosystem_coherence` | 0.02 | Cross-references; no duplication with siblings | |
| 112 | |
| 113 | ### Layer Blend Weights |
| 114 | |
| 115 | Each dimension draws from different layers at different ratios. With all three layers active |
| 116 | (`--depth deep` or `certify`): |
| 117 | |
| 118 | | Dimension | Static | Judge | Monte Carlo | |
| 119 | |---|---|---|---| |
| 120 | | `triggering_accuracy` | 0.15 | 0.25 | 0.60 | |
| 121 | | `orchestration_fitness` | 0.10 | 0.70 | 0.20 | |
| 122 | | `output_quality` | 0.00 | 0.40 | 0.60 | |
| 123 | | `scope_calibration` | 0.30 | 0.55 | 0.15 | |
| 124 | | `progressive_disclosure` | 0.80 | 0.20 | 0.00 | |
| 125 | | `token_efficiency` | 0.40 | 0.10 | 0.50 | |
| 126 | | `robustness` | 0.00 | 0.20 | 0.80 | |
| 127 | | `structural_completeness` | 0.90 | 0.10 | 0.00 | |
| 128 | | `code_template_quality` | 0.30 | 0.70 | 0.00 | |
| 129 | | `ecosystem_coherence` | 0.85 | 0.15 | 0.00 | |
| 130 | |
| 131 | At `--depth standard` (static + judge only), blends are renormalized to drop the Monte Carlo |
| 132 | column. At `--depth quick` (static only), all weight falls on Layer 1. |
| 133 | |
| 134 | ### Blended Score Calculation |
| 135 | |
| 136 | For a given depth, the blended score for dimension `d` is: |
| 137 | |
| 138 | ``` |
| 139 | blended[d] = Σ( layer_weight[d][layer] × layer_score[d][layer] ) |
| 140 | ───────────────────────────────────────────────────── |
| 141 | Σ( layer_weight[d][layer] for available layers ) |
| 142 | ``` |
| 143 | |
| 144 | This normalization ensures that skipping Monte Carlo at standard depth doesn't artificially |
| 145 | deflate scores. |
| 146 | |
| 147 | --- |
| 148 | |
| 149 | ## Interpreting Dimension Scores |
| 150 | |
| 151 | Each dimension score is a float in `[0.0, 1.0]`. The CLI converts it to a letter grade: |
| 152 | |
| 153 | | Grade | Score range | Meaning | |
| 154 | |---|---|---| |
| 155 | | A | 0.90 – 1.00 | Excellent — no meaningful improvement needed | |
| 156 | | B | 0.80 – 0.89 | Good — minor gaps only | |
| 157 | | C | 0.70 – 0.79 | Adequate — one or two clear improvement areas | |
| 158 | | D | 0.60 – 0.69 | Marginal — needs targeted work | |
| 159 | | F | < 0.60 | Failing — significant remediation required | |
| 160 | |
| 161 | When reading a report, focus first on the lowest-graded dimension that has the highest weight. |
| 162 | A D in `triggering_accuracy` (weight 0.25) costs far more than a D in `ecosystem_coherence` |
| 163 | (weight 0.02). |
| 164 | |
| 165 | **Confidence intervals** appear in the report when Layer 2 or Layer 3 ran. Narrow CIs (± < 5 |
| 166 | points) indicate stable scores. Wide CIs suggest inconsistency — often caused by an ambiguous |
| 167 | description or instructions that work for some prompt styles but not others. |
| 168 | |
| 169 | --- |
| 170 | |
| 171 | ## Quality Badges |
| 172 | |
| 173 | Badges require both a composite score threshold AND an Elo threshold (when Elo is available). |
| 174 | The `Badge.from_scores()` logic checks composite first, then Elo if provided: |
| 175 | |
| 176 | | Badge | Composite | Elo | Meaning | |
| 177 | |---|---|---|---| |
| 178 | | Platinum ★★★★★ | ≥ 90 | ≥ 1600 | Reference quality — suitable for gold corpus | |
| 179 | | Gold ★★★★ | ≥ 80 | ≥ 1500 | Production ready | |
| 180 | | Silver ★★★ | ≥ 70 | ≥ 1400 | Functional, has improvement opportunities | |
| 181 | | Bronze ★★ | ≥ 60 | ≥ 1300 | Minimum viable — not yet recommended for users | |
| 182 | | — | < 60 | any | Does not meet minimum bar | |
| 183 | |
| 184 | The Elo threshold is skipped when Elo has not been computed (i.e., at quick or standard depth |
| 185 | without `certify`). A skill can earn a badge on composite score alone in those cases. |
| 186 | |
| 187 | --- |
| 188 | |
| 189 | ## Anti-Pattern Flags |
| 190 | |
| 191 | The static analyzer detects five anti-patterns. Each carries a severity multiplier that feeds |
| 192 | into the penalty formula. |
| 193 | |
| 194 | ### OVER_CONSTRAINED |
| 195 | |
| 196 | **Trigger:** More than 15 occurrences of MUST, ALWAYS, or NEVER in the SKILL.md. |
| 197 | |
| 198 | **Problem:** Overly prescriptive instructions reduce model flexibility, increase token overhead, |
| 199 | and signal that the author is trying to micromanage every output rather than providing |
| 200 | principled guidance. |
| 201 | |
| 202 | **Fix:** Audit every MUST/ALWAYS/NEVER. Replace directive language with explanatory framing |
| 203 | where possible. Reserve hard constraints for genuine safety or correctness requirements. Target |
| 204 | fewer than 10 such directives per 100 lines. |
| 205 | |
| 206 | ### EMPTY_DESCRIPTION |
| 207 | |
| 208 | **Trigger:** The frontmatter `description` field is fewer than 20 characters after stripping. |
| 209 | |
| 210 | **Problem:** Without a meaningful description, the Claude Code plugin system cannot determine |
| 211 | when to invoke the skill. The skill becomes invisible to autonomous invocation. |
| 212 | |
| 213 | **Fix:** Write a description of at least 60–120 characters that includes: |
| 214 | - A "Use this skill when..." or "Use when..." trigger clause |
| 215 | - Two or more concrete contexts separated by commas or "or" |
| 216 | |
| 217 | ### MISSING_TRIGGER |
| 218 | |
| 219 | **Trigger:** The description does not contain "use when", "use this skill when", |
| 220 | "use proactively", or "trigger when" (case-insensitive). |
| 221 | |
| 222 | **Problem:** Even a long description is useless for autonomous invocation if it doesn't |
| 223 | include a clear trigger signal. The system's routing model needs an explicit cue. |
| 224 | |
| 225 | **Fix:** Prepend "Use this skill when..." to the description, followed by specific scenarios. |
| 226 | Example: "Use this skill when measuring plugin quality, interpreting score reports, or |
| 227 | explaining badge thresholds to a team." |
| 228 | |
| 229 | ### BLOATED_SKILL |
| 230 | |
| 231 | **Trigger:** SKILL.md exceeds 800 lines AND the skill has no `references/` directory. |
| 232 | |
| 233 | **Problem:** A monolithic SKILL.md forces the entire document into context on every invocation, |
| 234 | wasting tokens on content only needed in edge cases. |
| 235 | |
| 236 | **Fix:** Create a `references/` directory and move supporting material there: |
| 237 | - Detailed rubrics → `references/rubrics.md` |
| 238 | - Extended examples → `references/examples.md` |
| 239 | - Configuration reference → `references/config.md` |
| 240 | |
| 241 | The SKILL.md should link to these files with `[text](references/filename.md)` so the model |
| 242 | can fetch them on demand.A4 — This skill pulls in web or user content but never says to treat that content as data. A signal, not proof. |
| 243 | |
| 244 | ### ORPHAN_REFERENCE |
| 245 | |
| 246 | **Trigger:** SKILL.md contains a markdown link `[text](references/filename)` where |
| 247 | `filename` does not exist in the `references/` directory. |
| 248 | |
| 249 | **Problem:** Dead links waste tokens on context that will never resolve and confuse the model. |
| 250 | |
| 251 | **Fix:** Either create the missing reference file or remove the dead link. |
| 252 | |
| 253 | ### DEAD_CROSS_REF |
| 254 | |
| 255 | **Trigger:** SKILL.md references another skill or agent by relative path and that path |
| 256 | cannot be resolved from the skills/ directory. |
| 257 | |
| 258 | **Problem:** Broken ecosystem links undermine the plugin's coherence score and may cause |
| 259 | the model to attempt navigation to non-existent files. |
| 260 | |
| 261 | **Fix:** Verify the referenced skill exists. Update the path or remove the reference. |
| 262 | |
| 263 | --- |
| 264 | |
| 265 | ## Elo Ranking |
| 266 | |
| 267 | PluginEval uses an Elo/Bradley-Terry rating system to rank a skill against the gold corpus. |
| 268 | |
| 269 | **Starting rating:** 1500 (the corpus median by convention). |
| 270 | |
| 271 | **K-factor:** 32 (standard for moderate-stakes ratings). |
| 272 | |
| 273 | **Expected score formula** (standard Elo): |
| 274 | |
| 275 | ``` |
| 276 | E(A vs B) = 1 / (1 + 10^((B_rating − A_rating) / 400)) |
| 277 | ``` |
| 278 | |
| 279 | **Rating update after each matchup:** |
| 280 | |
| 281 | ``` |
| 282 | new_rating = old_rating + 32 × (actual_score − expected_score) |
| 283 | ``` |
| 284 | |
| 285 | where `actual_score` is 1.0 for a win, 0.5 for a draw, 0.0 for a loss. |
| 286 | |
| 287 | **Confidence intervals** are computed via 500-sample bootstrap, reported as 95% CI. |
| 288 | **Corpus percentile** reflects pairwise win rate against the gold corpus. |
| 289 | **Position bias check:** Pairs are evaluated in both orders; disagreements are flagged. |
| 290 | |
| 291 | The `plugin-eval init` command builds the corpus index from a plugins directory: |
| 292 | |
| 293 | ```bash |
| 294 | plugin-eval init ./plugins --corpus-dir ~/.plugineval/corpus |
| 295 | ``` |
| 296 | |
| 297 | --- |
| 298 | |
| 299 | ## CLI Reference |
| 300 | |
| 301 | ### Score a skill (quick static analysis only) |
| 302 | |
| 303 | ```bash |
| 304 | plugin-eval score ./path/to/skill --depth quick |
| 305 | ``` |
| 306 | |
| 307 | Returns Layer 1 results in < 2 seconds. Useful for fast feedback during authoring. |
| 308 | |
| 309 | ### Score with LLM judge (default) |
| 310 | |
| 311 | ```bash |
| 312 | plugin-eval score ./path/to/skill |
| 313 | ``` |
| 314 | |
| 315 | Runs static + LLM judge (standard depth). Takes 30–90 seconds. |
| 316 | |
| 317 | ### Score with full output as JSON |
| 318 | |
| 319 | ```bash |
| 320 | plugin-eval score ./path/to/skill --output json |
| 321 | ``` |
| 322 | |
| 323 | Emits structured JSON including `composite.score`, `composite.dimensions`, and |
| 324 | `layers[0].anti_patterns`. Suitable for CI integration: |
| 325 | |
| 326 | ```bash |
| 327 | plugin-eval score ./path/to/skill --depth quick --output json --threshold 70 |
| 328 | # exits with code 1 if score < 70 |
| 329 | ``` |
| 330 | |
| 331 | ### Full certification (all three layers + Elo) |
| 332 | |
| 333 | ```bash |
| 334 | plugin-eval certify ./path/to/skill |
| 335 | ``` |
| 336 | |
| 337 | Runs static + LLM judge + Monte Carlo (50 simulations) + Elo ranking. Takes 15–20 minutes. |
| 338 | Assigns a quality badge. Use before publishing a skill to the marketplace. |
| 339 | |
| 340 | ### Head-to-head comparison |
| 341 | |
| 342 | ```bash |
| 343 | plugin-eval compare ./skill-a ./skill-b |
| 344 | ``` |
| 345 | |
| 346 | Evaluates both skills at quick depth and prints a dimension-by-dimension comparison table. |
| 347 | Useful for deciding between two implementations or measuring improvement before/after a |
| 348 | rewrite. |
| 349 | |
| 350 | ### Initialize corpus for Elo |
| 351 | |
| 352 | ```bash |
| 353 | plugin-eval init ./plugins |
| 354 | ``` |
| 355 | |
| 356 | Builds the local corpus index at `~/.plugineval/corpus`. Required before Elo ranking works. |
| 357 | |
| 358 | ### Scripting the Composite Formula |
| 359 | |
| 360 | Reproduce the composite score offline (pre-commit hook, CI gate): |
| 361 | |
| 362 | ```python |
| 363 | def composite_score(dimension_scores: dict, anti_pattern_count: int = 0) -> float: |
| 364 | """Replicate the PluginEval composite formula.""" |
| 365 | WEIGHTS = { |
| 366 | "triggering_accuracy": 0.25, |
| 367 | "orchestration_fitness": 0.20, |
| 368 | "output_quality": 0.15, |
| 369 | "scope_calibration": 0.12, |
| 370 | "progressive_disclosure": 0.10, |
| 371 | "token_efficiency": 0.06, |
| 372 | "robustness": 0.05, |
| 373 | "structural_completeness":0.03, |
| 374 | "code_template_quality": 0.02, |
| 375 | "ecosystem_coherence": 0.02, |
| 376 | } |
| 377 | raw = sum(WEIGHTS[d] * s for d, s in dimension_scores.items()) |
| 378 | penalty = max(0.5, 1.0 - 0.05 * anti_pattern_count) |
| 379 | return round(raw * 100 * penalty, 2) |
| 380 | |
| 381 | # Example: a skill with a weak triggering score |
| 382 | scores = { |
| 383 | "triggering_accuracy": 0.65, # D — needs description work |
| 384 | "orchestration_fitness": 0.85, |
| 385 | "output_quality": 0.80, |
| 386 | # … fill in remaining 7 dimensions … |
| 387 | } |
| 388 | # composite_score(scores, anti_pattern_count=1) → ~76.5 |
| 389 | ``` |
| 390 | |
| 391 | ### JSON Output Format |
| 392 | |
| 393 | Top-level shape of `--output json`: |
| 394 | |
| 395 | ```json |
| 396 | { |
| 397 | "composite": { "score": 76.5, "badge": "Silver", "elo": null }, |
| 398 | "dimensions": { |
| 399 | "triggering_accuracy": { "score": 0.65, "grade": "D", "ci_low": 0.60, "ci_high": 0.70 }, |
| 400 | "orchestration_fitness": { "score": 0.85, "grade": "B", "ci_low": 0.80, "ci_high": 0.90 } |
| 401 | }, |
| 402 | "layers": [ |
| 403 | { "name": "static", "duration_ms": 1243, "anti_patterns": ["OVER_CONSTRAINED"] }, |
| 404 | { "name": "judge", "duration_ms": 48200, "judges": 1, "kappa": null } |
| 405 | ] |
| 406 | } |
| 407 | ``` |
| 408 | |
| 409 | Parse `composite.score` in CI to gate deployments: |
| 410 | |
| 411 | ```bash |
| 412 | score=$(plugin-eval score ./my-skill --output json | python3 -c "import sys,json; print(json.load(sys.stdin)['composite']['score'])") |
| 413 | if (( $(echo "$score < 70" | bc -l) )); then |
| 414 | echo "Quality gate failed: score $score < 70" |
| 415 | exit 1 |
| 416 | fi |
| 417 | ``` |
| 418 | |
| 419 | --- |
| 420 | |
| 421 | ## Tips for Improving a Skill's Score |
| 422 | |
| 423 | Work through dimensions in weight order. The largest gains come from fixing the top-weighted |
| 424 | dimensions first. |
| 425 | |
| 426 | ### Which Dimension to Improve First |
| 427 | |
| 428 | Use this table when a score report shows multiple D/F grades and you need to prioritize effort. |
| 429 | |
| 430 | | Dimension | Weight | Typical fix effort | Score impact / hour | Fix first if… | |
| 431 | |---|---|---|---|---| |
| 432 | | `triggering_accuracy` | 0.25 | Low — description rewrite | High | Score < 70 overall | |
| 433 | | `orchestration_fitness` | 0.20 | Medium — restructure sections | High | Skill mixes worker + supervisor logic | |
| 434 | | `output_quality` | 0.15 | Medium — add examples | Medium | Judge score < 0.70 | |
| 435 | | `scope_calibration` | 0.12 | Low — move content to references/ | Medium | File is < 100 or > 800 lines | |
| 436 | | `progressive_disclosure` | 0.10 | Low — create references/ dir | Medium | No references/ directory exists | |
| 437 | | `token_efficiency` | 0.06 | Low — reduce MUST/ALWAYS/NEVER | Low | Anti-pattern count ≥ 3 | |
| 438 | | `robustness` | 0.05 | Low — add Troubleshooting section | Low | No edge-case handling documented | |
| 439 | | `structural_completeness` | 0.03 | Very low — add headings/code blocks | Low | Fewer than 4 H2 headings | |
| 440 | | `code_template_quality` | 0.02 | Very low — add language tags | Very low | Code blocks missing language tags | |
| 441 | | `ecosystem_coherence` | 0.02 | Very low — add Related section | Very low | No cross-references at all | |
| 442 | |
| 443 | **Rule of thumb:** Fix `triggering_accuracy` before anything else — at weight 0.25 it delivers |
| 444 | more composite-score gain per hour than all low-weight dimensions combined. |
| 445 | |
| 446 | ### Triggering Accuracy (weight 0.25) |
| 447 | |
| 448 | - Include "Use this skill when..." followed by 3–4 comma-separated specific contexts. |
| 449 | - Add "proactively" if the skill should auto-activate without an explicit user request. |
| 450 | - Mental test: write 5 prompts that should trigger it and 5 that should not — does |
| 451 | your description discriminate? If not, add or tighten the context phrases. |
| 452 | |
| 453 | ### Orchestration Fitness (weight 0.20) |
| 454 | |
| 455 | - Document what the skill *receives* and what it *returns* — not what it orchestrates. |
| 456 | - Avoid "orchestrate", "coordinate", "dispatch", "manage workflow" in SKILL.md. |
| 457 | - Include an "Output format" section and 2+ code blocks showing concrete worker behavior. |
| 458 | |
| 459 | ### Output Quality (weight 0.15) |
| 460 | |
| 461 | - Give specific, actionable instructions — not just goals. |
| 462 | - Cover at least one edge case explicitly (empty input, malformed data, etc.). |
| 463 | - Include an examples section showing representative inputs and expected outputs. |
| 464 | - The more concrete the instructions, the higher the judge will score this dimension. |
| 465 | |
| 466 | ### Scope Calibration (weight 0.12) |
| 467 | |
| 468 | - Target 200–600 lines. Below 100 is a stub; above 800 without `references/` is bloat. |
| 469 | - Move background reading, extended examples, and reference tables to `references/`. |
| 470 | - Very narrow skills should be merged with a sibling; very broad ones should be split. |
| 471 | |
| 472 | ### Progressive Disclosure (weight 0.10) |
| 473 | |
| 474 | - Add a `references/` directory (earns 0.15–0.25 bonus) and keep SKILL.md focused on |
| 475 | the execution path. An `assets/` directory adds a further bonus. |
| 476 | |
| 477 | ### Token Efficiency (weight 0.06) |
| 478 | |
| 479 | - Audit MUST/ALWAYS/NEVER count. Target < 1 per 10 lines. |
| 480 | - Consolidate near-duplicate bullet points and repeated-structure tables. |
| 481 | |
| 482 | ### Robustness (weight 0.05) |
| 483 | |
| 484 | - Add a "Troubleshooting" or "Edge Cases" section covering at least 3 failure modes. |
| 485 | - State what the skill returns when it cannot complete its task. |
| 486 | |
| 487 | ### Structural Completeness (weight 0.03) |
| 488 | |
| 489 | - Ensure at least 4 H2/H3 headings, 3 code blocks, an Examples section, and a Troubleshooting section. |
| 490 | |
| 491 | ### Code Template Quality (weight 0.02) |
| 492 | |
| 493 | - All code blocks must be syntactically valid and copy-paste ready with language tags. |
| 494 | |
| 495 | ### Ecosystem Coherence (weight 0.02) |
| 496 | |
| 497 | - Add a "## Related" section listing sibling skills or agents with relative paths. |
| 498 | - Avoid duplicating content that already exists in another skill — link to it instead. |
| 499 | |
| 500 | --- |
| 501 | |
| 502 | ## Troubleshooting |
| 503 | |
| 504 | ### "Score is much lower than expected after adding content" |
| 505 | |
| 506 | The anti-pattern penalty compounds. Run with `--output json` and inspect |
| 507 | `layers[0].anti_patterns`. If you have 5+ anti-patterns, the multiplier can reduce your |
| 508 | score to 75% of its raw value regardless of how good the content is. Fix the flags first. |
| 509 | |
| 510 | ### "triggering_accuracy is low despite a detailed description" |
| 511 | |
| 512 | The `_description_pushiness` scorer looks for specific syntactic patterns, not just length. |
| 513 | Verify your description contains the phrase "Use this skill when" or "Use when" (exact |
| 514 | phrasing matters — it's a regex match). Also check that you have multiple use cases separated |
| 515 | by commas or "or" to earn the specificity bonus. |
| 516 | |
| 517 | ### "LLM judge scores vary significantly between runs" |
| 518 | |
| 519 | This is expected for ambiguous skills. The judge generates 10 mental test prompts |
| 520 | non-deterministically. Improve score stability by tightening the description and adding |
| 521 | concrete examples. When `judges > 1`, averaged scores will be more stable. Use |
| 522 | `--depth deep` with `certify` which runs Monte Carlo to get statistically-bounded scores. |
| 523 | |
| 524 | ### "progressive_disclosure score is low even though the file is the right length" |
| 525 | |
| 526 | Check whether the file is in the 200–600 line sweet spot. Files shorter than 100 lines |
| 527 | score only 0.20 on this sub-check. Also confirm that `references/` files are not empty — |
| 528 | the scorer checks for non-empty reference files, not just the directory. |
| 529 | |
| 530 | ### "compare shows my rewrite scores lower than the original" |
| 531 | |
| 532 | Quick depth (`--depth quick`) only runs static analysis. If the rewrite moved content to |
| 533 | `references/` and shortened SKILL.md significantly, static scores for structural completeness |
| 534 | may drop even though overall quality improved. Run `--depth standard` for a fairer comparison |
| 535 | that includes the LLM judge's assessment of content quality. |
| 536 | |
| 537 | --- |
| 538 | |
| 539 | ## References |
| 540 | |
| 541 | - [Full Rubric Anchors — all 4 judge dimensions](references/rubrics.md) |
| 542 | |
| 543 | ### Related Agents |
| 544 | |
| 545 | - **eval-judge** (`../../agents/eval-judge.md`) — the LLM judge that scores Layer 2 dimensions |
| 546 | (`triggering_accuracy`, `orchestration_fitness`, `output_quality`, `scope_calibration`). |
| 547 | Invoke directly when you need to re-run only the judge layer or inspect its reasoning. |
| 548 | - **eval-orchestrator** (`../../agents/eval-orchestrator.md`) — the top-level orchestrator that |
| 549 | sequences all three layers, merges results, assigns badges, and writes the final report. |
| 550 | Invoke when running a full certification pass or comparing two skills head-to-head. |
| 551 |
Reviews
Installed this one?Write the first review and take the Trailblazer badge.
Alternatives
Subagent Driven DevelopmentUse when executing implementation plans with independent tasks in the current session◐◐◐◐◐●36/40Python Code Style & DocumentationPython code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.◐····●35/40Competitor Price Analysis 💲Competitor pricing strategy analysis and market positioning. Price mapping, pricing gaps identification, elasticity signals evaluation, and strategic pricing optimization. Use when the user asks about competitor pricing, price analysis, pricing strategy, or co◐····●34/40Competitor Price Tracker 📊Set up competitor price tracking and monitoring workflows. Track price changes, detect promotions, analyze pricing patterns, and get alerts for competitive price movements.◐····●34/40