Skill: dingtom336-gif/skill-scorer (version 1.0.0)

--- name: skill-scorer description: "对任何 SKILL.md（或 skill 文件夹）进行质量评估和打分，基于行业最佳实践，生成 8 维度 100 分制的结构化质检报告，精准定位问题并提供可执行的优化建议。当用户要求评审、审计、评分、检测、质检任何 skill 时使用——哪怕只是说「这个 skill 写得怎么样？」也会触发。也支持：skill质检、skill评分、检测skill。 | Evaluate and score any SKILL.md (or skill folder) against industry best practices. Generates a structured quality report with a 100-point score across 8 dimensions, pinpoints issues, and provides actionable optimization suggestions. Use this skill whenever the user asks to review, audit, evaluate, grade, score, lint, or quality-check a skill — even if they just say 'is this skill any good?' or 'help me improve this skill'. Also triggers on: 'skill review', 'rate my skill'." version: "1.6.0" compatibility: "Claude Code, Claude.ai, Cowork, and all SKILL.md-compatible agents" changelog: | 1.6.0 — D4 orchestration criteria wording refined: clarified that Playbooks contain descriptive logic (not executable commands), Usage Examples contain executable commands, output merging can live in templates.md. README restructured to Chinese-first bilingual 1.5.0 — Dimension 4 expanded to 5 skill types: added Script-bundled and MCP-integrated with type-specific scoring criteria 1.4.0 — Dimension 4 (Workflow & Logic) adds Skill Type Detection: instruction-only / single-command / orchestration evaluated with type-specific criteria 1.3.0 — Description bilingual: Chinese first, English after, for internal platform display 1.2.0 — Added input validation and graceful degradation for non-skill files in Step 0 1.1.0 — Bilingual report output (Chinese first, English after, no interleaving) 1.0.0 — Initial release with 8-dimension scoring rubric --- # Skill: skill-scorer ## Overview A meta-skill that evaluates the quality of other skills. Given a SKILL.md file (or a complete skill folder), it performs a systematic audit across 8 dimensions, assigns a score out of 100, identifies issues by severity, and generates actionable optimization suggestions. This skill synthesizes quality criteria from Anthropic's official skill authoring best practices, the Skill Engineering Standard (v1.4.3), and community-tested patterns from production skill ecosystems. ## When to Activate User provides a skill and asks any of: - "帮我评分/打分/检测/质检 这个 skill" - "review/audit/score/grade/lint this skill" - "这个 skill 写得怎么样？" / "is this skill any good?" - "帮我优化这个 skill" (evaluate first, then suggest improvements) - Provides a SKILL.md and expects quality feedback Do NOT activate for: creating a new skill from scratch → use `skill-creator`. This skill is for **evaluation**, not generation. ## Core Workflow ### Step 0: Load the Skill Under Test Determine what the user has provided: | Input | Action | |-------|--------| | Single `SKILL.md` file | Evaluate that file | | Skill folder (with `references/`) | Evaluate all files, cross-reference consistency | | URL / GitHub link | Fetch and evaluate | | Pasted markdown content | Treat as SKILL.md | If the user has not provided a skill → ask: "请提供要评估的 SKILL.md 文件或 skill 文件夹路径。" **Input validation — before proceeding to Step 1, verify the input is actually a skill:** | Check | Condition | Action | |-------|-----------|--------| | Binary / garbled content | File is not valid text, or text is unreadable gibberish | **STOP.** Report: "This file does not appear to be a valid SKILL.md — it contains binary or unreadable content. Please provide a markdown-based skill file." Do NOT attempt to score. | | No skill markers at all | Text is valid but contains zero skill indicators (no YAML frontmatter `---`, no markdown headings resembling skill sections, no workflow/instructions) | **STOP.** Report: "This appears to be a {detected_type} file (e.g., Python script, JSON config, plain prose), not a SKILL.md. skill-scorer evaluates SKILL.md files only." Do NOT force-fit 8 dimensions onto non-skill content. | | Partial skill structure | Has some skill-like elements (e.g., YAML frontmatter exists but body is minimal, or has headings but no workflow) | **PROCEED with caveats.** Evaluate normally, but note in the report header: "⚠️ This file has incomplete skill structure — scores reflect what is present." Score missing sections as 0 in relevant dimensions rather than guessing. | ### Step 1: Parse Skill Structure Extract and inventory: - YAML frontmatter fields (`name`, `description`, `version`, `compatibility`) - Section headings and their order - References to external files (`references/`, `scripts/`, `assets/`) - Total line count and estimated token count of SKILL.md body ### Step 2: Run 8-Dimension Evaluation Read [references/rubric.md](references/rubric.md) for the complete scoring rubric. Evaluate the skill across these 8 dimensions (each scored 0-100, then weighted): | # | Dimension | Weight | What It Measures | |---|-----------|--------|------------------| | 1 | Metadata & Triggering | 15% | Name clarity, description quality, trigger coverage | | 2 | Structure & Architecture | 15% | File organization, section order, progressive disclosure | | 3 | Instruction Clarity | 15% | Actionability, conciseness, examples, tone | | 4 | Workflow & Logic | 15% | Step completeness, parameter handling, validation | | 5 | Error Handling | 10% | Fallbacks, edge cases, failure recovery | | 6 | Context Efficiency | 10% | Token budget, redundancy, information density | | 7 | Portability & Compatibility | 10% | Self-containment, cross-platform support | | 8 | Safety & Robustness | 10% | No injection risk, no hallucination traps, identity lock | ### Step 3: Identify Issues For each issue found, classify severity: | Severity | Meaning | Score Impact | |----------|---------|--------------| | 🔴 Critical | Skill will malfunction or not trigger | -10 to -15 per issue | | 🟡 Warning | Skill works but suboptimally | -3 to -8 per issue | | 🟢 Suggestion | Nice-to-have improvement | -1 to -2 per issue | ### Step 4: Generate Report Read [references/report-template.md](references/report-template.md) for the output format. The report includes: 1. **Score Card** — Overall score + per-dimension breakdown 2. **Issue List** — All findings sorted by severity 3. **Top 3 Quick Wins** — Highest-impact fixes with before/after examples 4. **Optimization Roadmap** — Prioritized improvement plan ### Step 5: Offer Follow-Up After presenting the report, ask: - "需要我帮你自动修复这些问题吗？" (auto-fix mode) - "需要对某个维度深入分析吗？" (deep-dive mode) - "需要生成优化后的 SKILL.md 吗？" (rewrite mode) ## Output Rules 1. **Bilingual report — Chinese first, English after, no interleaving.** Always output the complete report in Chinese, then a `---` separator, then the complete report in English. Never mix languages within a section. Both versions must contain identical scores, issues, and suggestions — only the language differs. 2. **Score must be justified.** Every deducted point must trace to a specific issue. 3. **Suggestions must be actionable.** Include before/after code snippets, not vague advice. 4. **Be constructive, not destructive.** Lead with what the skill does well before listing issues. 5. ❌ Never inflate scores to be polite — honest assessment helps the user improve. 6. ❌ Never evaluate based on domain correctness of the skill's content (e.g., whether hotel recommendations are good) — only evaluate skill engineering quality. ## References | File | Purpose | When to read | |------|---------|-------------| | [references/rubric.md](references/rubric.md) | Detailed scoring criteria for all 8 dimensions | Step 2: scoring | | [references/report-template.md](references/report-template.md) | Output format and report structure | Step 4: generating report | | [references/anti-patterns.md](references/anti-patterns.md) | Common skill mistakes and how to detect them | Step 3: finding issues |

