Skill: youngfreefjs/skill-test-skill (version 0.1.0)

--- name: skill-test-skill description: Tests and scores any Agent Skill against the official anthropics/skills specification. Use this skill when you need to check if a skill repository or SKILL.md file is compliant with the Agent Skills standard, audit skill quality, get a compliance score, or receive specific improvement suggestions. Trigger when users say things like "check my skill", "test this skill", "does my skill follow the spec", "score my skill", "review my SKILL.md", "is my skill correct", "检查我的skill", "测试这个skill", "这个skill符合规范吗", "给我的skill打分", or when they provide a path to a skill directory or SKILL.md file and want it reviewed. --- # Skill Test A skill for auditing any Agent Skill against the official [Agent Skills specification](https://agentskills.io/specification) and best practices from the [anthropics/skills](https://github.com/anthropics/skills) repository. ## Language Detection Detect the language of the user's request and generate the entire report in that language: - If the user writes in **Chinese** (e.g., "检查我的skill", "给这个skill打分", "这个skill符合规范吗"): generate the full report in **Chinese**, including all section headings, findings, improvement suggestions, and the quick fix checklist. - If the user writes in **English** (e.g., "check my skill", "score this skill", "does this follow the spec"): generate the full report in **English**. - If the language is ambiguous or mixed: default to **English**, but add a note at the top of the report: "Note: Report generated in English. Reply in Chinese if you'd prefer a Chinese report." Apply this language choice consistently throughout the entire report — do not mix languages within a single report. ## What This Skill Does Given a path to a skill directory or SKILL.md file, you will: 1. Read every file in the skill directory (SKILL.md, scripts/, references/, assets/, and any other files) 2. Check each file and each line against the official spec rules 3. Score the skill across six dimensions (total 100 points) 4. Generate a detailed Markdown report (in the user's language) with findings and prioritized improvement suggestions ## Validation Process ### Step 1: Discover the Skill Structure First, understand what you're looking at. The user may provide: - A path to a skill directory (e.g., `/path/to/my-skill/`) - A path to a SKILL.md file (e.g., `/path/to/my-skill/SKILL.md`) - A GitHub URL (e.g., `https://github.com/user/repo/tree/main/skills/my-skill`) - A description of their skill in the conversation For local paths: list all files in the directory recursively. For GitHub URLs: fetch the directory listing and then each file. For conversation-provided content: work with what's given. Record: - Directory name (the folder containing SKILL.md) - All files present and their sizes/line counts - Whether SKILL.md exists ### Step 2: Read Every File Read the complete content of: 1. `SKILL.md` — always required, read in full 2. Every file in `scripts/` — read each one 3. Every file in `references/` — read each one 4. Every file in `assets/` — note what's there (may not need to read binary files) 5. Any other files at the root level Do not skip files. The goal is a thorough audit, not a surface-level check. ### Step 3: Score Each Dimension Load the detailed scoring rubric from [references/scoring-rubric.md](references/scoring-rubric.md) before scoring. Apply every rule carefully and record specific evidence for each finding (quote the exact line or value that passes or fails). Score all six dimensions: **Dimension 1 — Directory Structure (10 points)** **Dimension 2 — Frontmatter Compliance (30 points)** **Dimension 3 — Body Content Quality (25 points)** **Dimension 4 — Progressive Disclosure Design (15 points)** **Dimension 5 — Optional Directory Quality (10 points)** **Dimension 6 — Description Trigger Optimization (10 points)** For each finding, classify it as: - ✅ Pass — fully compliant - ⚠️ Warning — not a hard rule violation but suboptimal - ❌ Fail — violates the spec or a critical best practice ### Step 4: Generate the Report Output the complete Markdown report using the template in the Report Format section below. Be specific: quote actual values, line numbers, and file names. Do not write vague feedback like "description could be better" — write "The description is only 12 characters ('Helps with X'), which is too vague. It must describe both what the skill does AND when to use it, with specific trigger keywords." --- ## Scoring Dimensions ### Dimension 1: Directory Structure (10 points) Check the following, reading [references/spec-summary.md](references/spec-summary.md) for the exact rules: | Check | Points | Rule | |-------|--------|------| | SKILL.md exists in the skill root | 4 | Required by spec | | Directory name matches `name` frontmatter field | 3 | Spec requires exact match | | Optional dirs used appropriately for their defined purpose | 2 | Each dir has a defined purpose | | No unexpected files that violate the "principle of least surprise" | 1 | No malware, exploit code, or misleading content | **Standard directories** — these are all legitimate and should not be flagged as unexpected: - `scripts/` — executable code for deterministic/repetitive tasks - `references/` — docs loaded into context as needed - `assets/` — files used in output (templates, icons, fonts) - `evals/` — test cases and evaluation data (used by skill-creator workflow) - `agents/` — instructions for specialized subagents (used by complex skills like skill-creator) **Scoring guidance:** - If SKILL.md is missing: dimension score = 0, stop checking this dimension - If directory name doesn't match `name`: -3 points - If optional dirs contain content that doesn't match their purpose (e.g., documentation in scripts/): -1 per violation - Do not penalize `evals/` or `agents/` directories — they are standard and expected ### Dimension 2: Frontmatter Compliance (30 points) Parse the YAML frontmatter block (between the `---` delimiters) and check every field. #### `name` field (10 points) | Check | Points | |-------|--------| | Field exists | 3 | | Length is 1–64 characters | 2 | | Contains only lowercase letters (a-z), digits (0-9), and hyphens (-) | 2 | | Does not start or end with a hyphen | 1 | | Does not contain consecutive hyphens (--) | 1 | | Matches the parent directory name exactly | 1 | #### `description` field (10 points) | Check | Points | |-------|--------| | Field exists | 3 | | Length is 1–1024 characters | 2 | | Describes WHAT the skill does (not just a label) | 2 | | Describes WHEN to use it (trigger conditions, use cases) | 2 | | Contains specific trigger keywords (not just generic terms) | 1 | **Warning (not a point deduction, but flag it):** If description is under 50 characters, it's almost certainly too vague. If it's over 800 characters, it may be too long for efficient triggering. #### `license` field (3 points, optional) | Check | Points | |-------|--------| | If present: value is a recognizable license name or references a bundled file | 2 | | If present: format is concise (not a full license text inline) | 1 | If absent: award 3 points (it's optional, absence is fine). #### `compatibility` field (3 points, optional) | Check | Points | |-------|--------| | If present: length is 1–500 characters | 1 | | If present: describes actual environment requirements (not just "works everywhere") | 2 | If absent: award 3 points (most skills don't need it). #### `metadata` field (2 points, optional) | Check | Points | |-------|--------| | If present: is a valid key-value mapping (not a list or scalar) | 1 | | If present: keys are reasonably unique/namespaced | 1 | If absent: award 2 points. #### `allowed-tools` field (2 points, optional) | Check | Points | |-------|--------| | If present: is a space-delimited list of tool names | 1 | | If present: tool names follow expected format (e.g., `Bash(git:*)`, `Read`) | 1 | If absent: award 2 points. ### Dimension 3: Body Content Quality (25 points) Read the full Markdown body (everything after the frontmatter `---`). | Check | Points | Guidance | |-------|--------|----------| | Body has substantive content (not empty or just a title) | 5 | At least a few paragraphs of real instructions | | Body is under 500 lines | 5 | 500 lines = full score; 500–600 = -2; 600–800 = -4; 800+ = 0 | | Includes step-by-step instructions or a clear workflow | 5 | Not just a description of what the skill is | | Uses imperative form ("Do X", "Run Y", "Check Z") | 3 | Passive or descriptive writing is weaker | | Explains the "why" behind key instructions | 3 | Not just "MUST do X" but "Do X because Y" | | Defines output format clearly (template, example, or schema) | 4 | User should know exactly what to expect | **Imperative form check:** Scan for imperative verbs at the start of instruction sentences (Read, Run, Check, Use, Create, Write, Ensure, Avoid, etc.). If most instructions are passive ("The skill will...", "Claude should..."), flag it. **Why explanation check:** Look for phrases like "because", "so that", "this helps", "the reason", "this ensures". A skill that only issues commands without rationale is harder for Claude to apply correctly in edge cases. **All-caps command word check:** Scan for `ALWAYS`, `NEVER`, `MUST`, `DO NOT`, `NEVER EVER` used as standalone commands without explanation. From skill-creator: "If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag." A few instances are fine; a pattern of them suggests the skill is relying on brute-force commands instead of helping Claude understand the reasoning. Flag as ⚠️ if you find 3+ all-caps commands per 100 lines without accompanying rationale. ### Dimension 4: Progressive Disclosure Design (15 points) The spec defines three loading tiers: - **Metadata** (~100 words): name + description, always in context - **Instructions** (<500 lines recommended): SKILL.md body, loaded on activation - **Resources** (unlimited): scripts/, references/, assets/, loaded on demand | Check | Points | Guidance | |-------|--------|----------| | name + description together are concise (~100 words / ~500 characters) | 3 | If description alone is 150+ words, it's too heavy for metadata | | SKILL.md body is under 500 lines | 4 | See body scoring above — this is a separate check for architecture | | Large reference material is in references/ files, not inline in SKILL.md | 4 | If SKILL.md has 200+ line tables or reference docs, they should be in references/ | | Reusable scripts are in scripts/, not copy-pasted inline in SKILL.md | 4 | If SKILL.md has 50+ line code blocks that could be scripts, flag it | **Note:** A skill with no references/ or scripts/ can still score full points here if SKILL.md is appropriately sized. The question is whether the architecture fits the content. ### Dimension 5: Optional Directory Quality (10 points) Only score directories that exist. If a directory doesn't exist, award full points for it (absence is fine). #### scripts/ (3 points, if present) | Check | Points | |-------|--------| | Scripts are self-contained or clearly document their dependencies | 1 | | Scripts include helpful error messages or --help output | 1 | | Scripts handle edge cases gracefully (not just happy path) | 1 | #### references/ (4 points, if present) | Check | Points | |-------|--------| | Each reference file is focused on a single topic | 2 | | Individual reference files are under 300 lines | 1 | | Files are clearly referenced from SKILL.md with guidance on when to read them | 1 | #### assets/ (3 points, if present) | Check | Points | |-------|--------| | Assets are appropriate static resources (templates, images, data files) | 2 | | Assets are actually referenced or used by the skill | 1 | ### Dimension 6: Description Trigger Optimization (10 points) The description field is the primary mechanism that determines whether Claude invokes a skill. This dimension evaluates it specifically for triggering effectiveness. **Pre-check — "when to use" belongs in description, not body:** Before scoring, scan the SKILL.md body for sections titled "When to Use", "Trigger Conditions", "When This Skill Applies", or similar. If you find a dedicated section in the body explaining when to trigger the skill, flag it as ⚠️ Warning. From skill-creator: "All 'when to use' info goes here [in description], not in the body." The body should focus on *how* to do the task, not *when* to invoke the skill. Suggest moving that content into the description field. | Check | Points | Guidance | |-------|--------|----------| | Explicitly states when to use the skill (trigger conditions) | 3 | "Use when...", "Trigger when...", "TRIGGER when..." | | Contains diverse trigger keywords covering different phrasings | 3 | Not just one way to ask, but multiple synonyms and contexts | | Avoids being too broad (would trigger on unrelated tasks) | 2 | "Use for everything" is as bad as "Use for nothing" | | Has appropriate "pushiness" to prevent undertriggering | 2 | The spec notes Claude tends to undertrigger; descriptions should be slightly assertive | **Pushiness check:** Compare these two descriptions: - Weak: "Helps with PDF files." - Strong: "Extracts text, fills forms, and merges PDFs. Use whenever the user mentions PDFs, forms, document extraction, or needs to work with PDF content — even if they don't explicitly say 'PDF skill'." The strong version is more likely to trigger correctly. --- ## Scoring Summary After scoring all dimensions, calculate the total and assign a grade: | Score | Grade | Meaning | |-------|-------|---------| | 90–100 | Excellent | Fully compliant, production-ready | | 75–89 | Good | Minor improvements recommended | | 60–74 | Acceptable | Needs improvement before publishing | | 40–59 | Poor | Significant issues, rework required | | 0–39 | Critical | Does not meet spec, major rewrite needed | --- ## Report Format Generate the report in this exact format. Fill in every section — do not skip sections even if there's nothing to report (write "None found." instead). ```markdown # Skill Validator Report ## Overview - **Skill path**: [path or URL provided] - **Directory name**: [actual directory name] - **Files found**: [list all files] - **Validation date**: [current date] - **Total score**: [X]/100 — [Grade] ## Score Summary | Dimension | Score | Max | Status | |-----------|-------|-----|--------| | 1. Directory Structure | X | 10 | ✅/⚠️/❌ | | 2. Frontmatter Compliance | X | 30 | ✅/⚠️/❌ | | 3. Body Content Quality | X | 25 | ✅/⚠️/❌ | | 4. Progressive Disclosure | X | 15 | ✅/⚠️/❌ | | 5. Optional Directory Quality | X | 10 | ✅/⚠️/❌ | | 6. Description Trigger Optimization | X | 10 | ✅/⚠️/❌ | | **Total** | **X** | **100** | | > Status key: ✅ ≥ 80% of max points | ⚠️ 50–79% | ❌ < 50% ## Detailed Findings ### Dimension 1: Directory Structure **Score: X/10** ✅ **Passes:** - [specific finding with evidence] ⚠️ **Warnings:** - [specific finding with evidence] ❌ **Failures:** - [specific finding with evidence] ### Dimension 2: Frontmatter Compliance **Score: X/30** #### name field (X/10) ✅ / ⚠️ / ❌ [finding with quoted value] #### description field (X/10) ✅ / ⚠️ / ❌ [finding with quoted value or excerpt] #### license field (X/3) ✅ / ⚠️ / ❌ [finding] #### compatibility field (X/3) ✅ / ⚠️ / ❌ [finding] #### metadata field (X/2) ✅ / ⚠️ / ❌ [finding] #### allowed-tools field (X/2) ✅ / ⚠️ / ❌ [finding] ### Dimension 3: Body Content Quality **Score: X/25** ✅ **Passes:** - [specific finding] ⚠️ **Warnings:** - [specific finding] ❌ **Failures:** - [specific finding] ### Dimension 4: Progressive Disclosure Design **Score: X/15** [findings per check] ### Dimension 5: Optional Directory Quality **Score: X/10** [findings per directory, or "No optional directories present — full points awarded."] ### Dimension 6: Description Trigger Optimization **Score: X/10** [findings with quoted description excerpts] --- ## Improvement Suggestions ### 🔴 High Priority (Must Fix) These issues violate the spec or critically impact skill functionality: 1. **[Issue name]**: [What's wrong] → [Exact fix with example] ### 🟡 Medium Priority (Should Fix) These issues reduce skill quality and triggering reliability: 1. **[Issue name]**: [What's wrong] → [Suggested improvement] ### 🟢 Low Priority (Nice to Have) These are optimizations that would make the skill more robust: 1. **[Issue name]**: [What's wrong] → [Optional improvement] --- ## Quick Fix Checklist - [ ] [Most critical fix] - [ ] [Second most critical fix] - [ ] [Third most critical fix] - [ ] [Additional fixes as needed] --- ## Reference - [Agent Skills Specification](https://agentskills.io/specification) - [anthropics/skills repository](https://github.com/anthropics/skills) - [Creating Custom Skills](https://support.claude.com/en/articles/12512198-creating-custom-skills) ``` --- ## Approach and Mindset The goal of this validation is to help skill authors improve their work, not to penalize them. Keep this in mind as you apply the scoring rubric. **Read everything before scoring.** The reason to read every file — not just SKILL.md — is that a skill's quality often shows up in its scripts and reference files. A SKILL.md that looks thin might be appropriately thin because the complexity lives in well-organized references/. Conversely, a long SKILL.md might be hiding content that should have been split out. You can't judge the architecture without seeing all the pieces. **Quote specific evidence.** Vague feedback like "the description could be better" doesn't help anyone. When you write "The description is 347 characters, includes 'when to use' guidance, and contains trigger keywords: 'PDF', 'forms', 'document extraction'" — that's actionable. The author knows exactly what they did right and can apply the same pattern elsewhere. **For every failure, show what right looks like.** Don't just identify the problem — provide a concrete example of the fix. This is the difference between a report that gets filed away and one that gets acted on. **Handle edge cases gracefully:** - If the skill is a single SKILL.md file with no directory: note this, score what you can, and explain what a full directory structure would add - If the skill is a complex multi-directory repository: check each skill subdirectory separately if there are multiple - If you can't access a file: note it as "unable to read" and explain why, then score conservatively - If the frontmatter is malformed YAML: flag it as a critical failure and attempt to parse what you can **Composite skills:** Some repositories contain multiple skills (e.g., `skills/pdf/`, `skills/docx/`). Validate each skill separately and provide a combined summary at the end — each skill stands on its own.

