mcpField
S
skill-authoring

skill-authoring

github.com/atholaエージェントワークフロー343109 回インストール4 日前に更新
リポジトリ

skill-authoring について

Claude Code のスキルを作成する人向けのガイドです。実際の失敗記録を起点とする TDD、モジュール化された手順、検証ゲートを特徴とします。

主な機能

  1. 01テスト先行の RED-GREEN-REFACTOR 手順
  2. 02Technique、Pattern、Reference の 3 種類
  3. 03検索されやすいスキル説明の指針
  4. 04モジュール化と段階的な情報開示
  5. 05検証とデプロイの品質ゲート

活用シーン

  1. 01観測した失敗事例をもとにスキルを作成
  2. 02スキルと関連モジュールを構成
  3. 03スキル説明とトリガーを改善
  4. 04デプロイ前にスキルを検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/athola/claude-night-market --skill skill-authoring

インストール後、Claude Code で/skill-authoringを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
modules/
advanced-patterns.md
authentication.md
deployment-checklist.md
description-writing.md
error-handling.md
examples.md
graphviz-conventions.md
persuasion-principles.md
progressive-disclosure.md
tdd-methodology.md
testing-with-subagents.md
troubleshooting.md
validation.md

詳細

スキル作成ガイド

使用しない場合

  • 既存のスキルを評価する場合（abstract:skills-eval を使用）
  • フックを作成する場合（abstract:hook-authoring を使用）
  • スキルが実行されることを検証する場合（abstract:subagent-testing を使用）

概要

効果的な Claude Code スキルを作成するには、テスト駆動開発（TDD）と、コンプライアンス研究に基づく説得の原則が必要です。スキルの作成は、理論的な指示にとどまらず、実証的な検証を要するプロセスのドキュメント化だと考えます。スキルは、測定可能な形でモデルの振る舞いを変えるための介入です。

TDD を用いることで、テストで特定された実際の失敗パターンにスキルで対処できるようにします。最適化された説明文はスキルの発見性を高め、モジュール式の構成は段階的な情報開示を可能にし、トークン使用量の管理に役立ちます。スキルは意図、制約、終了条件を明示し、それらを結ぶ作業の道筋は、作業を行うセッションに委ねます。modules/persuasion-principles.md では、各記述がこの3つのどれにどれだけ踏み込むかを決める説得力の予算を定めています。

鉄則

最初に失敗するテストを行わずにスキルを作成してはいけません

すべてのスキルは、スキルがない状態で Claude が失敗したことを示す、記録済みの証拠から始める必要があります。これにより、現実の問題を解決していることを確認できます。失敗するテストなしに実装を進めてはならず、証拠なしに完了を主張してもいけません。敵対的検証とカバレッジゲートの詳細な適用パターンについては、imbue:proof-of-work を参照してください。

スキルの種類

スキルは、特定の手法を扱うテクニックスキル、繰り返し使える解決策を扱うパターンスキル、すばやく確認するためのリファレンススキルの3種類に分類します。これにより、タスクに最も適した形式で介入を整理できます。

クイックスタート

スキル分析

```bash

スキルの複雑さを分析

python scripts/skill_analyzer.py

トークン数を推定

python scripts/token_estimator.py ```

検証

```bash

スキルの構造を検証

python scripts/abstract_validator.py --check ```

検証：先に進む前に、分析を実行し、トークン数の推定結果を確認してください。

説明文の最適化

スキルの説明文は、セマンティック検索と明示的な起動に向けて最適化する必要があります。[機能] + [使用する場面] + [主なトリガー] の形式に従ってください。三人称の表現（例：「案内します」「提供します」）を使い、具体的で明確なユースケースを含めてください。宣伝文句や「コーディングを支援します」のような曖昧な表現は避けてください。

スキルの文字数上限（Claude Code 2.1.32+）

スキルの説明文に使える文字数は、コンテキストウィンドウのサイズに応じて、使用可能なコンテキストの2%まで拡大するようになりました。つまり、次のとおりです。

コンテキストウィンドウ説明文の文字数上限
200K（Sonnet/Haiku）約4,000文字
1M（Opus 4.6 GA）約20,000文字

以前は制限されていたスキルでも、コンテキストウィンドウが大きければ、より詳しい説明文を使用できます。ただし、説明文は引き続き簡潔にしてください。長ければよいわけではありません。この拡大は、正当に複雑なトリガー条件を持つスキルの説明文が切り詰められるのを防ぐためのものであり、冗長な内容を追加するよう促すものではありません。