path: references/anti-patterns.md
content: # Anti-Patterns — skill-scorer

> A checklist of common skill mistakes. Use this during Step 3 (Issue Identification).
> Each anti-pattern maps to a scoring dimension and has a detection method.

---

## Category A: Metadata & Triggering Failures

### A1. Missing YAML Frontmatter
**Detect:** No `---` delimited block at top of SKILL.md.
**Severity:** 🔴 Critical
**Impact:** Skill will never be discovered or triggered. Name and description are invisible to the agent.
**Fix:** Add frontmatter with at least `name` and `description`.

### A2. Vague Description
**Detect:** Description is under 20 words, uses only generic terms ("a helpful skill for tasks"), or lacks specific trigger contexts.
**Severity:** 🟡 Warning
**Impact:** Severe undertriggering. Claude won't choose this skill over alternatives.
**Fix:** Make description specific: include what the skill does, when to use it, and example trigger phrases. Be "pushy" — explicitly list contexts.

### A3. Cryptic Name
**Detect:** Name uses abbreviations (`srch-flt-v2`), internal codes (`proj-tempest-gen`), or version suffixes.
**Severity:** 🟡 Warning
**Impact:** Hard for users to discover via slash command. Hard for Claude to match semantically.
**Fix:** Use descriptive verb-noun or gerund form: `search-cheap-flights`, `generating-reports`.

### A4. No Anti-Trigger Guidance
**Detect:** No "Do NOT activate for" or "Don't use when" section.
**Severity:** 🟢 Suggestion
**Impact:** May overtrigger for related but incorrect use cases, especially if sibling skills exist.
**Fix:** Add explicit anti-triggers: "Do NOT activate for X → use skill-Y instead."

---

## Category B: Structure & Architecture Failures

### B1. Monolithic SKILL.md (>500 lines)
**Detect:** SKILL.md exceeds 500 lines without references.
**Severity:** 🟡 Warning
**Impact:** Floods the context window. Claude may lose track of instructions in a long context.
**Fix:** Extract domain knowledge, large examples, and lookup tables into `references/` files. Keep SKILL.md as the routing and workflow hub.

### B2. No Progressive Disclosure
**Detect:** All content is in SKILL.md with no references. Or references exist but SKILL.md doesn't specify when to load them.
**Severity:** 🟡 Warning
**Impact:** Wastes context tokens on information not needed for most requests.
**Fix:** Add a References table at the bottom of SKILL.md specifying each file's purpose and when to read it.

### B3. Deeply Nested References
**Detect:** A reference file references another reference file, creating a chain (references/a.md → references/b.md → references/c.md).
**Severity:** 🟡 Warning
**Impact:** Claude may fail to follow multi-hop chains, losing critical information.
**Fix:** Flatten references to max 2 levels: SKILL.md → references/X.md. No reference file should reference another.

### B4. External Path References
**Detect:** File references paths outside the skill folder (../../shared/, /global/, absolute paths).
**Severity:** 🔴 Critical
**Impact:** Skill breaks when uploaded to a different location or shared with others.
**Fix:** Copy all shared files into the skill's own directory. Each skill must be a self-contained unit.

---

## Category C: Instruction Quality Failures

### C1. Passive Voice Instructions
**Detect:** Frequent use of "should be done", "it is recommended that", "one might consider".
**Severity:** 🟢 Suggestion
**Impact:** Ambiguous instructions lead to inconsistent behavior.
**Fix:** Use imperative form: "Do X", "Use Y", "Always Z". Explain why after the instruction.

### C2. No Examples
**Detect:** Workflow or output format described in abstract terms with zero concrete examples.
**Severity:** 🟡 Warning
**Impact:** Claude must guess at the intended output format, leading to inconsistent results.
**Fix:** Add 1-3 input/output examples using realistic data. Use "Example:" blocks.

### C3. Contradictory Instructions
**Detect:** Two sections give conflicting guidance (e.g., "always include X" vs "never include X").
**Severity:** 🔴 Critical
**Impact:** Claude picks whichever instruction it encounters last, leading to unpredictable behavior.
**Fix:** Audit all instructions for consistency. Use a single source of truth for each rule.

### C4. Over-Constrained (Zero Degrees of Freedom)
**Detect:** Every single step is rigidly prescribed with no room for Claude to adapt.
**Severity:** 🟢 Suggestion
**Impact:** Skill breaks when encountering any scenario not explicitly covered.
**Fix:** Constrain outputs and safety-critical steps tightly. Give Claude freedom on approach and ordering where appropriate.

### C5. Teaching Claude What It Already Knows
**Detect:** Long explanations of basic concepts (what JSON is, how HTTP works, what an API is).
**Severity:** 🟡 Warning
**Impact:** Wastes context tokens and dilutes important instructions.
**Fix:** Remove explanations of common knowledge. Add only what Claude genuinely doesn't know (project-specific conventions, custom formats, domain mappings).

---

## Category D: Workflow & Logic Failures

### D1. Missing Workflow Steps
**Detect:** Skill describes desired output but doesn't define the steps to get there.
**Severity:** 🔴 Critical
**Impact:** Claude must improvise the entire execution path.
**Fix:** Define a numbered step sequence from input to output. Each step should have clear inputs and outputs.

### D2. No Output Validation
**Detect:** Workflow ends at "format output" with no self-check or quality gate.
**Severity:** 🟡 Warning
**Impact:** Claude may deliver outputs missing required elements (links, tags, formatting).
**Fix:** Add a final "Validate Output" step with a checklist of required elements.

