quality-audit

品質監査スキル

明確さ、完全性、正確性、有用性の4つの側面からスキルの品質を評価するための体系的なフレームワークです。

このスキルを使用するタイミング

• 新しいスキルをレジストリに追加する前にレビューするとき
• 品質向上のために既存のスキルを監査するとき
• スキル検証用の品質基準を作成するとき
• ライブラリ全体でスキルの品質を標準化するとき
• スキルを本番環境で使用する準備をするとき

基本原則

4つの品質評価軸

評価軸	配点	焦点
明確さ	25%	構成、読みやすさ、段階的な情報開示
完全性	25%	網羅性、例、エッジケース、アンチパターン
正確性	30%	正しさ、ベストプラクティス、セキュリティ
有用性	20%	実際の適用可能性、本番利用への準備状況

評価スケール（1～5）

スコア	ラベル	意味
1	受け入れ不可	根本的に壊れている、危険、または使用不能
2	要改善	大幅な修正が必要な重大な問題がある
3	許容可能	最低基準を満たし、機能する
4	良好	高品質で、軽微な改善の余地がある
5	優秀	模範的で、本番環境に対応し、最高水準

合格基準

• 最低基準：加重平均3.0（許容可能）
• 目標：加重平均4.0（良好）
• 卓越：加重平均4.5以上（優秀）
• ブロッキング条件：正確性は3.0以上であること（危険な助言がないこと）

監査ワークフロー

フェーズ1：構成チェック

checklist:
  structure:
    - [ ] Has valid YAML frontmatter
    - [ ] Contains required metadata (name, description)
    - [ ] Follows progressive disclosure (Tier 1 → 2 → 3)
    - [ ] Sections are logically ordered
    - [ ] Token estimate is reasonable (<5000 for core)

フェーズ2：内容の評価

checklist:
  content:
    - [ ] "When to Use" section is clear
    - [ ] Core principles are well-defined
    - [ ] Code examples are complete and runnable
    - [ ] Anti-patterns are documented
    - [ ] Troubleshooting guidance exists

フェーズ3：評価軸ごとの採点

各評価軸について、具体的な基準に照らして評価します。

明確さの基準：

• 論理的な流れに沿って整理されたセクション
• 専門用語を過度に使わない簡潔な説明
• 読みやすく、十分なコメントが付いたコード例
• 簡単な内容から複雑な内容へと段階的に情報を開示している

完全性の基準：

• 中核となる概念を十分に網羅している
• エッジケースとエラー処理を含んでいる
• すべきことと、してはいけないことの両方を示している
• 主なユースケースに対応した実用的な例がある

正確性の基準：

• コード例がエラーなくコンパイルまたは実行できる
• 現在のベストプラクティスに従っている（非推奨ではない）
• セキュリティ上の考慮事項が正しい
• パフォーマンスに関する主張を検証できる

有用性の基準：

• 実例が現実の問題を解決している
• すぐに適用できる
• 本番環境のユースケースにも対応できる
• トラブルシューティングの指針を含んでいる

フェーズ4：レポートの生成

## Audit Report: {skill_name}

**Date**: {date}
**Auditor**: {auditor}
**Status**: {PASS|FAIL|NEEDS_REVIEW}

### Scores

| Dimension | Score | Weight | Weighted |
|-----------|-------|--------|----------|
| Clarity | {x}/5 | 25% | {x*0.25} |
| Completeness | {x}/5 | 25% | {x*0.25} |
| Accuracy | {x}/5 | 30% | {x*0.30} |
| Usefulness | {x}/5 | 20% | {x*0.20} |
| **Total** | | | **{sum}/5** |

### Issues Found

- [CRITICAL] {issue description}
- [MAJOR] {issue description}
- [MINOR] {issue description}

### Recommendations

1. {actionable recommendation}
2. {actionable recommendation}

実装パターン

パターン1：クイック監査（5分間のレビュー）

スキルの品質を迅速に評価する場合に使用します。

# Run automated structure checks
cortex skills audit <skill-name> --quick

# Output: Pass/Fail with basic metrics

クイック監査のチェック項目：

1. YAML フロントマターは有効か？
2. 必須セクションはそろっているか？
3. コードブロックに言語タグが付いているか？
4. TODO/FIXME マーカーが残っていないか？
5. トークン数は妥当か？

パターン2：完全監査（15～30分間のレビュー）

人によるレビューを含む包括的な評価です。

# Generate full audit report
cortex skills audit <skill-name> --full

