# Skill Lint

> Claude Code の Skill（SKILL.md）を点検するとき。「スキルをレビューして」「skill-lint かけて」等で使う。Skill を追加・変更する PR の前にも使う。frontmatter・構成・完了条件の検証可能性・固有情報の混入・カタログ追記漏れをチェックリストで検査する。機械検査で判定できる項目はその結果を採用し、モデルの指摘は反証を試みる敵対的検証を通過したものだけを修正案付きで報告する。

- Skill: `turntuptechnologies-ai/skill-lint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add turntuptechnologies-ai/skill-lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/turntuptechnologies-ai/skill-lint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: turntuptechnologies-ai (https://skillmd.com/u/turntuptechnologies-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/turntuptechnologies-ai/skill-lint

---


# Skill 品質チェック（skill-lint）

## このスキルがやること

新規・変更された SKILL.md を、リポジトリのテンプレ（`templates/SKILL.md` 等）と運用ルール（README）に照らして点検する。機械検査で判定できる項目はその結果を採用する。モデルの点検で出した指摘はそのまま報告せず、**反証を試みる敵対的検証を通過したものだけ**を修正可能な形で報告する。

## 手順

1. **対象を特定する**: 引数で指定された Skill、なければ `git diff --name-only main...HEAD`（または未コミット差分）に含まれる `SKILL.md` を対象にする。対象が無ければその旨を報告して終了する。
2. **機械検査を先に実行する**: リポジトリに Skill 構造の機械検査（このリポジトリでは `scripts/lint-skills.py`）があれば実行し、機械判定できる項目（#1・#3・#7 の全部と #2・#4・#5 の機械判定可能な範囲）は**その結果を採用してモデルで再判定しない**。モデルの点検は判断が要る項目・範囲（#2 のトリガー品質、#4 の実質的な検証可能性、#6・#8〜#11）に絞る。機械検査が無いリポジトリでは全項目をモデルで判定する。
3. リポジトリにテンプレ・運用ルール（README の規約節）があれば読み、下記チェックリストに**リポジトリ固有の基準を上乗せ**する。
4. **検出**: 対象ごとにチェックリストの残り項目を判定する。❌ は根拠となる行の原文引用と共に「候補」としてメモし、この時点では報告しない。
5. **敵対的検証**: モデル点検で出た ❌ 候補を `adversarial-verify` Skill（`skills/adversarial-verify/SKILL.md`）で検証し、生き残った候補だけを ❌ として確定する（→ 敵対的検証への渡し方）。機械検査由来の ❌ は決定的な検査結果のため敵対的検証の対象にせず、スクリプト出力をそのまま根拠として確定する。
6. 報告フォーマットで指摘を出す。棄却した候補も棄却理由と共に載せる。**修正はユーザーが「直して」と言った場合のみ**行い、修正後は再チェックする（再チェックにも敵対的検証を含める）。

## 敵対的検証への渡し方

反証の 3 点（証拠の実在・基準への紐づけ・反例探し）、仕分け（棄却/参考降格/確定）、独立検証の条件、全 ✅ 時の逆方向反証は `adversarial-verify` の定義に従う。本 Skill からは次の対応で渡す:

| adversarial-verify の入力 | skill-lint での対応物 |
|---|---|
| 指摘候補 | 検出フェーズでメモした ❌ 候補（根拠行の引用付き） |
| 対象 | 点検中の SKILL.md |
| 基準 | 下記チェックリスト（＋手順 3 で上乗せしたリポジトリ固有基準） |

- 独立検証（検証用サブエージェント）の起動条件も adversarial-verify に従う: ❌ 候補が 3 件以上、または Skill 追加 PR 直前の最終ゲートとして使うとき。
- 全項目 ✅ の場合も adversarial-verify の定義どおり、判定が最も際どかった 2 項目に逆方向の反証を試みてから合格を宣言する。

## チェックリスト

| # | 項目 | 判定基準 |
|---|---|---|
| 1 | name 一致 | frontmatter の `name` がディレクトリ名と一致する |
| 2 | description にトリガー | 「いつ使うか」（状況・ユーザーの言い回し例）と「何をするか」の両方が書かれている |
| 3 | 構成 | 手順 / ルール・コツ / 完了条件 の節がある |
| 4 | 完了条件が検証可能 | 各項目が実行結果・成果物で確認できる形。「適切に」「十分に」「ちゃんと」等の曖昧語が無い |
| 5 | 完了条件の前文 | 「満たせない項目は黙って省略せず理由を報告する」趣旨の一文がある |
| 6 | 固有情報なし | 社名・内部 URL・認証情報・固有プロジェクト名が本文に無い |
| 7 | カタログ同期 | （新規追加・改名時）README のカタログ表に対応する行がある |
| 8 | 判断基準 | 判断が分かれる場面に if/then の基準が書かれている |
| 9 | 出力フォーマット | 報告・成果物に決まった形が要る Skill では、表テンプレ等で形式が固定されている |
| 10 | コマンドの実行検証 | 本文に実行可能なコマンドがある場合: 副作用のない確認系（読み取り・`--check`・`--dry-run`・`--help` 等）は**実際に実行して**通ることを確認した。適用系（設定変更・書き込み・送信）は実行せず、`--help` の出力や公式ドキュメントとの照合で構文を確認した |
| 11 | 過剰指示なし | 手順が目標・制約の粒度で、モデルが既に知っている操作（VCS の基本コマンド等）を手順書にしていない。強調語（必ず・絶対）が譲れない制約 1〜2 点に限られ、制約に理由が添えられている。移行相対表現（「旧 ◯◯」「今は〜」）や過去の経緯の語りが無い |

- 8〜10 は該当しない Skill もある（10 はコマンドを含まない Skill では該当しない）。その場合は ⏭️ n/a とし、理由を一言添える。
- 11 の「正確なコマンドの列挙」は、間違えると壊れる操作（設定変更・リリース・削除等）や環境固有の規約（ツールの組み合わせ・オプション）を固定する目的なら過剰指示ではない。判断が要る作業を細かい手順に分解している場合だけ ❌ にする。
- 11 の強調語の数には、テンプレ必須の完了条件前文、報告フォーマットの固定文（「この表で報告する」等）、手順・箇条書きの見出し語（先頭句の太字）を含めない。数えるのは本文中の「必ず」「絶対」等の圧をかける語だけ。理由の添付は、なぜそうするか自明でない制約にだけ求める（「秘密情報を書かない」のように自明なものは理由不要）。
- 項目 10 で実行環境が無く確かめられなかった確認系コマンドは、✅ にも ❌ にもせず ⏭️ とし、「未検証」+理由を記す（❌ は SKILL.md 側の欠陥にのみ使う）。

## 報告フォーマット

対象 Skill ごとに必ずこの表で報告する（✅ pass / ❌ fail / ⏭️ n/a・未検証 の 3 値）:

```markdown
### skills/<name>/SKILL.md