### D3. Unrealistic Examples
**Detect:** Examples use placeholder data ("example.com", "John Doe", "2020-01-01") instead of realistic values.
**Severity:** 🟢 Suggestion
**Impact:** Harder for Claude to understand the expected output format in real-world context.
**Fix:** Use realistic but anonymized data: real city names, future dates, plausible IDs.

### D4. No Ambiguity Handling
**Detect:** Skill assumes user input is always complete and unambiguous. No clarification prompts defined.
**Severity:** 🟡 Warning
**Impact:** Claude either guesses (wrong) or stalls (unhelpful) on incomplete input.
**Fix:** Define parameter collection strategy: what to ask for, defaults for optional params, max questions per round.

---

## Category E: Error Handling Failures

### E1. No Fallback Paths
**Detect:** No fallback, error, or "what if" section exists.
**Severity:** 🟡 Warning (🔴 Critical for CLI-wrapping skills)
**Impact:** On failure, Claude either hallucinates an answer or silently stops.
**Fix:** Define at least: tool not available, no results, invalid input, timeout/network error.

### E2. Hallucination on Failure
**Detect:** Skill's implicit behavior on failure would be to answer from training data (no "do NOT use training data" guard).
**Severity:** 🔴 Critical (for CLI/API skills)
**Impact:** User receives fabricated data presented as real results.
**Fix:** Add explicit guard: "If [tool] fails, report the error honestly. Do NOT substitute training data."

### E3. Missing Environment Check
**Detect:** Skill depends on external tools (CLI, API, packages) but has no Step 0 verification.
**Severity:** 🟡 Warning
**Impact:** Skill fails mid-execution when dependency is missing, without a clear error message.
**Fix:** Add Step 0: check dependency → install if missing → verify → STOP if still missing.

---

## Category F: Context Efficiency Failures

### F1. Redundant Content
**Detect:** Same instruction or concept appears in 2+ places within the skill.
**Severity:** 🟢 Suggestion
**Impact:** Wastes context tokens. Risks contradictions if one copy is updated but not the other.
**Fix:** Say it once, in the most logical place. Reference it from elsewhere if needed.

### F2. Domain Knowledge in SKILL.md
**Detect:** SKILL.md contains large lookup tables, city lists, category mappings, or similar data blocks.
**Severity:** 🟡 Warning
**Impact:** Loaded into context even for queries that don't need this data.
**Fix:** Move data to `references/` files. Load on demand with clear guidance in the References table.

### F3. Verbose Metadata
**Detect:** Name + description combined exceed ~150 tokens.
**Severity:** 🟢 Suggestion
**Impact:** Every conversation pays this cost, even when the skill isn't triggered.
**Fix:** Keep name under 5 words. Keep description under 100 words. Move details to SKILL.md body.

---

## Category G: Portability & Compatibility Failures

### G1. Hardcoded Paths
**Detect:** Absolute paths or user-specific paths in skill content (/Users/alice/, C:\Users\bob\).
**Severity:** 🔴 Critical
**Impact:** Skill breaks for anyone except the original author.
**Fix:** Use relative paths within the skill folder, or environment variables.

### G2. No Dependency Declaration
**Detect:** Skill uses external tools but never lists them or provides install instructions.
**Severity:** 🟡 Warning
**Impact:** User doesn't know what to install. Claude can't recover if dependency is missing.
**Fix:** Add a Prerequisites section with install commands and version requirements.

### G3. Platform-Specific Assumptions
**Detect:** Skill assumes a specific OS, shell, or agent platform without declaring it.
**Severity:** 🟢 Suggestion
**Impact:** May fail silently on different platforms.
**Fix:** Add `compatibility` field to frontmatter. Handle platform differences in workflow (if/else on OS).

---

## Category H: Safety & Robustness Failures

### H1. Knowledge as Primary Data Source (CLI/API skills)
**Detect:** Large Domain Knowledge section with directly-usable answers (specific prices, hotel names, flight routes).
**Severity:** 🟡 Warning
**Impact:** Claude may answer from knowledge instead of executing the CLI, giving stale data.
**Fix:** Knowledge should contain mappings (intent → param), not answers. Add disclaimer: "does NOT replace execution."

### H2. No Identity Lock (CLI/API skills)
**Detect:** CLI-wrapping skill has no "CRITICAL EXECUTION RULES" or equivalent guard at the top.
**Severity:** 🟡 Warning
**Impact:** Claude treats the skill as a knowledge base rather than an execution guide.
**Fix:** Add identity lock block immediately after frontmatter.

### H3. Fabricated Parameters
**Detect:** Skill uses CLI flags or API parameters not listed in parent tool's documentation.
**Severity:** 🔴 Critical
**Impact:** Commands will fail. User loses trust.
**Fix:** Cross-validate every parameter against the tool's --help or official docs. Remove fabricated ones.

### H4. Unsanitized User Input in Commands
**Detect:** User input is directly interpolated into shell commands or code without any escaping.
**Severity:** 🟡 Warning
**Impact:** Potential injection vector if skill is used in automated pipelines.
**Fix:** Use proper quoting and escaping. Note: in most SKILL.md contexts, Claude handles this naturally, but explicit guidance helps.

---

## Quick Detection Checklist

Use this as a rapid scan before deep evaluation:

```
[ ] Frontmatter exists with name + description?
[ ] Description > 20 words and includes trigger contexts?
[ ] SKILL.md < 500 lines?
[ ] At least 1 concrete example in the workflow?
[ ] Error handling / fallback section exists?
[ ] No external path references?
[ ] References table exists (if reference files exist)?
[ ] No large data tables in SKILL.md body?
[ ] Dependencies declared (if any)?
[ ] Output validation step exists?
```


path: references/rubric.md
content: # Scoring Rubric — skill-scorer

> This rubric defines the exact criteria for each of the 8 evaluation dimensions.
> Each dimension is scored 0–100. The final score is a weighted average.

---

## Dimension 1: Metadata & Triggering (Weight: 15%)

Evaluates whether Claude can **discover and correctly activate** this skill.

### Scoring Criteria

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-20 | **YAML frontmatter exists** with `name` and `description` | Parse the `---` block at top of SKILL.md |
| 0-20 | **Name follows conventions** — descriptive, uses gerund or verb-noun form, no cryptic abbreviations | Check: would a user or LLM understand what this skill does from the name alone? |
| 0-30 | **Description is effective** — specific enough to trigger correctly, broad enough to catch edge queries, includes anti-trigger guidance | Test: given 5 hypothetical user queries, would this description cause correct triggering? |
| 0-15 | **Description is "pushy" enough** — addresses undertriggering by being explicit about when to activate | Check: does description say "use when..." or "triggers on..." with concrete examples? |
| 0-15 | **Trigger section in body** (if present) — complements description with explicit trigger phrases and anti-triggers | Check for "When to Activate" / "Do NOT activate for" sections |