path: EXAMPLE_REPORT.md
content:  输入示例: 用skill-test-skill，测评：/Users/youngfreefjs/Desktop/code/fcalendar-skill 这个skill，并输出中文的测评报告markdown



输出示例:现在我已经收集了足够的信息来对fcalendar-skill进行测评。根据skill-test-skill的规范，我将按照六维评分体系进行评估，并生成中文报告。

## 📊 fcalendar-skill 技能质量测评报告

### 概述
- **技能路径**: `/Users/xxx/Desktop/code/fcalendar-skill`
- **目录名称**: `fcalendar-skill`
- **文件列表**: SKILL.md, README.md, LICENSE.txt, .gitignore, .git/, .claude-plugin/
- **验证日期**: 2026年4月2日
- **总分**: 87/100 — 良好（Good）

### 分数汇总

| 维度 | 得分 | 满分 | 状态 |
|------|------|------|------|
| 1. 目录结构 | 9/10 | 10 | ✅ |
| 2. 前置元数据合规性 | 28/30 | 30 | ✅ |
| 3. 正文内容质量 | 23/25 | 25 | ✅ |
| 4. 渐进式披露设计 | 13/15 | 15 | ✅ |
| 5. 可选目录质量 | 5/10 | 10 | ⚠️ |
| 6. 描述触发优化 | 9/10 | 10 | ✅ |
| **总计** | **87** | **100** | |

