SuperAPI AI Directory

claude-skill-review

Coding & development

View repository

Updated 10-16 10:03

About this skill

Claude Code Skill Review

A skill that reviews the quality of Claude Code skills based on official best practices.

When to use

  • When a PR includes a SKILL.md file
  • When asked to check skill quality
  • Self-review when creating a new skill

Official documentation reference

For detailed rules and background, refer to the following:

  • Skill overview: @references/01_skill_overview.md
  • Best practices: @references/02_best_practices.md

Review procedure

Step 1: Frontmatter validation (Critical)

Field Requirement
name Required, max 64 characters, lowercase letters, numbers, and hyphens only, no reserved words (anthropic, claude)
description Required, non-empty, max 1024 characters

Critical determination:

  • Frontmatter is missing → Critical
  • nameis in an invalid format → Critical
  • descriptionis empty → Critical

Step 2: description quality check (Major/Minor)

Required elements (Major):

  1. What it does: Concretely explain the skill's functionality
  2. When to use it: Clearly state the trigger conditions

Quality check (Minor):

  • ✅ Write in third person ("does ~", "processes ~")
  • ✅ Contains specific keywords
  • ❌ Avoid first person and second person ("I will help you")
  • ❌ Avoid vague expressions ("useful for documentation")

Step 3: Directory structure check (Critical/Major)

Correct placement for marketplace distribution:

{domain}/skills/{skill-name}/
├── SKILL.md           # 必須
├── references/        # オプション
└── scripts/           # オプション

Critical: Incorrect placement:

  • ❌ ~/.claude/skills/ - User's install location
  • ❌ .claude/skills/ - For project-specific skills

Major: Naming convention violation:

  • ❌ CamelCaseやsnake_case
  • ✅ kebab-case (gerund form recommended: processing-pdfs)

Step 4: SKILL.md body quality check (Minor)

  • ✅ 500 lines or fewer (if exceeded, split into separate files)
  • ✅ Contains concrete examples (Example)
  • ✅ Has a clear workflow/steps
  • ✅ Uses consistent terminology throughout
  • ✅ Omit general knowledge Claude already knows

Step 5: Reference file check (Major/Minor)

  • ✅ All referenced files exist (Major)
  • ✅ References are only one level deep (Minor)
  • ✅ Files of 100 lines or more have a table of contents (Minor)
  • ✅ File paths use forward slashes (Minor)

Step 6: Detecting Patterns to Avoid

Pattern Severity
Time-sensitive information ("From August 2025 onward, ...") Major
Presenting many options in parallel Minor
Vulnerability to prompt injection Critical
Deeply nested references (2 or more levels) Minor
Windows-style paths (backslashes) Minor

Scoring Criteria

Score Criteria
10/10 All check items cleared
8-9/10 1-2 Minor issues
6-7/10 1 Major issue, or 3 or more Minor issues
5 or less/10 Critical issues present, or multiple Major issues

Output Format

## 📦 Skill Quality: X/10

### フロントマター
- [✅/❌] name: [評価コメント]
- [✅/❌] description: [評価コメント]

### ディレクトリ構造
- [✅/❌] 配置: [評価コメント]
- [✅/❌] 命名: [評価コメント]

### SKILL.mdボディ
- [✅/❌] 行数: [X行]
- [✅/❌] 例の有無: [評価コメント]
- [✅/❌] ワークフロー: [評価コメント]

### 参照ファイル
- [✅/❌] 存在確認: [評価コメント]
- [✅/❌] ネスト深度: [評価コメント]

### 検出された問題
| 重要度 | 問題 | 推奨される対応 |
|--------|------|---------------|
| [Critical/Major/Minor] | [問題の説明] | [対応方法] |