### Scoring Guide

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Description alone would reliably trigger for all intended use cases. Name is intuitive. Anti-triggers defined. |
| 70-89 | Description covers main use cases but misses edge cases. Name is clear. |
| 50-69 | Description is vague or too narrow. May undertrigger or overtrigger. |
| 30-49 | Description is a generic sentence. Name is cryptic. Claude would rarely choose this skill. |
| 0-29 | Missing frontmatter, no description, or name is meaningless. |

---

## Dimension 2: Structure & Architecture (Weight: 15%)

Evaluates the **file organization and information architecture** of the skill.

### Scoring Criteria

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-20 | **SKILL.md is the entry point** — contains the core logic, not just a pointer to other files | Check that the main workflow is in SKILL.md, not buried in references |
| 0-20 | **Progressive disclosure** — 3-level loading: metadata (always) → SKILL.md body (on trigger) → references (on demand) | Check: are references clearly separated? Does SKILL.md tell Claude when to read each reference? |
| 0-15 | **SKILL.md length is appropriate** — ideally under 500 lines; if longer, must justify with complexity | Count lines. Under 200 = good. 200-500 = acceptable. Over 500 = needs splitting. |
| 0-15 | **Logical section ordering** — follows a natural flow (overview → when → how → output → references) | Check section sequence for coherence |
| 0-15 | **Reference files are well-organized** — clear naming, each file has a single purpose, SKILL.md has a reference table | Check references/ directory structure and the References section in SKILL.md |
| 0-15 | **No deeply nested references** — reference files should not reference other reference files (max 2 levels) | Check for chains of file references |

### Scoring Guide

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Clean 3-level progressive disclosure. SKILL.md under 300 lines. All references clearly mapped. |
| 70-89 | Good structure with minor issues (e.g., slightly long SKILL.md, one unclear reference). |
| 50-69 | Flat structure (everything in SKILL.md) or messy reference organization. |
| 30-49 | No separation of concerns. SKILL.md is a wall of text with no references. |
| 0-29 | Chaotic structure. Missing files. No logical organization. |

---

## Dimension 3: Instruction Clarity (Weight: 15%)

Evaluates whether the instructions are **clear, actionable, and well-written**.

### Scoring Criteria

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-20 | **Uses imperative form** — "Do X" not "You should consider doing X" | Scan for weak modal verbs (should, could, might, consider) |
| 0-20 | **Explains WHY, not just WHAT** — gives reasoning behind rules so Claude can generalize | Check: are constraints accompanied by rationale? |
| 0-20 | **Includes concrete examples** — input/output pairs, before/after, or code samples | Count examples. 0 = bad. 2-3 = good. Excessive = bloat. |
| 0-15 | **Avoids redundancy** — no repeated instructions across sections | Check for duplicate or near-duplicate content |
| 0-15 | **Right degree of freedom** — tight constraints where precision matters, loose guidance where creativity helps | Assess: is every step locked down, or does the skill trust Claude where appropriate? |
| 0-10 | **Consistent terminology** — same concept uses same term throughout | Check for inconsistent naming of the same concept |

### Scoring Guide

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Every instruction is actionable. Examples are crisp. No redundancy. Perfect balance of prescriptive and permissive. |
| 70-89 | Clear overall, but some instructions are vague or redundant. Examples present. |
| 50-69 | Mix of clear and unclear instructions. Missing examples or excessive hand-waving. |
| 30-49 | Mostly vague or passive instructions. No examples. Claude would struggle to follow. |
| 0-29 | Incomprehensible, contradictory, or absent instructions. |

---

## Dimension 4: Workflow & Logic (Weight: 15%)

Evaluates the **operational correctness and completeness** of the skill's workflow.

### Step 0: Skill Type Detection (do this BEFORE scoring)

Different skill types have fundamentally different workflow patterns. Identify the type first, then apply the matching criteria.

| Type | How to Detect | Workflow Pattern |
|------|--------------|-----------------|
| **Instruction-only** | No CLI commands, no API calls, no scripts, no external tools. Pure markdown instructions. Examples: brand-guidelines, commit-formatter, code-review checklist | Rules/templates → Claude applies them using its own judgment |
| **Single-command executor** | One CLI/API command with scenario-specific defaults. SKILL.md contains the command template directly in workflow steps | Collect params → execute one command → format output |
| **Multi-command orchestration** | Multiple CLI/API commands combined. Parameters block defines a command pool; Playbooks describe how to combine them; Usage Examples give executable samples | Detect query type → select commands → orchestrate sequence → merge outputs |
| **Script-bundled** | Has a `scripts/` directory with executable code (Python/bash/Node). SKILL.md defines when and why; scripts handle the how. Claude invokes scripts and interprets their output | SKILL.md dispatches → script executes deterministic logic → Claude interprets results |
| **MCP-integrated** | Depends on an external MCP server connection. Skill is the "knowledge layer" on top of MCP tools — it tells Claude how to use those tools effectively | Verify MCP connection → call MCP tools per skill rules → format output following skill conventions |

**Critical rules:**
- An orchestration skill that puts executable commands in Parameters + Usage Examples and orchestration logic in Playbooks is a valid design pattern — not a workflow gap. Do NOT penalize it for "playbooks contain descriptive logic instead of executable commands."
- A script-bundled skill where SKILL.md is short and delegates to scripts is a valid design pattern — the workflow completeness lives in the scripts, not in SKILL.md. Evaluate the dispatch logic and script documentation, not SKILL.md line count.
- An MCP-integrated skill that says "use MCP tool X to do Y" without reimplementing the tool's logic is correct — the skill provides workflow guidance, not tool reimplementation.

### Scoring Criteria — Instruction-Only Skills

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-25 | **Rules are complete** — cover all relevant cases, no obvious gaps | Could Claude handle edge cases with these instructions alone? |
| 0-25 | **Output format defined** — templates, examples, or structure specified | Check for output templates or format examples |
| 0-25 | **Realistic examples** — input/output pairs demonstrate correct application | Check: do examples cover typical and edge cases? |
| 0-25 | **Handles ambiguous input** — guidance for unclear or borderline cases | Check for decision criteria or "when in doubt" guidance |