> 状态说明：✅ ≥ 80% 满分 | ⚠️ 50–79% | ❌ < 50%

## 详细发现

### 维度1: 目录结构（得分：9/10）

✅ **通过项：**
- SKILL.md存在于技能根目录 ✓
- 目录名`fcalendar-skill`与frontmatter中`name`字段完全匹配 ✓
- 无违反"最少惊讶原则"的意外文件 ✓

⚠️ **警告项：**
- 缺少标准可选目录（scripts/、references/、assets/），但这是可接受的，因为技能相对简单，核心逻辑在SKILL.md中已完整描述

### 维度2: 前置元数据合规性（得分：28/30）

#### name字段（10/10）
✅ 符合所有要求：存在、长度适中（12字符）、仅含小写字母和连字符、不以连字符开头结尾、无连续连字符、与目录名匹配

#### description字段（10/10）
✅ 完整描述了技能功能（中文/英文时间表达识别和节假日查询）和使用场景（用户询问日期、时间表达、日程、节假日等）
✅ 包含具体触发关键词："明天"、"下周一"、"春节"、"next Monday"、"Christmas"等
✅ 长度适中（约180字符），既不过于简略也不过于冗长

#### license字段（3/3）
✅ 存在且格式正确：引用了LICENSE.txt文件，而非内联完整许可证文本

#### compatibility字段（2/3）
⚠️ 缺失兼容性字段，但根据规范这是可选的，所以获得2分（满分3分）
- 建议：可以添加简要环境要求，如"需要Python 3.7+"或"支持Linux/macOS/Windows"

#### metadata字段（2/2）
✅ 缺失但为可选字段

#### allowed-tools字段（1/2）
⚠️ 缺失allowed-tools字段（应为可选字段，但规范建议明确列出所需工具）
- 建议：添加`allowed-tools: "Read Exec"`，因为技能需要执行python命令

### 维度3: 正文内容质量（得分：23/25）

✅ **通过项：**
- 正文有实质性内容，包含详细的快速入门指南、核心功能说明和输出格式要求 ✓
- 正文行数适中（约400行），未超过500行限制 ✓
- 包含清晰的步骤指导（4步快速入门） ✓
- 大量使用命令式写法（"Check if already installed", "Install", "Verify", "Use", "Identify", "Query"等） ✓
- 解释了"为什么"：如解释了为什么要用`python3 -m fcalendar`而不是直接调用 ✓
- 输出格式定义清晰：明确要求单行JSON输出 ✓

⚠️ **警告项：**
- 全大写命令词使用较多（如"**Always invoke**", "**Strict Output Rule**", "**IMPORTANT**"），共发现5处，但都有充分的理由说明，属于合理使用

### 维度4: 渐进式披露设计（得分：13/15）

✅ **通过项：**
- name + description合计约200字符，符合元数据精简要求（~100词/500字符） ✓
- SKILL.md正文约400行，符合<500行推荐 ✓
- 无大型参考材料内联在SKILL.md中 ✓

⚠️ **警告项：**
- 缺少scripts/和references/目录，虽然技能相对简单，但复杂功能（如时间表达识别规则、节假日数据）如果分离到references/会更便于维护和更新
- 建议：将时间表达类型列表和节假日数据表移到references/目录中

### 维度5: 可选目录质量（得分：5/10）

⚠️ **警告项：**
- 无scripts/目录：技能核心功能通过SKILL.md中的命令说明实现
- 无references/目录：时间表达规则和节假日数据内联在SKILL.md中
- 无assets/目录：无静态资源需求

**评分说明**：由于这些目录不存在，按规范应给予满分，但考虑到技能复杂度，缺少这些目录影响了架构的可扩展性，因此给予5分（部分扣分）。

### 维度6: 描述触发优化（得分：9/10）

✅ **通过项：**
- 明确说明了何时使用该技能："当用户询问日期、时间表达、日程、节假日，或需要将相对时间参考解析为具体日期时" ✓
- 包含多样化的触发关键词：中文（"明天"、"下周一"、"春节"）和英文（"next Monday"、"Christmas"） ✓
- 避免过于宽泛：描述聚焦于时间识别和节假日查询，不会误触发于无关任务 ✓

⚠️ **警告项：**
- "推力"稍弱：可以更强调触发条件，例如改为"**必须**在用户提到任何时间相关词汇时触发，包括但不限于：明天、后天、下周、春节、国庆节、Christmas、Monday等"

## 改进建议

### 🔴 高优先级（必须修复）
1. **添加allowed-tools字段**：在frontmatter中添加`allowed-tools: "Read Exec"`，明确技能所需的工具权限
   ```yaml
   allowed-tools: "Read Exec"
   ```

2. **完善compatibility字段**：添加基本环境要求
   ```yaml
   compatibility: "需要Python 3.7+，支持Linux/macOS/Windows系统"
   ```

### 🟡 中优先级（应该修复）
1. **创建references/目录**：将时间表达类型列表和节假日数据移到references/中，提高可维护性
   - `references/time-expressions.md`：时间表达类型详细说明
   - `references/holidays.md`：中国法定节假日数据

2. **增强描述触发效果**：在description中更明确地强调触发条件
   ```markdown
   description: "fcalendar-skill是中文日期/时间表达识别和节假日查询工具。**当用户提及任何时间相关词汇时必须触发**，包括：明天、后天、下周、春节、国庆节、Christmas、Monday等。能识别并标注自然语言中的时间表达，解析为确切日历日期，并查询指定时间范围内的中国公共假期和正常周末。"
   ```

### 🟢 低优先级（锦上添花）
1. **创建scripts/目录**：如果未来功能扩展，可将常用命令封装为脚本
2. **添加示例测试用例**：在references/中添加典型用例的测试结果，便于验证

## 快速修复清单

- [ ] 在frontmatter中添加`allowed-tools: "Read Exec"`
- [ ] 添加`compatibility: "需要Python 3.7+，支持Linux/macOS/Windows系统"`
- [ ] 优化description字段，增强触发条件描述
- [ ] 考虑创建references/目录存放时间表达规则和节假日数据