プラグイン名の自動表示（Claude Code 2.1.33+）

/skills メニューにスキルの説明文と並んでプラグイン名が自動表示されるようになりました。スキルの説明文にプラグイン名を繰り返し記載しないでください。重複となり、文字数上限を無駄に消費します。スキルの機能と使用する場面に説明を集中させてください。

スキルの TDD サイクル

RED フェーズ：ベースラインの失敗を記録する

介入が必要であることを示す実証的な証拠を確立します。時間的なプレッシャーと曖昧さを組み合わせたシナリオを少なくとも3つ作成します。スキルを有効にせず、新しいインスタンスで実行し、エラー処理の省略や検証の欠落など、具体的な失敗を記録します。

GREEN フェーズ：最小限のスキル実装

文書化された失敗に対処する、最小限の介入策を作成します。必須のフロントマターと、ベースラインの失敗に直接対処する内容を含む SKILL.md を作成します。正しい動作の例を1つ含め、同じプレッシャーシナリオで測定可能な改善が見られることを検証します。

REFACTOR フェーズ：トリガーを明確にする

Claude が要件を都合よく解釈して回避できないようにします。スキルを有効にした状態でプレッシャーシナリオを実行し、「タスクが簡単すぎる」など、よくある正当化を特定します。正当化がなくなるまで、例外テーブルや危険信号リストなど、明示的な対策を追加します。

スキルを適用するかどうかの判断

スキルでは、要件の回避を試みる Claude のパターンに明示的に対処する必要があります。よくある言い訳には、「タスクが簡単すぎる」や、「法の精神に従えば条文どおりでなくても十分」と主張することなどがあります。スキルには、自己確認のための危険信号リストを含めます。たとえば、「こう考えたら止まる：完全なプロセスを適用するには簡単すぎる」といった項目です。例外が必要な場合は、許可されていない近道を防ぐため、例外を明示的に文書化します。

モジュールの参照先

詳細な実装ガイダンスについては、以下を参照してください。

中核となる作成サイクル：

  • TDD の方法論：RED-GREEN-REFACTOR サイクルの詳細については、modules/tdd-methodology.md を参照してください
  • 指示の強さ：どの程度強く指示するか、何が不変条件に値するかについては、modules/persuasion-principles.md を参照してください
  • 説明文の作成：発見しやすさの最適化については、modules/description-writing.md を参照してください
  • 段階的開示：ファイル構造のパターンについては、modules/progressive-disclosure.md を参照してください
  • スキルの選択：スキルを適用するかどうかの判断については、../../shared-modules/skill-selection-judgment.md を参照してください
  • Graphviz の規約：プロセス図の標準については、modules/graphviz-conventions.md を参照してください

具体的なスキルを扱う場合（実装またはデバッグ時に読み込んでください）：

  • 注釈付きの例：このリポジトリで適切に作成されたスキルの解説については、modules/examples.md を参照してください
  • 高度なパターン：スキル間の連携、条件付き動作、アクティベーションコンテキストに応じた拡張については、modules/advanced-patterns.md を参照してください
  • 認証：gh、glab、MCP サーバー、その他の認証が必要なツールを使用するスキルについては、modules/authentication.md を参照してください
  • エラー処理：ツールの不足、タイムアウト、サブエージェントの部分的な結果、権限拒否については、modules/error-handling.md を参照してください
  • トラブルシューティング：テストコーパスどおりに動作しないスキルの診断については、modules/troubleshooting.md を参照してください

検証とデプロイ（リリース時に読み込んでください）：

  • 検証：マージ前のフロントマター解析、参照解決、構造チェックについては、modules/validation.md を参照してください
  • サブエージェントを使ったテスト：新しいサブエージェントで Iron Law テストを実行する方法については、modules/testing-with-subagents.md を参照してください（より広範なプレッシャーテストの方法論については、abstract:subagent-testing を参照してください）
  • デプロイチェックリスト：スキルを昇格する前の最終検証については、modules/deployment-checklist.md を参照してください

デプロイと品質ゲート

デプロイ前に、RED、GREEN、REFACTOR の各フェーズが完了し、文書化されていることを確認してください。フロントマターが有効で、説明が最適化され、行数が500行未満である必要があります。すべてのモジュール参照が有効であることを確認し、具体例を少なくとも1つ含めてください。

対象読者への適合