### Scoring Criteria — Single-Command Executor Skills

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-20 | **Complete workflow** — all steps from param collection to output delivery | Trace: can Claude handle a request end-to-end? |
| 0-20 | **Parameter handling** — required vs. optional clear; defaults specified; collection SOP defined | Check for parameter tables, defaults, collection strategy |
| 0-15 | **Validation step exists** — self-check before delivering results | Look for output validation / quality gate step |
| 0-15 | **Step dependencies clear** — each step knows what it receives from previous | Check data flow between steps |
| 0-15 | **Realistic usage examples** — commands that would actually work | Check: real values, future dates, valid IDs? |
| 0-15 | **Handles ambiguous input** — what to do when user intent is unclear | Check for clarification prompts or default behaviors |

### Scoring Criteria — Multi-Command Orchestration Skills

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-20 | **Command pool defined** — all available commands and their parameters are listed in a structured format (Parameters block or equivalent). This is where the "what can I call" lives | Check: are all CLI/API commands the skill can use clearly documented with flags and descriptions? A well-structured Parameters block = full score |
| 0-20 | **Orchestration logic defined** — Playbooks describe how to select and combine commands based on query type. Playbooks are EXPECTED to contain descriptive/procedural logic (e.g., "Step 1: search flights → Step 2: use result to search hotels"), NOT raw executable commands. The executable form lives in Usage Examples, not here | Check: do playbooks show command selection logic and sequencing? Different playbooks should have genuinely different command combinations. Score based on clarity of orchestration logic, not whether playbook text is directly copy-pasteable into a terminal |
| 0-15 | **Query type routing** — skill determines which subset of commands to run based on user intent (e.g., single-point query vs full itinerary) | Check: does Step 1 or equivalent classify the query before executing? |
| 0-15 | **Usage Examples are executable** — the Usage Examples section in SKILL.md contains concrete command samples with realistic parameters that can be copy-pasted and run. This is separate from Playbooks — playbooks describe logic, Usage Examples demonstrate concrete invocations | Check: does the Usage Examples section contain real `cli command --flag value` lines? Are values realistic (real cities, future dates)? |
| 0-15 | **Output merging logic** — how results from multiple commands are combined into a unified response. This can be defined in SKILL.md's Output Rules, in references/templates.md, or both. Any of these locations is valid | Check: is there a defined format (table, day-by-day, sections) for presenting multi-command results together? Location doesn't matter — existence and clarity do |
| 0-15 | **Validation step exists** — self-check covers all commands' outputs, not just the last one | Check: does validation verify booking links / data sources across all command results? |

### Scoring Criteria — Script-Bundled Skills

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-20 | **Dispatch logic clear** — SKILL.md tells Claude which script to run and when, with explicit invocation commands (e.g., `Run scripts/analyze.py --input {file}`) | Check: can Claude determine which script to call from SKILL.md instructions alone? |
| 0-20 | **Script documentation** — each script's purpose, inputs, outputs, and expected behavior are documented (in SKILL.md, script comments, or references/) | Check: could Claude understand what a script returns without reading its source code? |
| 0-15 | **Dependency declaration** — required packages, runtimes, and environment prerequisites are listed | Check for Prerequisites section or equivalent. Scripts that silently fail on missing dependencies are a critical flaw |
| 0-15 | **Error handling in dispatch** — SKILL.md defines what to do when a script fails (non-zero exit, unexpected output, timeout) | Check: is there a "if script fails → do X" path? |
| 0-15 | **Output interpretation** — SKILL.md tells Claude how to read and present script output to the user | Check: does the skill define how to parse script results (JSON, HTML, plaintext) and format them? |
| 0-15 | **Self-containment** — scripts are bundled in the skill folder, not referenced as external paths | Check: are all scripts in `scripts/` within the skill directory? No `../../shared/` references? |

### Scoring Criteria — MCP-Integrated Skills

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-20 | **MCP dependency declared** — skill explicitly states which MCP server(s) it requires and how to verify connectivity | Check for: MCP server name, connection verification step, "Requires X MCP server" in Prerequisites or frontmatter |
| 0-20 | **Tool usage guidance** — skill defines which MCP tools to use, in what order, and with what parameters for each workflow | Check: does the skill go beyond "use MCP tools" to specify which tools and how? |
| 0-15 | **Connection failure handling** — skill defines what to do when MCP server is disconnected or unreachable | Check for: "MCP not connected → tell user to reconnect. Do NOT proceed." Not just generic error handling |
| 0-15 | **Workflow adds value over raw MCP** — skill provides orchestration, formatting, or domain logic that raw MCP tool calls don't | Check: would removing the skill and using MCP tools directly produce the same result? If yes, the skill adds no value |
| 0-15 | **Output formatting rules** — skill defines how to present MCP tool results to the user | Check: does the skill specify output structure, not just pass through raw MCP responses? |
| 0-15 | **Realistic usage examples** — examples show complete MCP-mediated workflows with realistic parameters | Check: do examples show the full flow (connect → call tools → format → deliver)? |

### Scoring Guide (applies to all 5 types)

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Workflow is complete for its type. All type-specific criteria met. Examples work. |
| 70-89 | Workflow is complete but some type-specific criteria lack detail. |
| 50-69 | Workflow has gaps relative to its type's requirements. |
| 30-49 | Incomplete workflow. Claude would need to improvise major steps. |
| 0-29 | No coherent workflow. Just a description of what the skill should do, not how. |

---

## Dimension 5: Error Handling (Weight: 10%)

Evaluates how the skill handles **failures, edge cases, and unexpected inputs**.

### Scoring Criteria

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-25 | **Fallback paths defined** — what to do when primary approach fails | Look for fallback/recovery sections or conditional logic |
| 0-25 | **Common failure cases covered** — at minimum: no results, invalid input, tool not available | Count addressed failure cases |
| 0-25 | **Graceful degradation** — skill provides partial value even when full execution fails | Check: does the skill have a degraded mode or helpful error message? |
| 0-25 | **No silent failures** — errors are surfaced to user, not swallowed | Check: does every error path end with user-facing communication? |

### Scoring Guide

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Comprehensive fallback for every failure mode. Graceful degradation. Honest error reporting. |
| 70-89 | Main failure cases covered. Some edge cases missing. |
| 50-69 | Only 1-2 failure cases addressed. Others would leave Claude stuck. |
| 30-49 | Minimal error handling. Claude would likely hallucinate on failure. |
| 0-29 | No error handling at all. |

---

## Dimension 6: Context Efficiency (Weight: 10%)

Evaluates how well the skill **manages the context window budget**.

### Scoring Criteria

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-25 | **No unnecessary information** — every line in SKILL.md earns its place | Ask for each section: "Would Claude make a mistake without this?" |
| 0-25 | **No information Claude already knows** — doesn't re-explain common knowledge | Check for explanations of widely-known concepts |
| 0-25 | **Heavy content is in references, not SKILL.md** — domain knowledge, large examples, lookup tables are deferred | Check: is SKILL.md bloated with data that should be in references? |
| 0-25 | **Metadata is compact** — name + description together stay under ~150 tokens | Estimate token count of frontmatter |

