skill-linter

スキルリンター

使用する場面

• マーケットプレイスに新しいスキルを追加するとき
• スキルの PR をレビューするとき
• マージ前に品質ゲートを実行するとき
• 既存のスキルが要件に準拠しているか確認するとき

検証ルール

必須の Frontmatter

フィールド	制約
name	1～64 文字。小文字の英数字とハイフンのみ使用でき、先頭・末尾・連続するハイフンは不可です。親ディレクトリ名と一致する必要があります。「claude」または「anthropic」は予約語のため使用できません。
description	1～1024 文字。空欄不可で、見つけやすさにつながるキーワードを含める必要があります。XML の山かっこ（< >）は使用できません。

任意の Frontmatter

フィールド	制約
compatibility	1～500 文字。環境要件を記述します。
metadata	キーと値のペア（値は文字列のみ）
allowed-tools	スペース区切りのツールリスト（カンマまたは配列構文がある場合は FAIL）

構造要件

ルール	要件
ディレクトリ名	name フィールドと完全に一致する必要があります
SKILL.md	必須。存在している必要があります
README.md	スキルフォルダー内に存在してはいけません（ドキュメントは SKILL.md または references/ に配置します）
行数制限	SKILL.md は最大 500 行です
サブディレクトリ	scripts/、references/、assets/ のみ許可されます

コンテンツの品質ルール

ルール	要件
ASCII アート禁止	罫線文字（─│┌┐└┘├┤┬┴┼）、矢印（↑↓←→↔）、装飾的な図はトークンを無駄にします。LLM は文字を視覚的にではなく、1 文字ずつトークン化します。代わりに、通常のリストまたは表を使用してください。
装飾的な引用禁止	名言や出典の記載（「X が言ったように…」）は、LLM の実行に機能的な価値をもたらしません。
ペルソナ表現禁止	「あなたは専門家です…」はトークンを無駄にします。代わりに 対象読者： / 目標： の形式を使用してください。
機能的なコンテンツのみ	すべての行が LLM の動作を改善するものである必要があります。「これは Claude の実行に役立つか？」と考えてください。

対象読者／目標の形式（必須）

ペルソナのロールプレイを、対象読者に焦点を当てた形式に置き換えます。

❌ 悪い例（ペルソナ）：

You are an expert software engineer with deep expertise in testing.
Your role is to analyze code and generate thorough test coverage.

✅ 良い例（対象読者／目標）：

**Audience:** Developers needing test coverage for new or changed code.

**Goal:** Generate comprehensive tests based on specified test type and framework.

理由：「ペルソナ Z として行動する」よりも、「対象読者 Y 向けに X を説明する」ほうが、対象に合わせた出力が得られます。

ASCII アート検出パターン：

[─│┌┐└┘├┤┬┴┼╭╮╯╰═║╔╗╚╝╠╣╦╩╬↑↓←→↔⇒⇐⇔▲▼◄►]{3,}

このパターンに一致するファイルは、レビュー対象としてフラグを立ててください。

description のルーティング品質（警告）

スキルの description はドキュメントではなく、ルーティングロジックです。次の点を示します。

• いつこのスキルを使用するか（トリガー条件）
• いつ使用しないか（ネガティブルーティング）
• どのような出力が期待できるか（成功基準）

品質レベル	例
良好	「Stimulus コントローラーを実装するときに使用します。React コンポーネントには使用しません。ターゲットとアクションを含むコントローラーを出力します。」
十分	「Rails アプリケーションで Stimulus コントローラーを扱うときに使用します。」
不十分	「Stimulus コントローラー開発スキル。」
アンチパターン	「最先端の Stimulus コントローラーを構築するための、包括的で強力なツールキットです。」

スキル内のテンプレートは推奨されます。トリガー時にのみ読み込まれるため、実質的にトークンを消費しません。

スキルの使い分け（情報）

複数のスキルが類似した領域を扱う場合は、ネガティブルーティングを含めてください。

例（minitest と rspec）：

スキル	description のルーティング
minitest-coder	「Minitest のテストを書くときに使用します。RSpec には使用せず、代わりに rspec-coder を使用してください。」
rspec-coder	「RSpec のテストを書くときに使用します。Minitest には使用せず、代わりに minitest-coder を使用してください。」