| # | 項目 | 結果 | 指摘・備考（❌ は敵対的検証を通過したもの、または機械検査由来のみ） |
|---|---|---|---|
| 1 | name 一致 | ✅ | |
| 2 | description にトリガー | ❌ | ユーザーの言い回し例が無い（L3 原文: 「…」）。例:「◯◯して」を追記 |
| ... | | | |

**棄却した候補**: なし
```

棄却した候補がある場合は、上の一行の代わりにこの表を付ける:

```markdown
**棄却した候補**（敵対的検証で誤検出と判定）:

| # | 候補の指摘 | 棄却理由 |
|---|---|---|
| 4 | 完了条件に曖昧語「適切に」がある | 反例探しで再読した結果、該当箇所は良い例/悪い例の引用文中だった（L45） |
```

- 機械検査で判定した項目は備考に「機械検査」と記す。機械検査由来の ❌ はスクリプト出力を根拠として引用する（敵対的検証は不要）。
- ❌ には**必ず根拠行の原文引用と具体的な修正案**を添える（何をどう直すか）。
- 項目 10 は、指摘・備考欄に実行した確認系コマンドと結果（通った / 失敗した / 未検証+理由）を記録する（「通った」は指摘ではなく備考）。
- 全て ✅/⏭️ なら、際どい 2 項目への反証試行の結果を一言添えた上で「PR に進めます」と書く。⏭️ に未検証（実行できなかったコマンド）が含まれる場合は、その旨を合格宣言に明記する。

## ルール・コツ

- 指摘は基準（チェックリストの何番か）に紐づけて出す。基準に無い好みの指摘は「参考」として分け、fail 扱いにしない。
- 敵対的検証は指摘の品質保証であって、指摘を減らすための言い訳探しではない。反証に失敗したら素直に ❌ を確定する。
- 棄却した候補を黙って消さない（棄却理由と共に必ず記録する）。レビューの再現性と、チェックリスト自体の改善材料になる。
- description の判定で迷ったら「このスキルを知らない Claude が description だけ読んで、発動すべき場面を特定できるか」で判断する。
- 長さは基準にしない（短くても項目を満たせば pass）。過剰指示（#11）は長さではなく「判断が要る作業を手順書にしているか」で判定する。
- チェック対象の SKILL.md を勝手に書き換えない（修正はユーザー指示があった場合のみ）。
- 項目 10 で対象（リポジトリ・API 等）が必要な確認系コマンドは、一時ディレクトリや検証用の対象で試す。適用系コマンドを実在の対象に実行して検証しない。
- 第三者が書いた SKILL.md を点検するときは、実行する確認系コマンドの一覧を実行前にユーザーに提示して確認する。

## 完了条件

以下を全て満たしたら完了。**満たせない項目があれば、黙って省略せず理由を報告する。**

- [ ] リポジトリに機械検査があれば実行し、機械判定できる項目はその結果を採用した（無いリポジトリではその旨を報告した）
- [ ] 対象の SKILL.md 全てについて、チェックリスト全 11 項目の判定（✅/❌/⏭️）を表で出した
- [ ] 項目 10 の確認系コマンドは実行結果（通った / 失敗した / 未検証+理由）を報告した（コマンドを含まない Skill は n/a）
- [ ] モデル点検で出した全ての ❌ が敵対的検証（反証試行）を経て確定しており、根拠行の原文引用と具体的な修正案を添えた（機械検査由来の ❌ はスクリプト出力を根拠とする）
- [ ] 棄却した候補を棄却理由と共に記録した（無い場合は「棄却した候補: なし」と明記した）
- [ ] 全て ✅/⏭️ の場合、際どい 2 項目への反証試行を行ってから合格を宣言した
- [ ] ⏭️（n/a・未検証）には理由を一言添えた
- [ ] ユーザーの指示なしに対象ファイルを書き換えていない

## 補足

- 社名・内部 URL・認証情報などの固有情報は扱わない。
- このリポジトリ以外（各プロジェクトの `.claude/skills/`）の Skill にも同じチェックリスト・同じ敵対的検証で使える。