### Scoring Guide

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Every token is necessary. Perfect progressive disclosure. SKILL.md is lean. |
| 70-89 | Mostly efficient with minor bloat (a paragraph or two that could be cut). |
| 50-69 | Notable redundancy or unnecessary explanations. Could lose 30%+ without harm. |
| 30-49 | Significant bloat. Large knowledge sections in SKILL.md that should be deferred. |
| 0-29 | Massive context waste. Walls of text that Claude doesn't need. |

---

## Dimension 7: Portability & Compatibility (Weight: 10%)

Evaluates whether the skill **works across environments and is self-contained**.

### Scoring Criteria

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-25 | **Self-contained** — no external path references (../../shared/), all needed files are in the skill folder | Search for relative paths pointing outside the skill directory |
| 0-25 | **Cross-platform** — works on Claude Code, Claude.ai, and other SKILL.md-compatible agents, or explicitly states compatibility | Check compatibility field and instructions for environment-specific code |
| 0-25 | **Dependencies declared** — required CLIs, packages, APIs are listed with install instructions | Check for Prerequisites section or equivalent |
| 0-25 | **Environment check** — skill verifies its dependencies are available before proceeding | Check for Step 0 / environment verification logic |

### Scoring Guide

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Fully self-contained. Works everywhere. Dependencies declared and checked. |
| 70-89 | Mostly portable. Minor assumptions about environment. |
| 50-69 | Works in one environment but would fail in others. Missing dependency declarations. |
| 30-49 | References external paths. No dependency management. |
| 0-29 | Cannot function outside its original context. |

---

## Dimension 8: Safety & Robustness (Weight: 10%)

Evaluates the skill's **resilience against misuse and hallucination**.

### Scoring Criteria

| Points | Criterion | How to Check |
|--------|-----------|-------------|
| 0-25 | **Identity lock** (if applicable) — skill prevents Claude from substituting training data for real-time data | Check for "CRITICAL EXECUTION RULES" or equivalent guardrails |
| 0-25 | **No hallucination traps** — skill doesn't include large knowledge sections that Claude might use instead of executing commands | Check: does knowledge section have a "does NOT replace execution" disclaimer? |
| 0-25 | **No prompt injection risk** — skill doesn't contain patterns that could be exploited | Check for: raw user input passed unsanitized, eval() patterns, instructions to ignore previous context |
| 0-25 | **No harmful content** — skill doesn't facilitate unauthorized access, data exfiltration, or malicious behavior | Content safety review |

### Scoring Guide

| Score Range | Meaning |
|-------------|---------|
| 90-100 | Strong guardrails. No hallucination traps. Safe content. Identity lock where appropriate. |
| 70-89 | Adequate safety. Minor risks (e.g., large knowledge section without disclaimer). |
| 50-69 | Some safety concerns. Missing guardrails for a CLI-wrapping skill. |
| 30-49 | Notable risks. Knowledge could easily override execution. |
| 0-29 | Active safety issues. Prompt injection vectors or harmful content. |

---

## Final Score Calculation

```
Final Score = Σ (dimension_score × dimension_weight)

Grade scale:
  A+ : 95-100  — Production-ready, exemplary skill
  A  : 90-94   — Excellent, minor polish needed
  B+ : 85-89   — Very good, a few improvements would help
  B  : 80-84   — Good, some issues to address
  C+ : 70-79   — Acceptable, needs work in several areas
  C  : 60-69   — Below average, significant improvements needed
  D  : 40-59   — Poor, fundamental issues
  F  : 0-39    — Nonfunctional or critically flawed
```


path: references/report-template.md
content: # Report Template — skill-scorer

> **Bilingual output rule:** Always generate the FULL report in Chinese first, then a clear separator, then the FULL report in English. No interleaving. Both versions must have identical scores, issues, and suggestions.

---

## Report Language Structure

The report is a single document with two complete halves:

```
┌──────────────────────────────────┐
│  Part 1: 中文完整报告              │
│  (Header → Score Card → Strengths │
│   → Issues → Quick Wins → Roadmap │
│   → Follow-Up)                    │
├──────────────────────────────────┤
│  --- (separator)                  │
├──────────────────────────────────┤
│  Part 2: English Full Report      │
│  (Header → Score Card → Strengths │
│   → Issues → Quick Wins → Roadmap │
│   → Follow-Up)                    │
└──────────────────────────────────┘
```

Use the delivery format that matches the user's context:
- **In Claude.ai / Cowork**: Output as formatted markdown directly in conversation
- **In Claude Code**: Output as markdown AND optionally save to file if user requests

---

### Section 1: Header & Summary

**Chinese version:**
```markdown
# 🎯 Skill 质检报告

**Skill 名称:** {skill_name}
**版本:** {version or "N/A"}
**评估日期:** {date}
**总分:** {score}/100（{grade}）

> {一句话总评}
```

**English version:**
```markdown
# 🎯 Skill Quality Report

**Skill:** {skill_name}
**Version:** {version or "N/A"}
**Evaluated:** {date}
**Overall Score:** {score}/100 ({grade})

> {one_sentence_verdict}
```

### Section 2: Score Card

Present as a visual table with bar indicators.

**Chinese version — use Chinese dimension names:**

```markdown
## 📊 评分卡

| # | 维度 | 得分 | 评级 |
|---|------|------|------|
| 1 | 元数据与触发 | {score}/100 | {bar} |
| 2 | 结构与架构 | {score}/100 | {bar} |
| 3 | 指令清晰度 | {score}/100 | {bar} |
| 4 | 工作流与逻辑 | {score}/100 | {bar} |
| 5 | 错误处理 | {score}/100 | {bar} |
| 6 | 上下文效率 | {score}/100 | {bar} |
| 7 | 可移植性与兼容性 | {score}/100 | {bar} |
| 8 | 安全性与鲁棒性 | {score}/100 | {bar} |

**加权总分: {final_score}/100 — 等级: {grade}**
```

**English version — use English dimension names:**

```markdown
## 📊 Score Card

| # | Dimension | Score | Rating |
|---|-----------|-------|--------|
| 1 | Metadata & Triggering | {score}/100 | {bar} |
| 2 | Structure & Architecture | {score}/100 | {bar} |
| 3 | Instruction Clarity | {score}/100 | {bar} |
| 4 | Workflow & Logic | {score}/100 | {bar} |
| 5 | Error Handling | {score}/100 | {bar} |
| 6 | Context Efficiency | {score}/100 | {bar} |
| 7 | Portability & Compatibility | {score}/100 | {bar} |
| 8 | Safety & Robustness | {score}/100 | {bar} |

**Weighted Total: {final_score}/100 — Grade: {grade}**
```