ルーティングの精度を高めるうえで、「いつ使用するか」と同じくらい「いつ使用しないか」も重要です。

名前のパターン

^[a-z][a-z0-9]*(-[a-z0-9]+)*$

有効： my-skill、skill1、api-v2-handler 無効： -skill、skill-、my--skill、MySkill、my_skill

コマンド／エージェントの呼び出しパターン

スキルでは、主にオーケストレーションではなく知識を提供します。呼び出しが必要な場合は、次のようにします。

パターン	ステータス	代わりに使用
Skill("command", args: "...")	❌ 非推奨	/command args
SlashCommand("command", ...)	❌ 非推奨	/command args
Task(subagent_type="agent", ...)	✅ 正しい	（変更なし）

✅ 推奨されるコマンドの呼び出し：

/majestic-engineer:tdd-workflow
/majestic-engineer:workflows:build-task "T1"

設定の読み込みには関数呼び出し形式を使用します（config-reader スキルを呼び出します）。

TECH_STACK = config_read("tech_stack", "generic")

❌ 非推奨のパターン：

Skill("config-reader", args: "tech_stack generic")
SlashCommand("majestic:build-task", args: "...")

注： Task() によるエージェントの呼び出しは正しい方法です。@agent 構文はありません。

使用方法

単一のスキルを検証する

./scripts/validate-skill.sh path/to/skill-name

Marketplace のすべてのスキルを検証する

for skill in plugins/*/skills/*/; do
  ./scripts/validate-skill.sh "$skill"
done

CI との統合

pre-commit フックまたは CI パイプラインに追加します。

- name: Lint Skills
  run: |
    for skill in plugins/*/skills/*/; do
      .claude/skills/skill-linter/scripts/validate-skill.sh "$skill" || exit 1
    done

検証スクリプト

script/validate-skill.sh のリンタースクリプトでは、次の項目をチェックします。

1. ディレクトリの存在 — SKILL.md ファイルがあること
2. フロントマターの有無 — YAML の区切り文字があること
3. name フィールドの有効性 — パターン、長さ、ディレクトリとの一致
4. 予約語 — name に「claude」または「anthropic」を含めることはできません（失敗）
5. description フィールドの有効性 — フィールドがあり、長さの制約を満たすこと
6. フロントマター内の XML タグ — 山括弧 < > がないこと（セキュリティ、失敗）
7. README.md がないこと — スキルフォルダー内に存在しないこと（警告）
8. オプションフィールドの有効性 — 存在する場合、制約を満たすこと
9. 行数 — 500 行未満であること
10. サブディレクトリ名 — 許可されたディレクトリのみであること
11. ASCII アートがないこと — フェンス付きコードブロック外に罫線文字がないこと（警告）
12. ペルソナを示す文がないこと — フェンス付きコードブロック外に「You are a/an/the」がないこと（失敗）
13. description のルーティング品質 — ルーティングキーワードが含まれていること（警告）
14. マーケティング文言の検出 — description 内の流行語（警告）

エラーコード

コード	意味
0	すべての検証に合格
1	SKILL.md が見つからない
2	フロントマターが無効
3	name の検証に失敗
4	description の検証に失敗
5	オプションフィールドの検証に失敗
6	行数の上限を超過
7	サブディレクトリが無効
8	ASCII アートを検出（警告）
9	ペルソナを示す文を検出
10	description のルーティング品質（警告）
11	マーケティング文言を検出（警告）

出力例

Validating: plugins/majestic-tools/skills/brainstorming

[PASS] SKILL.md exists
[PASS] Frontmatter present
[PASS] Name 'brainstorming' valid (12 chars)
[PASS] Name matches directory
[PASS] Description valid (156 chars)
[PASS] Line count: 87/500
[PASS] Subdirectories valid
[PASS] No ASCII art outside code blocks
[PASS] No persona statements
[PASS] Description has routing keywords
[PASS] No marketing copy in description

Result: ALL CHECKS PASSED

仕様リファレンス

agentskills.io/specification に基づいています。

• 段階的な開示 — 起動時のメタデータは約 100 トークン、有効化時の全コンテンツは 5000 トークン未満
• 参照ファイル — SKILL.md から 1 階層以内に配置します
• トークン予算 — メインの SKILL.md は 500 行未満を推奨します