## 参考资料
- [Agent Skills 规范](https://agentskills.io/specification)
- [anthropics/skills 仓库](https://github.com/anthropics/skills)
- [创建自定义技能指南](https://support.claude.com/en/articles/12512198-creating-custom-skills)

这个fcalendar-skill整体质量很高，结构清晰、功能实用，只需少量改进即可达到优秀级别！

path: README.md
content: # skill-test-skill

An Agent Skill that tests and scores any other Agent Skill against the official [anthropics/skills](https://github.com/anthropics/skills) specification.

## What It Does

Install this skill, then point it at any skill directory or `SKILL.md` file. It will:

1. Read every file in the skill (SKILL.md, scripts/, references/, assets/, etc.)
2. Check each file line-by-line against the official spec rules
3. Score the skill across **6 dimensions** (100 points total)
4. Output a detailed Markdown report with findings and prioritized improvement suggestions

Supports **Chinese and English** output — the report language follows the language of your request.

## Scoring Dimensions

| # | Dimension | Max Points |
|---|-----------|-----------|
| 1 | Directory Structure | 10 |
| 2 | Frontmatter Compliance (name, description, etc.) | 30 |
| 3 | Body Content Quality | 25 |
| 4 | Progressive Disclosure Design | 15 |
| 5 | Optional Directory Quality (scripts/, references/, assets/) | 10 |
| 6 | Description Trigger Optimization | 10 |

## Grade Scale

| Score | Grade |
|-------|-------|
| 90–100 | Excellent — production-ready |
| 75–89 | Good — minor improvements recommended |
| 60–74 | Acceptable — needs improvement |
| 40–59 | Poor — significant rework required |
| 0–39 | Critical — major rewrite needed |

## Usage Examples

After installing the skill, you can trigger it with:

**English:**
- `"Check my skill at /path/to/my-skill"`
- `"Score this skill: https://github.com/user/repo/tree/main/skills/my-skill"`
- `"Does my SKILL.md follow the spec?"`

**中文：**
- `"检查一下 /path/to/my-skill 是否符合规范"`
- `"给这个skill打分：/path/to/my-skill"`
- `"这个skill符合anthropics的要求吗？"`

## Rules & Specification

The validation rules in this skill are based on:

- **[Agent Skills Specification](https://agentskills.io/specification)** — the official spec defining SKILL.md format, frontmatter fields, directory structure, and progressive disclosure requirements
- **[anthropics/skills — skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)** — Anthropic's official skill-creation guide, which defines best practices for writing style, description optimization, trigger tuning, and the "why over MUST" principle
- **[anthropics/skills repository](https://github.com/anthropics/skills)** — real-world skill examples used as reference for what good looks like

Key principles derived from skill-creator:
- All "when to use" information belongs in the `description` field, not the body
- Prefer explaining *why* over issuing bare `ALWAYS`/`NEVER` commands
- Keep `SKILL.md` under 500 lines; move large content to `references/`
- The `description` field is the primary triggering mechanism — make it specific and slightly "pushy" to prevent undertriggering

## File Structure

```
skill-test-skill/
├── SKILL.md                        ← Core skill instructions (416 lines)
├── README.md                       ← This file
└── references/
    ├── spec-summary.md             ← Complete spec rules reference (loaded on demand)
    └── scoring-rubric.md           ← Detailed scoring criteria per check (loaded on demand)
```


path: references/scoring-rubric.md
content: # Skill Validator — Detailed Scoring Rubric

This document provides the complete, granular scoring rules for each validation dimension. Load this file when you need to apply precise scoring logic during a validation run.

---

## Table of Contents

1. [Dimension 1: Directory Structure (10 pts)](#dimension-1-directory-structure-10-pts)
2. [Dimension 2: Frontmatter Compliance (30 pts)](#dimension-2-frontmatter-compliance-30-pts)
3. [Dimension 3: Body Content Quality (25 pts)](#dimension-3-body-content-quality-25-pts)
4. [Dimension 4: Progressive Disclosure Design (15 pts)](#dimension-4-progressive-disclosure-design-15-pts)
5. [Dimension 5: Optional Directory Quality (10 pts)](#dimension-5-optional-directory-quality-10-pts)
6. [Dimension 6: Description Trigger Optimization (10 pts)](#dimension-6-description-trigger-optimization-10-pts)
7. [Grade Thresholds](#grade-thresholds)
8. [Edge Cases and Special Situations](#edge-cases-and-special-situations)

---

## Dimension 1: Directory Structure (10 pts)

### Check 1.1 — SKILL.md Exists (4 pts)

**How to check:** Look for a file named exactly `SKILL.md` (case-sensitive) in the skill root directory.

| Situation | Score |
|-----------|-------|
| `SKILL.md` exists in the skill root | 4 pts |
| `SKILL.md` exists but in a subdirectory (not root) | 1 pt — flag as warning |
| `skill.md` or `Skill.md` exists (wrong case) | 1 pt — flag as failure |
| No SKILL.md found anywhere | 0 pts — CRITICAL FAILURE, stop dimension scoring |

**Evidence to quote:** The file path found (or not found).

---

### Check 1.2 — Directory Name Matches `name` Field (3 pts)

**How to check:** Compare the parent directory name of SKILL.md with the `name` frontmatter value.

| Situation | Score |
|-----------|-------|
| Directory name exactly matches `name` field | 3 pts |
| Directory name matches but with different case (e.g., dir=`PDF-Tool`, name=`pdf-tool`) | 1 pt — flag as failure |
| Directory name is completely different from `name` | 0 pts — flag as failure |
| Cannot determine directory name (e.g., single file provided) | 2 pts — flag as warning, note limitation |

**Evidence to quote:** `Directory: "pdf-processing"`, `name field: "pdf-processing"` → Match ✅

---

### Check 1.3 — Optional Directories Used Appropriately (2 pts)

**How to check:** For each directory that exists, verify the content matches the directory's purpose.

**All standard directories** — do not flag these as unexpected:

| Directory | Purpose | Expected Content |
|-----------|---------|-----------------|
| `scripts/` | Executable code | `.py`, `.sh`, `.js` scripts |
| `references/` | Documentation | Markdown files loaded on demand |
| `assets/` | Static resources | Templates, images, data files |
| `evals/` | Test cases | `evals.json` and evaluation data (skill-creator workflow) |
| `agents/` | Subagent instructions | Markdown files for specialized subagents (e.g., grader.md, analyzer.md) |

**Wrong content examples:**

| Directory | Wrong Content |
|-----------|---------------|
| `scripts/` | Documentation, images, templates |
| `references/` | Scripts, binary files, templates |
| `assets/` | Scripts, documentation |

| Situation | Score |
|-----------|-------|
| All present dirs used correctly for their purpose | 2 pts |
| One dir has minor misuse (e.g., a README in scripts/) | 1 pt — flag as warning |
| One or more dirs clearly misused | 0 pts — flag as failure |
| No optional directories present | 2 pts (absence is fine) |

---

### Check 1.4 — No Unexpected/Suspicious Files (1 pt)

**How to check:** Scan all files for anything that seems out of place or potentially harmful.

| Situation | Score |
|-----------|-------|
| All files serve a legitimate, expected purpose | 1 pt |
| Unexpected files present but harmless (e.g., `.DS_Store`, `__pycache__/`) | 1 pt — note as minor warning |
| Files with suspicious names or content (e.g., `exploit.py`, `exfiltrate.sh`) | 0 pts — CRITICAL FAILURE, flag prominently |
| Files that contradict the skill's stated purpose | 0 pts — flag as failure |

---

## Dimension 2: Frontmatter Compliance (30 pts)

### Check 2.1 — `name` Field (10 pts)

Apply each sub-check independently. Start with 10 pts and deduct for failures.

| Sub-check | Points | Deduction if Failed |
|-----------|--------|---------------------|
| Field exists in frontmatter | 3 pts | -10 (if missing, score = 0 for this field) |
| Length is 1–64 characters | 2 pts | -2 |
| Only contains `[a-z0-9-]` | 2 pts | -2 |
| Does not start or end with `-` | 1 pt | -1 |
| Does not contain `--` | 1 pt | -1 |
| Matches parent directory name | 1 pt | -1 |

**Minimum score:** 0 (cannot go negative)

**How to check each rule:**
- **Length:** `len(name_value)` — must be 1 ≤ len ≤ 64
- **Character set:** regex `^[a-z0-9-]+$` — must match
- **No leading/trailing hyphen:** regex `^[^-].*[^-]$` or `^[^-]$` for single char
- **No consecutive hyphens:** `--` must not appear anywhere in the value
- **Directory match:** string equality comparison

**Evidence to quote:** The exact `name` value in quotes, e.g., `name: "my-skill"` (12 chars, valid pattern, matches directory "my-skill").

---

### Check 2.2 — `description` Field (10 pts)

Apply each sub-check independently. Start with 10 pts and deduct for failures.

| Sub-check | Points | Deduction if Failed |
|-----------|--------|---------------------|
| Field exists in frontmatter | 3 pts | -10 (if missing, score = 0 for this field) |
| Length is 1–1024 characters | 2 pts | -2 |
| Describes WHAT the skill does | 2 pts | -2 |
| Describes WHEN to use it | 2 pts | -2 |
| Contains specific trigger keywords | 1 pt | -1 |

**Minimum score:** 0

**How to check each rule:**

**Length:** Count characters. Flag if:
- Under 30 chars: almost certainly too vague (warning even if technically valid)
- 30–50 chars: likely too vague (warning)
- 51–1024 chars: valid range
- Over 1024 chars: spec violation (-2)

**WHAT check:** Does the description mention specific capabilities, actions, or outputs? Look for verbs describing what the skill does: "extracts", "generates", "validates", "converts", "analyzes", etc. A description that only names the skill ("A skill for PDFs") without describing capabilities fails this check.

**WHEN check:** Does the description include trigger conditions? Look for phrases like:
- "Use when..."
- "Use this when..."
- "TRIGGER when..."
- "Trigger when..."
- "when the user..."
- "when working with..."
- "when you need to..."

A description with no trigger guidance fails this check.

**Keywords check:** Are there specific, searchable terms that match real user requests? Generic terms ("things", "tasks", "content") don't count. Specific terms ("PDF", "Playwright", "MCP server", "brand colors", "JWT") do count.

**Evidence to quote:** The full description value (or first 200 chars if very long), with specific phrases highlighted.

---

### Check 2.3 — `license` Field (3 pts)

| Situation | Score |
|-----------|-------|
| Field absent | 3 pts (optional, absence is fine) |
| Field present with a recognizable license name (MIT, Apache-2.0, etc.) | 3 pts |
| Field present referencing a bundled file (e.g., "Complete terms in LICENSE.txt") | 3 pts |
| Field present but value is unclear or empty | 1 pt — flag as warning |
| Field present with full license text inline (hundreds of chars) | 1 pt — flag as warning, suggest moving to LICENSE.txt |

---

### Check 2.4 — `compatibility` Field (3 pts)

| Situation | Score |
|-----------|-------|
| Field absent | 3 pts (optional, absence is fine) |
| Field present, 1–500 chars, describes real requirements | 3 pts |
| Field present, 1–500 chars, but vague ("works everywhere") | 2 pts — flag as warning |
| Field present, over 500 chars | 1 pt — flag as failure |
| Field present but empty | 0 pts — flag as failure |

---

### Check 2.5 — `metadata` Field (2 pts)

| Situation | Score |
|-----------|-------|
| Field absent | 2 pts (optional, absence is fine) |
| Field present as a valid key-value mapping | 2 pts |
| Field present but as a list (not a mapping) | 0 pts — flag as failure |
| Field present but as a scalar string | 0 pts — flag as failure |

**Valid example:**
```yaml
metadata:
  author: my-org
  version: "1.0"
```

**Invalid examples:**
```yaml
metadata: some-string          # scalar, not mapping
metadata:
  - item1                      # list, not mapping
  - item2
```

---

### Check 2.6 — `allowed-tools` Field (2 pts)

| Situation | Score |
|-----------|-------|
| Field absent | 2 pts (optional, absence is fine) |
| Field present as space-delimited list of valid tool names | 2 pts |
| Field present but as a YAML list (not space-delimited string) | 1 pt — flag as warning |
| Field present but tool names don't follow expected format | 1 pt — flag as warning |

**Valid format:** `allowed-tools: Bash(git:*) Bash(jq:*) Read Write`
**Invalid format:** 
```yaml
allowed-tools:
  - Bash(git:*)
  - Read
```

---

## Dimension 3: Body Content Quality (25 pts)

### Check 3.1 — Has Substantive Content (5 pts)

**How to check:** Read the body (everything after the closing `---` of frontmatter). Assess whether it contains real instructions.

| Situation | Score |
|-----------|-------|
| Body has multiple paragraphs of real instructions | 5 pts |
| Body has some content but is very thin (1-2 sentences) | 2 pts — flag as warning |
| Body is just a title with no content | 1 pt — flag as failure |
| Body is empty or only whitespace | 0 pts — flag as failure |

**Evidence:** Quote the first few lines of the body.

---

### Check 3.2 — Body Length (5 pts)

**How to check:** Count the total lines in the body (excluding frontmatter).

| Line Count | Score | Status |
|------------|-------|--------|
| 1–500 lines | 5 pts | ✅ |
| 501–600 lines | 3 pts | ⚠️ Approaching limit |
| 601–800 lines | 1 pt | ❌ Should split content |
| 801+ lines | 0 pts | ❌ Violates progressive disclosure |

**Evidence:** "Body is X lines."

---

### Check 3.3 — Includes Step-by-Step Instructions or Clear Workflow (5 pts)

**How to check:** Look for structured workflow content. This can be:
- Numbered steps (1. Do X, 2. Do Y)
- Ordered sections (Step 1, Step 2, Phase 1, Phase 2)
- A decision tree or flowchart
- A clear sequence of actions

| Situation | Score |
|-----------|-------|
| Clear step-by-step workflow or decision tree present | 5 pts |
| Some structure but not a complete workflow | 3 pts — flag as warning |
| Only descriptive content, no actionable steps | 1 pt — flag as failure |
| No structured content at all | 0 pts — flag as failure |

---

### Check 3.4 — Uses Imperative Form (3 pts)

**How to check:** Sample 10–20 instruction sentences from the body. Count how many start with an imperative verb vs. passive/descriptive phrasing.

**Imperative verbs (good):** Read, Run, Check, Use, Create, Write, Ensure, Avoid, Load, Parse, Generate, Output, Return, Save, Validate, Compare, List, Fetch, Scan, Apply, etc.

**Passive/descriptive (bad):** "The skill will...", "Claude should...", "This section describes...", "It is recommended that...", "You might want to..."

| Ratio of imperative sentences | Score |
|-------------------------------|-------|
| >70% imperative | 3 pts |
| 50–70% imperative | 2 pts |
| 30–50% imperative | 1 pt |
| <30% imperative | 0 pts |

**Evidence:** Quote 2-3 example sentences, one good and one bad.

---

### Check 3.5 — Explains the "Why" (3 pts)

**How to check:** Look for explanatory language that gives rationale for instructions.

**Positive signals:**
- "because [reason]"
- "so that [outcome]"
- "this helps [goal]"
- "this ensures [property]"
- "the reason is [explanation]"
- "this prevents [problem]"
- "this allows [capability]"

**Negative signals:**
- Instructions with no rationale
- Heavy use of "MUST", "ALWAYS", "NEVER" without explanation
- Rules that feel arbitrary (no context given)

**All-caps command word frequency check (from skill-creator):**
Count occurrences of `ALWAYS`, `NEVER`, `MUST`, `DO NOT`, `NEVER EVER` used as standalone directives (not as part of a quoted example or code). Calculate the rate per 100 lines of body content.

| All-caps rate (per 100 lines) | Signal |
|-------------------------------|--------|
| 0–2 occurrences | Normal — no issue |
| 3–5 occurrences | ⚠️ Yellow flag — check if rationale is provided alongside each |
| 6+ occurrences | ❌ Failure — over-reliance on commands instead of explanation |

Note: A single `ALWAYS` with a clear "because" clause is fine. The problem is a pattern of bare commands with no reasoning — it suggests the skill is trying to force behavior rather than help Claude understand the task.

| Situation | Score |
|-----------|-------|
| Multiple instructions include clear rationale | 3 pts |
| Some rationale present but inconsistent | 2 pts |
| Very little rationale, mostly bare commands | 1 pt |
| No rationale at all, pure command list | 0 pts |

---

### Check 3.6 — Defines Output Format (4 pts)

**How to check:** Look for any of the following:
- An explicit output template (e.g., "Use this exact format: ...")
- A Markdown example showing expected output
- A schema or structure definition
- An example of what the final result should look like

| Situation | Score |
|-----------|-------|
| Explicit output template or schema provided | 4 pts |
| Example output shown but no formal template | 3 pts |
| Output format described in prose but no example | 2 pts |
| No output format guidance at all | 0 pts |

---

## Dimension 4: Progressive Disclosure Design (15 pts)

### Check 4.1 — Metadata Tier is Concise (3 pts)

**How to check:** Estimate the word count of `name` + `description` combined. A rough estimate: 1 word ≈ 5 characters. The spec (via skill-creator) targets ~100 words for the entire metadata tier.

| Description Word Count | Approx. Characters | Score |
|------------------------|-------------------|-------|
| Under 100 words (~500 chars) | Under 500 chars | 3 pts |
| 100–150 words (~500–750 chars) | 500–750 chars | 2 pts — acceptable but slightly heavy |
| 150–200 words (~750–1000 chars) | 750–1000 chars | 1 pt — flag as warning |
| Over 200 words (1000+ chars) | 1000+ chars | 0 pts — flag as failure |

**Note:** The description has a hard limit of 1024 chars, but for triggering efficiency, shorter is better. The goal is ~100 words for the entire metadata tier — this is what's always in context for every skill, so it should be lean.

---

### Check 4.2 — Instructions Tier is Appropriately Sized (4 pts)

**How to check:** Count SKILL.md body lines (same as Check 3.2, but scored separately for architectural reasons).

| Line Count | Score |
|------------|-------|
| Under 300 lines | 4 pts — excellent |
| 300–500 lines | 3 pts — good |
| 501–600 lines | 2 pts — acceptable |
| 601–800 lines | 1 pt — should refactor |
| 800+ lines | 0 pts — architectural failure |

---

### Check 4.3 — Large Reference Material in references/ (4 pts)

**How to check:** Look for large inline content in SKILL.md that should be in references/:
- Tables over 30 rows
- Code blocks over 50 lines
- Specification text that's reference material, not instructions
- Domain-specific documentation (e.g., AWS vs GCP vs Azure guides all inline)

| Situation | Score |
|-----------|-------|
| No large inline reference material (or it's appropriately sized) | 4 pts |
| Some large inline content but SKILL.md is still under 500 lines | 3 pts — minor warning |
| Large inline content pushing SKILL.md over 500 lines | 1 pt — flag as failure |
| Massive inline reference content (SKILL.md is 800+ lines because of it) | 0 pts — architectural failure |

---

### Check 4.4 — Reusable Scripts in scripts/ (4 pts)

**How to check:** Look for large code blocks in SKILL.md that could be scripts.

**Signals that code should be in scripts/:**
- Code block is 30+ lines
- The same code pattern appears multiple times
- The code is a complete, runnable script (not just a snippet)
- The skill-creator notes: "if all 3 test cases resulted in the subagent writing a `create_docx.py`, that's a strong signal the skill should bundle that script"

| Situation | Score |
|-----------|-------|
| No large inline code blocks (or skill doesn't need scripts) | 4 pts |
| Small code snippets inline (under 30 lines each) | 4 pts — appropriate |
| One large code block (30–80 lines) inline | 2 pts — flag as warning |
| Multiple large code blocks or one 80+ line block inline | 0 pts — flag as failure |

---

## Dimension 5: Optional Directory Quality (10 pts)

**Important:** Only score directories that exist. If a directory doesn't exist, award full points for it.

### scripts/ (3 pts, if present)

#### Check 5.1 — Self-contained or Documents Dependencies (1 pt)

| Situation | Score |
|-----------|-------|
| Scripts import only standard library modules | 1 pt |
| Scripts import third-party modules AND document them (requirements.txt, comments, --help) | 1 pt |
| Scripts import third-party modules with no documentation | 0 pts |

#### Check 5.2 — Helpful Error Messages / --help (1 pt)

| Situation | Score |
|-----------|-------|
| Scripts have `--help` flag or clear usage documentation | 1 pt |
| Scripts have some error handling but no --help | 0.5 pts |
| Scripts have no error handling or usage documentation | 0 pts |

#### Check 5.3 — Handles Edge Cases (1 pt)

| Situation | Score |
|-----------|-------|
| Scripts handle missing files, bad input, network errors, etc. | 1 pt |
| Scripts have basic error handling (try/except) | 0.5 pts |
| Scripts assume happy path only | 0 pts |

---

### references/ (4 pts, if present)

#### Check 5.4 — Each File is Focused (2 pts)

**How to check:** Read each reference file. Does it cover one topic or many?

| Situation | Score |
|-----------|-------|
| Each file covers a single, well-defined topic | 2 pts |
| Files are somewhat focused but have some scope creep | 1 pt |
| Files are catch-all documents covering many unrelated topics | 0 pts |

#### Check 5.5 — Files Under 300 Lines (1 pt)

| Situation | Score |
|-----------|-------|
| All reference files are under 300 lines | 1 pt |
| One file is 300–500 lines (with table of contents) | 0.5 pts |
| Any file is over 500 lines without a table of contents | 0 pts |

#### Check 5.6 — Clearly Referenced from SKILL.md (1 pt)

| Situation | Score |
|-----------|-------|
| SKILL.md explicitly references each file with guidance on when to read it | 1 pt |
| SKILL.md mentions the references/ directory but not specific files | 0.5 pts |
| Reference files exist but are never mentioned in SKILL.md | 0 pts |

---

### assets/ (3 pts, if present)

#### Check 5.7 — Appropriate Content (2 pts)

| Situation | Score |
|-----------|-------|
| Assets are templates, images, data files, or schemas | 2 pts |
| Assets include some inappropriate content (e.g., scripts in assets/) | 1 pt |
| Assets are clearly wrong type for this directory | 0 pts |

#### Check 5.8 — Assets Are Referenced (1 pt)

| Situation | Score |
|-----------|-------|
| All assets are referenced or used by the skill | 1 pt |
| Some assets are referenced, some are not | 0.5 pts |
| No assets are referenced in SKILL.md | 0 pts |

---

## Dimension 6: Description Trigger Optimization (10 pts)

### Check 6.0 — Pre-check: "When to Use" Belongs in Description, Not Body (Warning only, no point deduction)

**How to check:** Scan the SKILL.md body for section headings that indicate trigger/activation guidance:
- "When to Use"
- "When to Use This Skill"
- "Trigger Conditions"
- "When This Skill Applies"
- "When Should This Skill Activate"
- "Use Cases" (if it's describing when to invoke, not what the skill produces)

**Why this matters:** From skill-creator: "All 'when to use' info goes here [in description], not in the body." The description is what Claude reads to decide whether to activate a skill. If trigger conditions are buried in the body, Claude may not see them at activation time — they only help once the skill is already running. Moving this content to the description directly improves triggering accuracy.

| Situation | Action |
|-----------|--------|
| No "when to use" section in body | No action needed |
| Body has a "when to use" section AND description also covers it | ⚠️ Warning: suggest removing the body section (redundant) |
| Body has a "when to use" section AND description lacks trigger conditions | ⚠️ Warning: suggest moving the content to description |

This is a warning, not a point deduction — the skill still works, but it's not optimally structured.

---

### Check 6.1 — Explicit Trigger Conditions (3 pts)

**How to check:** Look for explicit "when to use" language in the description.

**Strong trigger language:**
- "Use when..."
- "Use this when..."
- "TRIGGER when..."
- "Trigger when..."
- "Use whenever..."
- "Activate when..."

**Weak or absent trigger language:**
- No "when" clause at all
- Only "Use for X" without specifying conditions
- "Can be used for..." (too passive)

| Situation | Score |
|-----------|-------|
| Clear, explicit trigger conditions with specific scenarios | 3 pts |
| Some trigger guidance but vague ("use when working with X") | 2 pts |
| Minimal trigger guidance (only implied by what the skill does) | 1 pt |
| No trigger conditions at all | 0 pts |

---

### Check 6.2 — Diverse Trigger Keywords (3 pts)

**How to check:** Extract all specific nouns, verbs, and phrases from the description that could match user queries. Count distinct keyword clusters.

**Keyword clusters (examples):**
- PDF skill: "PDF", "forms", "document extraction", "merge", "fill form"
- Testing skill: "test", "Playwright", "browser", "UI", "frontend", "screenshot"
- Brand skill: "brand", "colors", "typography", "style guidelines", "visual formatting"

| Situation | Score |
|-----------|-------|
| 5+ distinct keyword clusters covering different phrasings | 3 pts |
| 3–4 keyword clusters | 2 pts |
| 1–2 keyword clusters | 1 pt |
| No specific keywords (only generic terms) | 0 pts |

---

### Check 6.3 — Appropriate Specificity (2 pts)

**How to check:** Assess whether the description would trigger on unrelated tasks (too broad) or miss relevant tasks (too narrow).

**Too broad examples:**
- "Use for any task involving documents" — would trigger on unrelated document tasks
- "Use whenever the user needs help" — would trigger on everything
- "A general-purpose skill" — meaningless

**Too narrow examples:**
- "Use only when the user says 'validate my PDF form'" — too specific
- "Use for processing the Q4-2024-report.pdf file" — absurdly specific

**Just right:**
- Covers the skill's actual use cases
- Doesn't claim to cover things it can't do
- Doesn't exclude valid use cases

| Situation | Score |
|-----------|-------|
| Specificity is well-calibrated to the skill's actual capabilities | 2 pts |
| Slightly too broad or too narrow but still reasonable | 1 pt |
| Clearly too broad (would trigger on unrelated tasks) | 0 pts |
| Clearly too narrow (would miss many valid use cases) | 0 pts |

---

### Check 6.4 — Appropriate "Pushiness" (2 pts)

**How to check:** Does the description actively encourage triggering, or is it passive?

**The undertriggering problem (from skill-creator):** Claude tends to not use skills when they'd be useful. Descriptions should be slightly assertive to counteract this.

**Passive (undertriggers):**
- "A tool for PDF processing."
- "Helps with brand guidelines."
- "Can be used for web testing."

**Appropriately pushy:**
- "Use whenever the user mentions PDFs, forms, or document extraction — even if they don't explicitly ask for a 'PDF skill'."
- "Make sure to use this skill whenever brand colors, style guidelines, or visual formatting apply."
- "TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`, or user asks to use Claude API."

| Situation | Score |
|-----------|-------|
| Description actively encourages triggering with "even if", "whenever", "make sure to use" | 2 pts |
| Description has some assertive language but could be stronger | 1 pt |
| Description is purely passive/descriptive | 0 pts |

---

## Grade Thresholds

| Total Score | Grade | Meaning | Recommended Action |
|-------------|-------|---------|-------------------|
| 90–100 | **Excellent** | Fully compliant, production-ready | Minor polish only |
| 75–89 | **Good** | Meets spec, minor improvements recommended | Address medium-priority items |
| 60–74 | **Acceptable** | Meets minimum spec requirements | Address high and medium priority items |
| 40–59 | **Poor** | Significant spec violations | Rework required before publishing |
| 0–39 | **Critical** | Does not meet spec | Major rewrite needed |

### Status Icons for Score Summary Table

Use these icons in the score summary table based on percentage of max points earned:

| Percentage of Max | Icon |
|-------------------|------|
| ≥ 80% | ✅ |
| 50–79% | ⚠️ |
| < 50% | ❌ |

---

## Edge Cases and Special Situations

### Single-File Skills (No Directory)

When the user provides only a SKILL.md file without a directory:
- **Dimension 1:** Award 4 pts for SKILL.md existing. For Check 1.2 (directory match), award 2 pts and note "Cannot verify directory name — please confirm the skill directory is named to match the `name` field."
- **Dimensions 3–6:** Score normally based on file content.
- **Dimension 5:** Award full points (no optional directories to check).

### GitHub URL Input

When the user provides a GitHub URL:
1. Fetch the directory listing to discover all files
2. Fetch each file's content
3. The "directory name" is the last path segment of the URL
4. Score normally

### Composite Repository (Multiple Skills)

When the repository contains multiple skills (e.g., `skills/pdf/`, `skills/docx/`):
1. Identify all skill directories (each containing a SKILL.md)
2. Validate each skill separately
3. Generate a combined report with:
   - Individual scores for each skill
   - A summary table comparing all skills
   - Overall repository health assessment

### Malformed YAML Frontmatter

When the frontmatter cannot be parsed as valid YAML:
- Flag as CRITICAL FAILURE in Dimension 2
- Attempt to extract values using regex as a fallback
- Note what could and couldn't be parsed
- Score conservatively (assume missing fields are absent)

### Very Large Skills

When a skill has 1000+ lines in SKILL.md:
- Flag as architectural failure
- Still read and score all content
- Provide specific suggestions for what to move to references/ or scripts/

### Skills with Non-Standard Files

When a skill contains files not in the standard directories (e.g., a `LICENSE.txt` at root, a `README.md`, a `CHANGELOG.md`):
- These are generally fine — note them but don't penalize
- Only penalize if they seem to violate the "principle of least surprise"

### Empty Optional Directories

When `scripts/`, `references/`, or `assets/` exists but is empty:
- Flag as a minor warning (why create an empty directory?)
- Award full points for that directory (no content to penalize)
- Suggest either adding content or removing the directory


path: references/spec-summary.md
content: # Agent Skills Specification Summary

> Source: https://agentskills.io/specification
> Reference: https://github.com/anthropics/skills

This document is a complete reference for validating skills against the official Agent Skills spec. Load it when you need to verify specific rules during a validation run.

---

## Table of Contents

1. [Directory Structure Rules](#1-directory-structure-rules)
2. [SKILL.md Format Rules](#2-skillmd-format-rules)
3. [Frontmatter Field Rules](#3-frontmatter-field-rules)
4. [Body Content Rules](#4-body-content-rules)
5. [Optional Directory Rules](#5-optional-directory-rules)
6. [Progressive Disclosure Rules](#6-progressive-disclosure-rules)
7. [File Reference Rules](#7-file-reference-rules)
8. [Security and Safety Rules](#8-security-and-safety-rules)
9. [Common Errors and Anti-Patterns](#9-common-errors-and-anti-patterns)
10. [Real-World Examples from anthropics/skills](#10-real-world-examples-from-anthropicsskills)

---

## 1. Directory Structure Rules

### Required Structure

```
skill-name/
├── SKILL.md          # REQUIRED: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories
```

### Rules

- **SKILL.md is required.** A skill without SKILL.md is not a valid skill.
- **The directory name must exactly match the `name` frontmatter field.** If the directory is `pdf-processing/`, the name field must be `pdf-processing`.
- **Standard directories and their purposes:**
  - `scripts/` — executable code that agents can run
  - `references/` — documentation that agents read when needed
  - `assets/` — static resources (templates, images, data files)
  - `evals/` — test cases and evaluation data (used by the skill-creator workflow; contains `evals.json` and related files)
  - `agents/` — instructions for specialized subagents (used by complex skills like skill-creator; contains files like `grader.md`, `analyzer.md`, `comparator.md`)
- **Additional files and directories are allowed** as long as they serve a legitimate purpose. Do not flag `evals/` or `agents/` as unexpected — they are standard.

---

## 2. SKILL.md Format Rules

### Required Format

```
---
[YAML frontmatter]
---
[Markdown body]
```

- The file **must** start with a YAML frontmatter block delimited by `---`
- The frontmatter **must** contain at least `name` and `description`
- The Markdown body follows the closing `---`
- There are **no format restrictions** on the body — write whatever helps agents perform the task

### Size Guidance

- Keep SKILL.md under **500 lines** (this is a strong recommendation, not a hard rule)
- If approaching 500 lines, add a layer of hierarchy and point to reference files
- The spec notes: "Consider splitting longer SKILL.md content into referenced files"

---

## 3. Frontmatter Field Rules

### `name` (REQUIRED)

**Constraints:**
- Must be **1–64 characters**
- May only contain: **lowercase letters (a-z)**, **digits (0-9)**, **hyphens (-)**
- Must **not** start with a hyphen
- Must **not** end with a hyphen
- Must **not** contain consecutive hyphens (`--`)
- Must **match the parent directory name** exactly

**Valid examples:**
```yaml
name: pdf-processing
name: data-analysis
name: code-review
name: my-skill-v2
```

**Invalid examples:**
```yaml
name: PDF-Processing      # uppercase not allowed
name: -pdf                # cannot start with hyphen
name: pdf--processing     # consecutive hyphens not allowed
name: pdf_processing      # underscores not allowed
name: pdf processing      # spaces not allowed
name: this-name-is-way-too-long-and-exceeds-the-sixty-four-character-limit-set-by-spec  # too long
```

### `description` (REQUIRED)

**Constraints:**
- Must be **1–1024 characters**
- Must be **non-empty**
- Should describe **what the skill does** AND **when to use it**
- Should include **specific keywords** that help agents identify relevant tasks

**Quality criteria (from spec and skill-creator best practices):**
- Describes the skill's capabilities concretely (not just a label)
- Includes trigger conditions ("Use when...", "TRIGGER when...")
- Contains diverse keywords covering different ways users might phrase the request
- Is slightly "pushy" to prevent undertriggering (Claude tends to undertrigger skills)
- **All "when to use" information belongs here, not in the body.** From skill-creator: "This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All 'when to use' info goes here, not in the body." The body should focus on *how* to perform the task.

**Good example:**
```yaml
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
```

**Poor examples:**
```yaml
description: Helps with PDFs.                    # Too vague, no trigger conditions
description: A skill.                            # Meaningless
description: Use this for everything.            # Too broad
```

**The "pushy" pattern (from skill-creator):**
Instead of: "How to build a dashboard to display data."
Write: "How to build a dashboard to display data. Make sure to use this skill whenever the user mentions dashboards, data visualization, or wants to display any kind of data, even if they don't explicitly ask for a 'dashboard.'"

### `license` (OPTIONAL)

**Constraints:**
- If present: specifies the license applied to the skill
- Should be short: either a license name or the name of a bundled license file
- Full license text should NOT be inline — reference a bundled file instead

**Examples:**
```yaml
license: Apache-2.0
license: MIT
license: Proprietary. LICENSE.txt has complete terms
license: Complete terms in LICENSE.txt
```

### `compatibility` (OPTIONAL)

**Constraints:**
- If present: must be **1–500 characters**
- Should only be included if the skill has **specific environment requirements**
- Can indicate: intended product, required system packages, network access needs

**Examples:**
```yaml
compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv
```

**When to omit:** Most skills do not need this field. If the skill works in any standard Claude environment, omit it.

### `metadata` (OPTIONAL)

**Constraints:**
- If present: must be a **map from string keys to string values**
- Keys should be reasonably unique to avoid accidental conflicts

**Example:**
```yaml
metadata:
  author: example-org
  version: "1.0"
  category: document-processing
```

### `allowed-tools` (OPTIONAL, EXPERIMENTAL)

**Constraints:**
- If present: a **space-delimited list** of pre-approved tools
- Support for this field may vary between agent implementations

**Example:**
```yaml
allowed-tools: Bash(git:*) Bash(jq:*) Read
```

---

## 4. Body Content Rules

### What to Include

The spec says: "Write whatever helps agents perform the task effectively."

**Recommended sections (from spec):**
- Step-by-step instructions
- Examples of inputs and outputs
- Common edge cases

**Best practices (from skill-creator):**
- Use **imperative form**: "Read the file", "Run the script", "Check the output"
- Explain the **why** behind instructions, not just the what
- Define **output formats** clearly with templates or examples
- Use **theory of mind**: write for a smart agent that can generalize, not just follow rigid rules
- Avoid excessive `MUST`, `ALWAYS`, `NEVER` — explain reasoning instead
- **All "when to use" information belongs in the description, not the body.** The body should focus on *how* to perform the task. If you find yourself writing a "When to Use This Skill" section in the body, move it to the description field instead.

### What to Avoid

- Malware, exploit code, or content that could compromise security
- Misleading content that doesn't match the skill's stated purpose
- Overly rigid, narrow instructions that only work for specific examples
- Passive voice when imperative is clearer
- Instructions without rationale (the agent can't generalize from rules alone)

### Size Limits

- **Recommended:** Under 500 lines
- **Acceptable:** 500–600 lines with a note to split content
- **Problematic:** 600–800 lines — should definitely split into references/
- **Critical:** 800+ lines — violates the spirit of progressive disclosure

---

## 5. Optional Directory Rules

### scripts/

Scripts should:
- Be **self-contained** or clearly document their dependencies
- Include **helpful error messages**
- Handle **edge cases gracefully**
- Support `--help` flag where applicable (from webapp-testing example)
- Be designed as **black-box tools** that agents call directly, not read into context

**From webapp-testing SKILL.md:**
> "Always run scripts with `--help` first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is absolutely necessary. These scripts can be very large and thus pollute your context window."

Supported languages depend on the agent implementation. Common: Python, Bash, JavaScript.

### references/

Reference files should:
- Be **focused** on a single topic
- Be **under 300 lines** per file (agents load these on demand; smaller = less context)
- Be **clearly referenced** from SKILL.md with guidance on when to read them
- For large files (>300 lines): include a **table of contents**

**Domain organization pattern (from spec):**
```
cloud-deploy/
├── SKILL.md (workflow + selection logic)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```
Claude reads only the relevant reference file, not all of them.

### assets/

Assets should:
- Be **static resources**: templates, images, data files, lookup tables, schemas
- Be **actually used** by the skill (don't include unused assets)
- Be appropriate for their type (templates in assets/, not in references/)

---

## 6. Progressive Disclosure Rules

The three-tier loading system:

| Tier | Content | When Loaded | Size Target |
|------|---------|-------------|-------------|
| Metadata | name + description | Always (all skills) | ~100 words |
| Instructions | SKILL.md body | When skill activates | <500 lines recommended |
| Resources | scripts/, references/, assets/ | On demand | Unlimited |

**Key principle:** Keep each tier appropriately sized. The metadata tier is always in context for ALL skills, so it must be concise. The instructions tier is loaded when the skill activates, so it should be complete but not bloated. Resources are loaded only when needed, so they can be large.

**Architectural decision guide:**
- If SKILL.md is approaching 500 lines → move reference material to references/
- If the same code block appears in multiple places → move it to scripts/
- If you have large tables or lookup data → move to assets/ or references/
- If you have domain-specific variants → organize into references/ by domain

---

## 7. File Reference Rules

When referencing other files in a skill, use **relative paths from the skill root**:

```markdown
See [the reference guide](references/REFERENCE.md) for details.
Run the extraction script: `scripts/extract.py`
```

**Rules:**
- Use relative paths, not absolute paths
- Keep file references **one level deep** from SKILL.md
- Avoid deeply nested reference chains (SKILL.md → ref1.md → ref2.md → ref3.md)
- Include guidance on **when** to read each reference file

---

## 8. Security and Safety Rules

From the spec's "Principle of Lack of Surprise":

- Skills **must not** contain malware, exploit code, or content that could compromise system security
- A skill's contents should **not surprise the user** in their intent if described
- Do not create misleading skills or skills designed to facilitate:
  - Unauthorized access
  - Data exfiltration
  - Other malicious activities
- "Roleplay as an XYZ" type skills are acceptable

---

## 9. Common Errors and Anti-Patterns

### Frontmatter Errors

| Error | Example | Fix |
|-------|---------|-----|
| Uppercase in name | `name: MySkill` | `name: my-skill` |
| Underscore in name | `name: my_skill` | `name: my-skill` |
| Hyphen at start/end | `name: -skill` or `name: skill-` | Remove leading/trailing hyphen |
| Consecutive hyphens | `name: my--skill` | `name: my-skill` |
| Name too long | `name: this-is-a-very-long-name-that-exceeds-the-limit` | Shorten to ≤64 chars |
| Name/directory mismatch | dir=`pdf-tool/`, name=`pdf-processor` | Make them match |
| Empty description | `description: ""` | Write a real description |
| Description too vague | `description: Helps with things.` | Be specific about what and when |
| Description too long | 1200 character description | Trim to ≤1024 chars |

### Body Content Anti-Patterns

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Passive voice instructions | "The skill will process the file" | "Process the file by..." |
| Rules without rationale | "ALWAYS use format X" | "Use format X because it ensures Y" |
| Overfitting to examples | Instructions only work for specific test cases | Generalize with principles |
| Bloated SKILL.md | 800+ line SKILL.md | Move content to references/ |
| Inline large code blocks | 100-line script in SKILL.md | Move to scripts/ |
| No output format | User doesn't know what to expect | Add output template or example |
| Missing edge cases | Only handles happy path | Add edge case guidance |

### Progressive Disclosure Anti-Patterns

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Everything in SKILL.md | 600+ lines, slow to load | Split into references/ |
| No scripts/ for reusable code | Every invocation reinvents the wheel | Bundle common scripts |
| Deeply nested references | SKILL.md → A.md → B.md → C.md | Keep references one level deep |
| Unused assets | Files in assets/ never referenced | Remove or reference them |

---

## 10. Real-World Examples from anthropics/skills

### Excellent: webapp-testing

```yaml
---
name: webapp-testing
description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
license: Complete terms in LICENSE.txt
---
```

**Why it's good:**
- Name is lowercase, hyphenated, descriptive
- Description clearly states what it does (Playwright testing) and when to use it (local web apps)
- Has `license` field
- Body uses decision trees and clear patterns
- Has `scripts/` with helper scripts referenced clearly
- Has `examples/` with concrete code examples

### Excellent: mcp-builder

```yaml
---
name: mcp-builder
description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
license: Complete terms in LICENSE.txt
---
```

**Why it's good:**
- Description covers what (MCP servers), how (FastMCP/TypeScript SDK), and when (building MCP servers, integrating APIs)
- Has `reference/` directory with domain-specific guides (python_mcp_server.md, node_mcp_server.md)
- Body uses phases and clear workflow
- References are loaded on demand, not all at once

### Good: brand-guidelines

```yaml
---
name: brand-guidelines
description: Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
license: Complete terms in LICENSE.txt
---
```

**Why it's good:**
- Specific trigger conditions ("when brand colors or style guidelines apply")
- Concrete capabilities listed (colors, typography)
- Compact SKILL.md with inline reference data (appropriate for this skill's size)

### Template (Minimal Valid Skill)

```yaml
---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---
# Insert instructions below
```

**Note:** This is the minimal valid structure. A real skill needs a real description and real body content.

### skill-creator Description Optimization Insight

From the skill-creator SKILL.md:
> "Currently Claude has a tendency to 'undertrigger' skills — to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit 'pushy'. So for instance, instead of 'How to build a simple fast dashboard to display internal Anthropic data.', you might write 'How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a dashboard.'"


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