Rating bar format:
- 90-100: `████████████ Excellent`
- 80-89:  `█████████░░ Very Good`
- 70-79:  `████████░░░ Good`
- 60-69:  `██████░░░░░ Acceptable`
- 50-59:  `█████░░░░░░ Needs Work`
- 40-49:  `████░░░░░░░ Poor`
- 0-39:   `██░░░░░░░░░ Critical`

### Section 3: Strengths

List 2-4 things the skill does well. Lead with positives.

**Chinese version:**
```markdown
## ✅ 亮点

- **{亮点标题}**: {说明}
- **{亮点标题}**: {说明}
```

**English version:**
```markdown
## ✅ Strengths

- **{strength_title}**: {explanation}
- **{strength_title}**: {explanation}
```

### Section 4: Issue List

Group by severity. Each issue must have: location, description, impact, and fix suggestion.

**Chinese version:**
```markdown
## 🔍 发现的问题

### 🔴 严重 ({count})

**问题 C1: {标题}**
- **位置:** {file}:{section or line range}
- **问题:** {具体问题描述}
- **影响:** {为什么重要}
- **修复:** {具体可执行的建议}

### 🟡 警告 ({count})

**问题 W1: {标题}**
- **位置:** {file}:{section}
- **问题:** {具体问题描述}
- **影响:** {为什么重要}
- **修复:** {具体可执行的建议}

### 🟢 建议 ({count})

**问题 S1: {标题}**
- **位置:** {file}:{section}
- **建议:** {改进思路}
```

**English version:**
```markdown
## 🔍 Issues Found

### 🔴 Critical ({count})

**Issue C1: {title}**
- **Location:** {file}:{section or line range}
- **Problem:** {what's wrong}
- **Impact:** {why it matters}
- **Fix:** {specific actionable suggestion}

### 🟡 Warning ({count})

**Issue W1: {title}**
- **Location:** {file}:{section}
- **Problem:** {what's wrong}
- **Impact:** {why it matters}
- **Fix:** {specific actionable suggestion}

### 🟢 Suggestion ({count})

**Issue S1: {title}**
- **Location:** {file}:{section}
- **Suggestion:** {improvement idea}
```

### Section 5: Top 3 Quick Wins

The 3 highest-impact fixes. Each must include a before/after example.

**Chinese version:**
```markdown
## 🚀 Top 3 快速优化

### 优化 1: {标题}
**收益:** {哪方面提升} | **工作量:** {低/中/高}

修改前:
\`\`\`markdown
{当前内容}
\`\`\`

修改后:
\`\`\`markdown
{优化后内容}
\`\`\`

**原因:** {为什么这样改更好}
```

**English version:**
```markdown
## 🚀 Top 3 Quick Wins

### Quick Win 1: {title}
**Impact:** {what improves} | **Effort:** {low/medium/high}

Before:
\`\`\`markdown
{current content}
\`\`\`

After:
\`\`\`markdown
{improved content}
\`\`\`

**Why:** {explanation of the improvement}
```

### Section 6: Optimization Roadmap

Prioritized improvement plan in phases.

**Chinese version:**
```markdown
## 📋 优化路线图

### 阶段 1: 紧急修复（立即处理）
- [ ] {修复_1}
- [ ] {修复_2}

### 阶段 2: 质量提升（下次迭代）
- [ ] {改进_1}
- [ ] {改进_2}

### 阶段 3: 打磨细节（有空再做）
- [ ] {打磨_1}
- [ ] {打磨_2}
```

**English version:**
```markdown
## 📋 Optimization Roadmap

### Phase 1: Critical Fixes (do immediately)
- [ ] {fix_1}
- [ ] {fix_2}

### Phase 2: Quality Improvements (next iteration)
- [ ] {improvement_1}
- [ ] {improvement_2}

### Phase 3: Polish (when time permits)
- [ ] {polish_1}
- [ ] {polish_2}
```

### Section 7: Follow-Up Prompt

**Chinese version:**
```markdown
---

💡 **下一步:**
- 输入 `fix` → 自动修复 Critical 和 Warning 级别问题，生成优化后的 SKILL.md
- 输入 `deep [维度编号]` → 对某个维度做深度分析
- 输入 `rewrite` → 生成该 skill 的完整优化版本
```

**English version:**
```markdown
---

💡 **Next Steps:**
- Type `fix` → Auto-fix critical and warning issues, generate an improved SKILL.md
- Type `deep [dimension_number]` → Deep dive into a specific dimension
- Type `rewrite` → Generate a fully optimized version of this skill
```

---

## Formatting Rules

1. **Bilingual structure is mandatory** — complete Chinese report first, `---` separator, then complete English report. Never interleave languages within a section. Code snippets in before/after examples stay in their original language (usually English) in both versions.
2. Use emoji sparingly — only for section headers and severity indicators
3. Keep the report scannable — busy PMs should understand the score in 10 seconds
4. Code blocks use markdown syntax highlighting
5. Before/after examples must be real content from the evaluated skill, not generic
6. If the skill is short (<50 lines), keep the report proportionally short — don't pad
7. The overall tone should be that of a **constructive senior code reviewer**: honest, specific, and helpful
8. Both language versions must contain **identical** scores, issue counts, and severity levels — no discrepancies allowed


path: README.md
content: # skill-scorer

对任何 SKILL.md 进行质量评估和打分，生成中英双语结构化质检报告和优化建议。

## 概述

skill-scorer 是一个 meta-skill（元技能），用于审计其他 skill 的质量。给定一个 SKILL.md 文件或完整的 skill 文件夹，它会从 8 个维度进行系统评估，给出加权总分（满分100），按严重程度标注问题（严重/警告/建议），并生成可执行的优化路线图。报告始终以中英双语输出——中文在前，英文在后，不穿插。

评分标准融合了 Anthropic 官方 Skill 编写最佳实践、Skill Engineering Standard (v1.4.3) 和社区生产环境验证的模式。

## 版本历史