# Interactive mode for scoring
cortex skills audit <skill-name> --interactive

完全監査の手順：

1. 自動チェックを実行する
2. 内容を手作業で読み通す
3. コード例をテストする
4. 各評価軸を採点する
5. 問題点と推奨事項を記録する
6. レポートを生成する

パターン3：比較監査

スキルをリファレンス実装と比較します。

# Compare against template-skill-enhanced
cortex skills audit <skill-name> --compare template-skill-enhanced

パターン4：一括監査

レジストリの健全性を確認するため、複数のスキルを監査します。

# Audit all skills in a category
cortex skills audit --category security

# Audit skills below threshold
cortex skills audit --below-score 3.5

CLI コマンド

# Basic audit
cortex skills audit <skill-name>

# Options
  --quick           Quick structural check only
  --full            Full audit with all dimensions
  --interactive     Interactive scoring mode
  --output FILE     Write report to file
  --format FORMAT   Output format (markdown|json|yaml)
  --compare SKILL   Compare against reference skill
  --fix             Auto-fix simple issues (formatting)

カスタム基準の作成

スキルでは、validation/rubric.yaml にカスタム基準を定義できます。

# validation/rubric.yaml
version: "1.0.0"
skill_name: my-skill

dimensions:
  clarity:
    weight: 25
    criteria:
      - "API examples use realistic data"
      - "Error handling is shown for each operation"
  completeness:
    weight: 25
    criteria:
      - "Covers all HTTP methods"
      - "Includes pagination patterns"
  accuracy:
    weight: 30
    criteria:
      - "Follows REST conventions"
      - "Security headers documented"
  usefulness:
    weight: 20
    criteria:
      - "Examples work with common frameworks"

passing_criteria:
  minimum_score: 3.5  # Higher bar for this skill
  required_dimensions:
    - accuracy
    - completeness

ベストプラクティス

すべきこと

• 具体的にする — 「セキュリティ上の問題がある」ではなく、「45行目：SQL クエリにインジェクションの脆弱性がある」と記載します
• 実行可能な内容にする — 各問題の修正方法を記載します
• 公平に評価する — 一貫して同じ基準を適用します
• 根拠を記録する — 各スコアの根拠として、該当する内容を引用します
• 優先順位を付ける — 重大な問題を先に、提案を最後に扱います

してはいけないこと

• 個人的なスタイルの好みに基づいて採点する
• 代替案を提示せずに、非推奨のパターンを指摘する
• 任意のセクションがないことを理由にスキルを不合格にする
• 他のスコアに関係なく、セキュリティ上の問題を無視する
• 複雑なスキルの監査を急いで済ませる

アンチパターン

判を押すだけの審査

問題：十分なレビューを行わずにスキルを承認してしまいます なぜ問題なのか：品質の低いスキルは、ライブラリへの信頼を損ないます 解決策：監査チェックリストをすべて使用し、コード例をテストします

完璧主義による却下

問題：些細な問題を理由にスキルを不合格にします なぜ問題なのか：役に立つスキルを利用できなくなります 解決策：ブロッキングとなる問題と提案を区別します

スコアの水増し

問題：根拠を示さずに高いスコアを付けます なぜ問題なのか：スコアの意味がなくなります 解決策：各スコアの具体的な根拠を記録します

CI/CD との統合

# .github/workflows/skill-quality.yml
name: Skill Quality Gate

on:
  pull_request:
    paths:
      - 'skills/**'

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install cortex
        run: pip install cortex
      - name: Audit changed skills
        run: |
          for skill in $(git diff --name-only HEAD~1 | grep 'skills/' | cut -d'/' -f2 | uniq); do
            cortex skills audit "$skill" --quick --fail-under 3.0
          done

トラブルシューティング

「監査に失敗するのに、スキルには問題がないように見えます」

1. YAML フロントマターの構文を確認します
2. 必須セクションがすべて存在することを確認します
3. コードブロックに言語タグが付いていることを確認します
4. 不可視文字（コピー＆ペーストの問題）がないか確認します

「スコアに一貫性がないように見えます」

1. 各評価項目の採点ガイドを確認します
2. まず template-skill-enhanced を監査して、評価基準を調整します
3. 基準をより明確にするには、--interactive モードを使用します

外部リソース

• スキルテンプレートのリファレンス
• 評価基準のスキーマ
• スキル作成者向けガイド

変更履歴

1.0.0 (2026-01-05)

• 初回リリース
• 4 項目の評価フレームワーク
• CLI との統合
• CI/CD ワークフローの例