SKILL.md ハブは「実践者」向けのドキュメントです。読者はその分野に詳しく、このリポジトリ独自の見解に触れることになります。その読者に向けてハブを書き、スキルの保守担当者だけが必要とする情報はすべて modules/ に記載し、modules: フロントマターに列挙してください。そうすることで、progressive_loading によってハブのトークン予算から除外されます。これは、500 行の上限によってすでに求められている区分けと同じですが、行数ではなく読者に基づいて判断します。

スキルの読者が実践者でない場合は、スキルの冒頭の行でそのことを明記してください。また、作成者が判断していない場合は、推測せずに質問してください。ティア表、ソクラテス式の質問集、抽出プロトコルについては、scribe:slop-detector モジュールの audience-targeting.md を参照してください。

Scribe による検証

すべての Markdown ファイルは Scribe の検証に合格する必要があります。これには、スコアを 2.5 未満にするためのスロップスキャンと、すべてのファイルパスおよびコマンド例が機能することを確認するドキュメント検証が含まれます。読みやすさを保つため、箇条書きと本文の比率は 60% 未満にしてください。これらの確認には Skill(scribe:slop-detector) と Agent(scribe:doc-verifier) を使用してください。

統合とベストプラクティス

個々のスキルは skill-authoring を使用して作成し、大規模な構造のアーキテクチャは modular-skills で扱います。skills-eval は継続的な品質評価を行います。理論上の動作に基づいてスキルを書くというよくある落とし穴を避け、開発の指針として、常に記録された失敗を活用してください。段階的開示を用いて、ファイルがモノリシックになるのを防ぎ、各介入が焦点を保ち、トークン効率に優れるようにしてください。

関連スキル
  • Skill(superpowers:writing-skills)：Claude Code スキルの作成に関する superpowers の上流の見解です。このガイドの TDD サイクルと併せて、スキルの構成や作成技法の補足資料として読み込んでください。

スキルディレクトリ変数（2.1.69+）

SKILL.md の内容では、${CLAUDE_SKILL_DIR} を使用してスキル自身のディレクトリを参照できます。この変数は、SKILL.md ファイルを含むディレクトリの絶対パスに解決されます。絶対パスをハードコードせずに、同階層のファイル、データアセット、モジュールパスを参照する場合に使用してください。

See `${CLAUDE_SKILL_DIR}/modules/advanced-patterns.md`
for detailed patterns.

Run: `python3 ${CLAUDE_SKILL_DIR}/scripts/check.py`

これは、スクリプトやデータファイルとともに配布され、プラグインのインストール場所にかかわらず機能するポータブルなパス参照が必要なスキルで特に役立ちます。

説明文のコロンに関する修正（2.1.69+）

コロンを含むスキルの説明文（例：description: "Triggers include: X, Y, Z"）は、以前は SKILL.md のフロントマターからの読み込みに失敗していました。この問題は 2.1.69 で修正されています。また、description: フィールドのないスキルも利用可能なスキル一覧に表示されるようになりました（以前はひそかに除外されていました）。

トラブルシューティング

よくある問題

スキルが読み込まれない YAML フロントマターの構文と必須フィールドを確認してください。 2.1.69 以降、description: フィールドのないスキルもスキル一覧に表示されますが、コロンを含む説明文は YAML フロントマター内で引用符で囲む必要があります。

トークン制限を超過する 段階的開示を使用してください。詳細をモジュールに移動します。

モジュールが見つからない SKILL.md 内のモジュールパスが正しいことを確認してください。

完了基準

  • RED フェーズは、スキルがない場合に Claude が失敗することを示すプレッシャーシナリオを少なくとも 3 つ用いて記録されており、実装を開始する前に失敗の内容が正確に記録されている。
  • GREEN フェーズでは、有効な YAML フロントマター（引用符で囲んだ説明文、必須の name フィールド）を含み、Claude Code でエラーなく読み込まれる SKILL.md が作成される。
  • REFACTOR フェーズでは、特定した合理化パターンを少なくとも 1 つ記録し、スキルに明示的な対抗策（例外表、危険信号の一覧、禁止する言い訳の一覧）を追加する。
  • python scripts/abstract_validator.py --check が終了コード 0 で終了し、SKILL.md が 500 行未満である。
  • ハブは宣言された 1 つの読者ティアに対応し、別のティア向けの情報は modules/ に配置され、フロントマターに列挙されている。

コメント

Markdown 対応