| 版本 | 变更 |
|------|------|
| 1.6.0 | D4 编排型评分标准措辞精准化：明确 Playbooks 应包含描述性编排逻辑（而非可执行命令），Usage Examples 才是可执行命令的位置，output merging 可以定义在 templates.md 中。README 重构为中文在前的双语结构 |
| 1.5.0 | Dimension 4 扩展为 5 种 skill 类型：新增 Script-bundled（脚本驱动型）和 MCP-integrated（MCP 集成型），各有独立评分标准 |
| 1.4.0 | Dimension 4（工作流逻辑）新增 Skill 类型识别：指令型 / 单命令型 / 编排型三类 skill 使用差异化评分标准 |
| 1.3.0 | Description 改为中英双语（中文在前），确保内部平台展示中文 |
| 1.2.0 | Step 0 增加输入验证和降级路径——对非 skill 文件（乱码、Python 代码等）直接拒绝评分而非强行打分 |
| 1.1.0 | 报告输出改为中英双语（中文在前，英文在后，不穿插）|
| 1.0.0 | 首次发布，8 维度评分体系 |

## 快速开始

### 安装

```bash
# 安装到全局 skills 目录
cp -r skill-scorer/ ~/.claude/skills/skill-scorer/

# 或安装到项目级别
cp -r skill-scorer/ .claude/skills/skill-scorer/
```

### 使用方式

```
# 在 Claude Code 中
> 帮我评分这个 skill: .claude/skills/my-skill/SKILL.md

# 在 Claude.ai / Cowork 中
> [上传 SKILL.md 文件] 帮我质检这个 skill
```

## 评估维度

| # | 维度 | 权重 |
|---|------|------|
| 1 | 元数据与触发 | 15% |
| 2 | 结构与架构 | 15% |
| 3 | 指令清晰度 | 15% |
| 4 | 工作流与逻辑 | 15% |
| 5 | 错误处理 | 10% |
| 6 | 上下文效率 | 10% |
| 7 | 可移植性与兼容性 | 10% |
| 8 | 安全性与鲁棒性 | 10% |

输出报告包含：评分卡、亮点、按严重程度分类的问题清单、Top 3 快速优化（含修改前/后示例）、优化路线图。

## 支持的 Skill 类型

Dimension 4（工作流逻辑）会先识别 skill 类型，再使用对应的评分标准：

| 类型 | 说明 |
|------|------|
| 指令型 | 纯 markdown 指令，无 CLI/脚本/外部工具 |
| 单命令型 | 包装一个 CLI/API 命令 |
| 编排型 | 多命令编排，Parameters 定义命令池，Playbooks 定义编排逻辑 |
| 脚本驱动型 | SKILL.md + scripts/ 目录，脚本处理确定性计算 |
| MCP 集成型 | 依赖外部 MCP server，skill 是 MCP 工具之上的知识层 |

## 文件结构

```
skill-scorer/
├── README.md               # 本文件
├── SKILL.md                # 核心评估逻辑
└── references/
    ├── rubric.md           # 8 维度详细评分标准
    ├── report-template.md  # 报告输出格式模板
    └── anti-patterns.md    # 25+ 常见 skill 反模式检测清单
```

## 兼容性

支持：Claude Code、Claude.ai、Cowork 及所有兼容 SKILL.md 的 Agent。

## 许可证

MIT

---

# skill-scorer (English)

Evaluate and score any SKILL.md against industry best practices, with a bilingual (Chinese + English) quality report and actionable optimization suggestions.

## Overview

skill-scorer is a meta-skill that audits other skills. Given a SKILL.md file or a complete skill folder, it performs a systematic evaluation across 8 dimensions, assigns a weighted score out of 100, identifies issues by severity (Critical / Warning / Suggestion), and generates an actionable improvement roadmap. Reports are always output in both Chinese and English — Chinese first, English after, clearly separated.

The scoring rubric synthesizes criteria from Anthropic's official skill authoring best practices, the Skill Engineering Standard (v1.4.3), and community-tested patterns from production skill ecosystems.

## Changelog

| Version | Changes |
|---------|---------|
| 1.6.0 | D4 orchestration criteria wording refined: clarified that Playbooks contain descriptive logic (not executable commands), Usage Examples contain executable commands, output merging can live in templates.md. README restructured to Chinese-first bilingual |
| 1.5.0 | Dimension 4 expanded to 5 skill types: added Script-bundled and MCP-integrated with type-specific scoring criteria |
| 1.4.0 | Dimension 4 (Workflow & Logic) adds Skill Type Detection: instruction-only / single-command / orchestration evaluated with type-specific criteria |
| 1.3.0 | Description bilingual: Chinese first, English after, for internal platform display |
| 1.2.0 | Added input validation and graceful degradation in Step 0 — rejects non-skill files (binary, garbled, unrelated code) instead of force-scoring |
| 1.1.0 | Bilingual report output (Chinese first, English after, no interleaving) |
| 1.0.0 | Initial release with 8-dimension scoring rubric |

## Quick Start

### Install

```bash
# Copy into your skills directory
cp -r skill-scorer/ ~/.claude/skills/skill-scorer/

# Or for project-level installation
cp -r skill-scorer/ .claude/skills/skill-scorer/
```

### Usage

```
# In Claude Code
> score this skill: .claude/skills/my-skill/SKILL.md

# In Claude.ai / Cowork
> [upload a SKILL.md file] 帮我质检这个 skill
```

## Evaluation Dimensions

| # | Dimension | Weight |
|---|-----------|--------|
| 1 | Metadata & Triggering | 15% |
| 2 | Structure & Architecture | 15% |
| 3 | Instruction Clarity | 15% |
| 4 | Workflow & Logic | 15% |
| 5 | Error Handling | 10% |
| 6 | Context Efficiency | 10% |
| 7 | Portability & Compatibility | 10% |
| 8 | Safety & Robustness | 10% |

Outputs a report with: score card, strengths, issue list with severity, top 3 quick wins with before/after examples, and an optimization roadmap.

## Supported Skill Types

Dimension 4 (Workflow & Logic) first identifies the skill type, then applies type-specific scoring criteria:

| Type | Description |
|------|-------------|
| Instruction-only | Pure markdown instructions, no CLI/scripts/external tools |
| Single-command executor | Wraps one CLI/API command |
| Multi-command orchestration | Multiple commands combined; Parameters define command pool, Playbooks define orchestration logic |
| Script-bundled | SKILL.md + scripts/ directory; scripts handle deterministic computation |
| MCP-integrated | Depends on external MCP server; skill is the knowledge layer on top of MCP tools |

## File Structure

```
skill-scorer/
├── README.md               # This file
├── SKILL.md                # Core evaluation logic
└── references/
    ├── rubric.md           # Detailed scoring criteria for all 8 dimensions
    ├── report-template.md  # Output format and report structure
    └── anti-patterns.md    # 25+ common skill mistakes and detection methods
```

## Compatibility

Works with: Claude Code, Claude.ai, Cowork, and all SKILL.md-compatible agents.

## License

MIT


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)