reviewing-skills

Skill Review

Review skills based on official best practices and provide concrete improvement suggestions.

Review Workflow

Step 1: Identify the target skill

Identify the SKILL.md file to review:

• User specifies the path directly
• Search for SKILL.md in the current directory
• If multiple skills exist, confirm with the user

Step 2: Load and analyze

1. Fully load the target SKILL.md file
2. best-practices.md Check the checklist with
3. Parse the YAML frontmatter (name, description)
4. Analyze the structure of the body content

Step 3: Compare against best practices

Evaluate each category:

Frontmatter Check

• name: length, format, naming conventions
• description: completeness, specificity, triggers

Body Check

• Line count (target: 500 lines or fewer)
• Clarity of structure
• Use of Progressive Disclosure
• Quality of workflow design

Content Check

• Consistency of terminology
• Quality of examples
• Appropriateness of templates

Anti-pattern detection

• Multiple options without a default
• Windows-style paths
• Time-dependent information
• Magic constants

Step 4: Generate review report

Output format:

# スキルレビューレポート: {skill-name}

## サマリー
- 総合評価: {PASS | NEEDS_IMPROVEMENT | CRITICAL_ISSUES}
- Critical: {件数}
- Warning: {件数}
- Info: {件数}

## Critical（必須修正）
{修正必須の問題をリスト}

## Warning（推奨修正）
{推奨される改善をリスト}

## Info（改善提案）
{オプションの強化をリスト}

## 具体的な推奨事項
{例を含む具体的なアクションアイテム}

Step 5: Interactive improvement

After presenting the report:

1. Ask the user whether they want fixes
2. Fix Critical issues first
3. Apply fixes incrementally
4. Re-validate after each fix

Severity classification

Critical

Issues that prevent the skill from functioning properly:

• description is empty or missing
• Body significantly exceeds 500 lines
• Script security vulnerabilities
• Insufficient script error handling

Warning

Issues that reduce the effectiveness of the skill:

• Progressive Disclosure is not applied
• Insufficient examples
• Terminology is inconsistent
• Workflow is unclear

Info

Opportunities for improvement:

• Can be made more concise
• Structure optimization
• Additional examples would be good

Review session example

User: "Review the pdf-processor skill"

1. 読み込み: skills/pdf-processor/SKILL.md
2. ロード: references/best-practices.md
3. チェックリストに照らして分析
4. 日本語でレポート生成
5. 修正を提案