skillz

skillz

スキルの追加、改善、監査、楔入れ、自動改善を行います。 改善と監査は、エージェント定義にも対応しています。 この製品は予測可能な定義です。すべての実行、すべてのハーネスで同じプロセスを適用します。 各視点では、各行について「実行をより予測可能にするものか、それとも堆積物か」を問います。

モードは、スキル名の次に来る最初の単語です。 Aliases 列には、同じモードを選択する名前が記載されています。 各モードでは対象を必須にします。 モードが指定されていない場合は、モードを尋ねます。 モードで対象が必要な場合は、対象を尋ねます。

モード

モード	別名	対象	分析	書き込み先	成果物
add <name>	なし	新しいスキル名	いいえ	skills/<name>/ を作成します	評価基準に合格する、登録済みのスキル
improve <path>	optimize、tighten	SKILL.md またはエージェントファイル	はい。ただし、現在の監査結果を再利用する場合を除きます	分析キャッシュ、承認後に対象	承認済みの修正と、残存する指摘事項
audit <path>	なし	SKILL.md またはエージェントファイル	はい	分析キャッシュのみ。対象は変更しません	調整済みレポート
wedge <path>	なし	SKILL.md	いいえ	対象スキル：選択した各 CLI、その配布ファイル、呼び出し箇所、および依存関係への書き込み	オフロード概要。その後、選択した候補ごとに CLI を 1 つずつ作成します。楔入れを行う場合は各 CLI を個別のディレクトリに置き、そうしない場合は理由を明示します
autoimprove <path>	experiment	スキルディレクトリ。コントラクトやマニフェストは不要です	ユーザーが承認したケース。分析データがある場合は、エージェントが作成したセッションケース	分離された実行ディレクトリ	ホールドアウトゲートの判定と、非公開の候補パッチ

audit は対象を変更しません。audit と improve の Usage セレモニーでは scripts/agent-session-analytics.pyz ingest を実行し、分析キャッシュを作成または更新します。 詳細は references/analytics-ceremony.md を参照してください。Usage を省略した場合と未加工ログへのフォールバックでは、キャッシュは書き込まれません。

autoimprove では、references/experiments.md を読みます。共通の監査プロトコルではなく、そこに記載されたワークフローに従ってください。 evals/evals.json、evals/journeys.json、または evals/autoimprove.json を読み書きする前に、references/eval-formats.md を読んでください。 ケースはエージェントが作成します。ユーザーにコントラクトやケースマニフェストを求める必要はありません。 scripts/skillz-experiment.pyz run を実行し、コード化された各停止項目に回答してから、export を実行します。 質問は最大 3 つです。ハーネスとモデル、ケースの承認、予算の承認について尋ねます。 runner、export、improvement の各主張について、ステータスと根拠を報告します。claims.apply が true の場合に限り、勝者を適用します。 ユーザーが claude アダプターまたはカスタムコマンドチェックを選択した場合は、references/experiment-harness.md も読みます。 Gemini CLI、Copilot CLI、Cursor CLI、OpenCode、または Pi の場合は、references/harness-recipes.md も読みます。 インストール済みの scripts/skillz-experiment.pyz を使用してください。ソースのチェックアウトは必要ありません。

共通プロトコル

1. 読み取りと分類

対象を読みます。実行中に記載されたトリガーに一致する場合に限り、リンク先のリファレンスを読みます。 パッケージ全体の監査では、対象パッケージ内のすべてのファイルを明示的に読み取る場合があります。 スキルディレクトリの場合、評価基準を適用する前に python3 <this-skill-directory>/scripts/skillz-experiment.pyz audit-facts <skill-directory> を実行します。 また、文章の事実を調べるために python3 -I <this-skill-directory>/scripts/inspect-skill.pyz <target> も実行します。 両方の JSON 出力は、適合性スコアではなく、客観的なパッケージ情報として扱います。エージェントファイルにはパッケージがないため、audit-facts は実行しません。 チェック ID とステータスについては、references/experiments.md § Audit facts contract を読みます。 ヘルパーでエラーが発生した場合は、監査の成功として扱わず、そのエラーを報告します。 対象を エージェント（tools: / disallowedTools:、または agents/registry.yaml のエントリー）か、スキル（name: + description:）に分類します。 スキルの場合、git ls-files -z -co --exclude-standard <skill-dir> | LC_ALL=C sort -z | xargs -0 git hash-object | git hash-object --stdin を実行します。 その出力がコンテンツ ID です。パッケージ内のすべてのファイルが対象となるため、サイドカーファイルやリファレンスを編集すると ID が変わります。 エージェントファイルの場合、git hash-object <target> を実行します。その出力がコンテンツ ID です。 コマンドが失敗した場合、コンテンツ ID は unavailable です。 本文のサイズを、5k の上限に対する ~N tok として報告します。 スキルの場合は、body.token-estimate チェックの値をそのまま使用します。エージェントファイルの場合は、フロントマターの後のバイト数を 4 で割って数えます。 定義が適用されるデプロイ先を列挙します（references/harness-layout.md § Layout）。

2. 評価基準

各評価軸を採点します。 各行には、原則、検出する失敗モード、検証可能なテストが記載されています。 指摘事項に詳細な形式が必要な場合は、references/anti-patterns.md を読みます。

観点	原則 → 防ぐ問題	確認項目
予測可能性	検証可能な完了条件を備えた固定プロトコル → «早すぎる完了»	すべてのステップが、エージェントが検証できる完了条件で終わること。
呼び出し	description = トリガー条件を冒頭に置き、三人称で記述 → «ワークフローの要約», «要約形式の説明»	トリガーとなるフレーズ + 「次の場合には使用しないでください」；内部ワークフローは含めない；スキルの長さは description.length で決まり、エージェントファイルは手作業で1024文字以下に保つ；最初の文にトリガーを含める。references/description-optimization.md。
移植性	Spec-core のフロントマターに Claude 固有フィールドを追加；すべてのホストでユーザーのみを対象とするポリシー → «Claude だけを前提とした設計», «サイドカーの欠落», «$ARGUMENTS への依存»	キー、サイドカーの組み合わせ、引数、スキルディレクトリ、またはファイル参照構文に関する audit-facts の失敗チェックを引用する。手作業で判断する：引数はスキル名の後に続くテキストから解析される；スキルは /name で相互参照される；ディスパッチと GitHub 操作では、ホスト構文より先にコントラクトを明示する。完全な一覧：references/harness-layout.md。
情報階層	一部の実行で省略される情報のみを開示する；本文は≤5kトークン；参照は1階層までとし、それぞれに読み取りトリガーを設ける → «肥大化», «トリガーのない分割», «@file による強制読み込み»	トークン予算、ネストされた参照、孤立した参照、または読み取りトリガーの欠落に関する audit-facts の失敗チェックを引用する。手作業で判断する：実行ごとにそのブロックを使うかどうかが分岐し、## References の項目にトリガーが記載されている場合に限り、移動したとみなす。references/progressive-disclosure.md。
文章（ASD-STE100）	能動態、現在形、1文につき1つの指示、短い文 → «受動態», «複数の指示を含む文», «長い文»	inspect-skill.pyz の long_sentences の情報（25語を超える文）を引用する。advisory_sentences（21〜25語）は手順のステップに限り引用する。受動態と複数の指示を含む文は指摘事項として報告する。
冒頭の言葉	事前学習済みの単語1つで、言い換えた三項目を上回る → «重複», «効果のない弱い言葉»	言い換えによる重複をまとめる；弱い言葉を強める（be thorough → relentless）。
刈り込み	信頼できる唯一の情報源；効果のない記述を削除する → «堆積»	同じ意味を複数箇所に置かない；モデルが既定で従う行を残さない。文全体を削除する。
決定論的なオフロード	固定処理は文章を再生成するのではなく、バンドルされたコマンドとして実行する → «インラインスクリプト»	解析、カウント、フィルタリング、ソート、射影を毎回モデルに記述または再導出させるステップを設けない；scripts.invocation-line は呼び出し行を対象とする；wedge.own-targets と wedge.foreign-binary はウェッジの状態を対象とする；バンドルされた各スクリプトに出力コントラクトがあるかを判断する。references/offload.md を参照して修正する。
ツールの範囲設定	読み取り専用／書き込み対象を限定／用途を絞る；利用可能な場合はホスト側の強制適用を使う → «文章だけの制約»	Claude スキルでは disallowed-tools を使って現在のターンのツールを除外する。allowed-tools はプロンプトなしで権限を付与する；拒否リストではない。Claude エージェントでは disallowedTools を使う。モードごとの実際の強制適用を報告し、文章だけの制限は劣化として示す。improve では書き込みを無効にしない。
コンテキストとフォーク	出力が約500行を超える場合、または要約のみが必要な場合はフォークする → «一枚岩の出力»	フォークが規模に合っている；まとめのシグナルがある；model-policy.* のチェックが model: + effort: を対象としている。
プロンプトの品質	肯定的な表現、何よりも理由、強力な例を1つ、「決して行わないこと」 → «否定表現への偏重», «理由のないルール»	判断を伴うタスクでは、常に／決して、ではなく足場となる枠組みを使う。references/decision-frameworks.md。
確度の調整	判断を行うエージェントは確信度 × 重大度をタグ付けする → «確度調整のない判断»	<certain> / <speculative> / <don't know>；don't know は決して表に出さない。
出力形式	要約を最初に置き、指摘事項には表を使い、問題の有無を明確に示す → «出力形式の未定義»	形式を定義する；要約と詳細を分ける。
使用状況 (audit, improve)	宣言内容と実際の使用状況を一致させる → «宣言と実際の不一致», «劣化»	宣言したツールが実際に使われている；エラー率がベースラインに近い；使用状況が低下していない。

3. キャリブレーション

各指摘に重大度 × 確信度のタグを付けます。 基準は references/calibration.md です。デフォルトは次のとおりです。

• レンズ別の重大度 — Predictability、Invocation、Portability、Tool scoping、Calibration → high；Information hierarchy、Context & fork、Pruning → high／medium；Leading words、Prose、Deterministic offload、Output format、Usage → medium。
• 確信度 — 引用した行と具体的な失敗、正しく実行できている参照例、または分析データがある → <certain>；確認可能だが未検証の観察 → <speculative>；誤読 → <don't know>、削除。
• 再導出 — 対象を読み直し、最初の確認を参照せずに各 <speculative> の指摘を一度再導出します。再現しない場合は削除します。
• 重大度の高い順に並べ、同じ重大度では <certain> を先にします。

文章チェック

add の手順 6 と improve の手順 5 でこのチェックを実行します。

1. SKILL.md またはエージェントファイルに対して、python3 -I <this-skill-directory>/scripts/inspect-skill.pyz <target file> を実行します。
2. long_sentences（25 語超）にある文をすべて書き換えます。 advisory_sentences（21〜25 語）にある文のうち、手順を示すものを書き換えます。
3. 参照ファイルを変更した場合は、両方の制限を手作業で適用します。通常は 25 語、手順の場合は 20 語です。

ヘルパーは frontmatter のないファイルを拒否するため、参照ファイルはチェックできません。

モード：add

1. 名前を確認します。kebab-case で 64 文字以下、ディレクトリ名と name: が一致し、skills/、~/.claude/skills、~/.agents/skills に重複がないことを確認します。
2. 引数から情報を収集するか、次の情報を尋ねます。1 文での目的、5 つ以上のトリガーフレーズ、アンチトリガー、呼び出しポリシー、ハーネスのセット。 呼び出しポリシーはモデルによる呼び出しか、ユーザーのみの呼び出しです。
3. references/harness-layout.md § Template に従ってスキルを作成します。 作成時点で本文を 2k tok 以下にします。 一部の実行でスキップするブロックに限り、参照を作成します。 スキルがユーザーのみの呼び出しの場合は agents/openai.yaml を追加します。 スキルがモデルによる呼び出しの場合に限り、model と effort を設定します。
4. references/harness-layout.md § Evals に従って evals/evals.json を作成します。 各トリガーフレーズに対してトリガーケースを 1 つ、各アンチトリガーに対してニアミスケースを 1 つ追加します。 目的と Flow から、少なくとも 3 つのタスクケースを作成します。 各タスクケースに、出力を評価者が確認できる assertions を設定します。
5. スキルをリポジトリのインデックスに登録します（references/harness-layout.md § Registration）。 リポジトリローカルのスキルはグローバルリストに登録せず、references/harness-layout.md § Repo-local skills に従って配置します。
6. 完了を報告する前に、SKILL.md と変更した各参照に対して文章チェックを実行します。
7. 新しいファイルに対して improve を 1 回実行します。新しいスキルにはセッションがないため、Usage はスキップします。 リポジトリにデプロイ手順がある場合は、その手順を実行します。 デプロイ手順の例として、dotfiles の同期、npx skills add、ハーネスのスキルディレクトリへのコピーがあります。

完了の条件：ファイルが存在し、リポジトリのインデックスに記載されていること。または、すべてのリポジトリローカルのホストパスが解決できること。 evals/evals.json には、各トリガーフレーズとアンチトリガーに対するケースに加え、少なくとも 3 つのタスクケースが含まれていること。 デプロイ手順がある場合、その手順が終了コード 0 で終了すること。Invocation レンズに合格すること。 インスペクターが空の long_sentences リストを報告すること。

モード：改善

1. 対象の最新の監査結果を取得します。 対象とコンテンツ ID が一致する監査レポートがこの会話内にある場合は、それを再利用します。再利用したレポート名を明記してください。 コンテンツ ID が unavailable の場合は、一致したものとして扱いません。 それ以外の場合は、監査の手順 1〜3 を実行します。Usage がない場合は、その理由を明記してください。
2. 最初の編集前に、所見ごとに推奨事項を 1 つ記載した所見表を提示します。 <certain> の所見で、重大度が medium 以上かつプロトコルの意味を変えないものには、apply を推奨してください。 Deterministic offload の所見には、offload または decline を推奨してください。offload はプロトコルの意味を変えるため、明示的な承認が必要です。 その他の所見には、それぞれ apply または decline を推奨し、その理由を説明してください。
3. 表示されたすべての所見を対象とする承認の質問を、ユーザーに 1 つだけ尋ねます。 承認された所見を適用します。承認された offload はそれぞれ references/offload.md に従って実装します。 却下された所見は残存事項として記録します。 委任された実行では、所見を親に返し、親が質問します。 PR の本文やレポートは承認として扱いません。
4. 対象の文体とプロトコルの意味を維持します。承認された項目に限り、変更します。
5. 完了を報告する前に、対象ファイルと変更した各参照ファイルで文章チェックを実行します。
6. 本文のトークン数を再計測します。変更前後のトークン数と残存所見を報告します。
7. 対象が skills/ または agents/ 以下にあり、同期によって配布される場合は、リポジトリのデプロイ手順を実行します。 デプロイ先のコピーがソースと一致することを確認してください。同名のベンダー提供スキルはローカルのスキルを上書きします（harness-layout.md § Layout）。

完了の条件：レポートで、再利用した監査または新規監査であることが明記されていること。 最初の編集前に、表示されたすべての所見をユーザーが確認できること。承認の質問で扱った各所見について、ユーザーが承認または却下すること。 承認されたすべての所見が適用されていること。 本文が 5k トークン以下であること。インスペクターの long_sentences リストが空であること。リポジトリの品質ゲートが終了コード 0 で終了すること。

モード：監査

1. 共通プロトコル §1「読み取りと分類」を実行し、target_kind を解決します。
2. 該当する target_kind で references/analytics-ceremony.md を実行します。DuckDB がない場合は、代わりに references/raw-log-fallback.md と references/harness-coverage.md を読みます。フォールバックの手順 1 では、DuckDB のインストール、サンプルを用いたスキャンの承認、Usage のスキップから 1 つを選ぶ質問をします。同意なしにスキャンを実行してはいけません。
3. Usage のダイジェストを使って、共通プロトコル §2〜3 を実行します。
4. 以下のレポートを出力します。対象は変更しないでください。アナリティクスのキャッシュ以外には何も書き込まないでください。
5. Run /skillz improve <path> to apply. で締めくくります。この会話では、コンテンツ ID が一致する間、improve はこのレポートを再利用します。

完了の条件：レポートに、表示されたすべての所見が引用行とともに記載され、基準未満の件数が明記されていること。

モード：wedge

対象スキル内の定型作業を見つけ、CLI に移します。 references/offload.md に従ってください。手順は Find、Contract、Implement、Deliver、Wire です。

1. 対象とその scripts/ を読みます。Deterministic オフロードの観点だけで評価してください。 エージェントファイルの場合は、wedge が変更するのはスキルのみであることを報告し、そこで終了します。
2. 候補ごとに Find と Contract を実行します。各候補の行を明記してください。 実行時に作業が繰り返される頻度が高い順に候補を並べ、同じ頻度の場合は対象の行番号が小さい順にします。 候補がゼロの場合は、No offload candidates と報告して終了します。
3. 以下のブリーフを出力します。 推薦候補を添えて、どの候補を実装するかユーザーに尋ねます。 同じ質問の中で、ユーザーが fromargs を拒否するか、ウェッジを拒否するかも尋ねます。 その質問には、依存関係への書き込みをそれぞれ明記します。
4. 選択された候補ごとに Implement、Deliver、Wire を実行します。 ユーザーが fromargs を拒否していない場合は、Implement の前に references/fromargs.md を読みます。 CLI をウェッジする前に references/wedge-packaging.md を読みます。
5. 対象の SKILL.md で文章チェックを実行します。その後、リポジトリの品質ゲートを実行します。
6. improve の手順 7 と同様に、同期によって対象が配布される場合は、リポジトリのデプロイ手順を実行します。 デプロイ済みのコピーがソースと一致することを確認します。

完了の条件：すべての候補に行番号が記載され、7 つの契約フィールドがすべて揃っていること。 選択された各 CLI が、その呼び出し行を通じて契約テストに合格すること。 ウェッジされていない各 CLI について、その理由が記載されていること。

## skillz wedge: <name>

| # | Step (line) | Transformation | Command | Delivery | Stays in prose |
|---|---|---|---|---|---|

### Candidate <n>: <command>
**Inputs** · **Output** · **Ordering** · **Empty** · **Errors** · **Side effects** · **Caller line**

レポート

## skillz <mode>: <name>

- Type: agent | skill · Invocation: model | user-only · Tools: <N allowed, N disallowed> · Body: ~N tok (before → after for improve)
- Harnesses reached: <list> · Findings: N surfaced, N below the bar
- Target: <path> · Content id: <id | unavailable> · Usage: included | omitted (<reason>) · Audit: fresh | reused <content id> (improve only)

| # | Severity | Confidence | Lens | Issue (line) | Fix | Recommendation (apply / decline / `/skillz wedge`) | Decision (approved / declined / pending / residual; improve only) |
|---|---|---|---|---|---|---|---|

### Detail (per surfaced finding)
**What** · **Why** (the principle) · **How** (exact section) · **Reference** (a definition that does it right)

### Recommended hooks
Only for a rule that must hold every time; pick from `references/hooks-catalog.md`. Omit when none.

### Below the bar
N findings were `<don't know>` or trivial (not shown).

このスキルが決して行わないこと

• audit は対象を変更せず、分析キャッシュのみを書き込みます。
• wedge が書き込むのは、ユーザーが選択した候補のみです。
• improve はユーザーが承認の質問に回答する前に編集することはなく、承認なしにプロトコルの意味を変更することもありません。
• add は、説明が Invocation の観点に合格しないスキルを登録しません。
• <don't know> を表に出すことはありません。
• 自分自身を例外扱いすることはありません。skillz に対する指摘も、ほかの指摘と同様に記録されます。

注意点

• シンプルなスキルに対する一般的な指摘：すべての指摘で、行番号または名前付きパターンを明記します。
• ホストのデフォルト設定ですでにツールリストが制限されている場合に、disallowedTools がないことを過度に重視すること。
• 時間が足りないときに最初に省かれ、最も多くの誤検出を見つける手順が、<speculative> の再導出です。
• disable-model-invocation だけでは、Codex による自動呼び出しを防げません。解決策はサイドカーであり、説明文を増やすことではありません。
• フックは常に守る必要があるルールのためのものであり、すべての指摘に使うものではありません。

参照資料

必要に応じて読みます。

• references/harness-layout.md — 移植性の観点が発火した場合、または add（グローバルまたはリポジトリローカル）の場合に読みます。フロントマターのマトリクス、ルール、テンプレート、評価、サイドカー、ソースについて説明しています。
• references/analytics-ceremony.md — audit の場合、または再利用可能な監査がない状態での improve の場合に読みます。scripts/agent-session-analytics.pyz を使って、パックごとのベストエフォートの分析を実行します。
• references/raw-log-fallback.md — DuckDB がない場合に読みます。ユーザーは DuckDB をインストールするか、サンプリングされた読み取り専用の Usage スキャンを選択するか、スキップします。
• references/anti-patterns.md — 発見事項について、失敗モードの詳細な説明が必要な場合に読みます。
• references/offload.md — wedge を実行する場合、または improve で承認済みのオフロードを実装する場合に読みます。共通の手順を説明しています。
• references/fromargs.md — オフロードによって fromargs CLI を作成する場合に読みます。
• references/wedge-packaging.md — オフロードによって CLI をウェッジ化する前に読みます。ビルダーは scripts/wedge.pyz です。
• assets/records.py、assets/wedge.toml — オフロードでコピーする CLI とマニフェストのテンプレートです。
• evals/evals.json — 負荷シナリオです。オフロードの手順を変更するときに使用します。
• references/progressive-disclosure.md — 情報階層の観点が発火した場合に読みます。
• references/description-optimization.md — 呼び出しの観点が発火した場合に読みます。
• references/decision-frameworks.md — プロンプト品質の確認で、判断を要するタスクに硬直的なルールが見つかった場合に読みます。
• references/hooks-catalog.md — 発見事項について常時適用の強制が必要な場合、または呼び出しの観点で強制評価フックが推奨された場合（§1）に読みます。
• references/skill-usage.md、references/agent-orchestration.md、references/drift-regression.md — 分析パックです。分析の手順では、各パックのパスと対象の種類をパックのコンテキストに渡します。ホストにサブエージェントがない場合に限り、パックを読みます。
• scripts/agent-session-analytics.pyz — 分析 CLI です。ingest、db-path、sql、schema を使用します。
• references/canonical-schema.md — パック入力の schema です。パック用 SQL を作成または確認するときに読みます。
• references/query-conventions.md — パック入力の conventions です。パックを作成するとき、またはそのクエリを実行するときに読みます。
• references/harness-coverage.md — パック入力の coverage です。ハーネス間の比較を行う前と、raw-log フォールバックを使用するときに読みます。
• 分析の手順では、これら3つのパスを schema、conventions、coverage として各パックのコンテキストに渡します。
• references/calibration.md — 発見事項の重大度と確信度をタグ付けするときに読みます。確信度 × 重大度のカーネルについて説明しています。
• references/experiments.md — autoimprove の場合、またはチェック ID が必要な audit の場合に読みます。実行フロー、ケースのドラフト、ゲート判定、エクスポート、任意のコントラクト、採点器、分離、ヘルパーのコントラクトについて説明しています。
• references/eval-formats.md — 作成者が書く評価ファイルについて説明しています。フィールド、スキーマ、$schema、最小要件、validate が含まれます。
• references/experiment-harness.md — ユーザーが claude アダプターを選択する場合、またはカスタムコマンドやロールファイルを確認する場合に読みます。
• references/harness-recipes.md — ユーザーが Gemini CLI、Copilot CLI、Cursor CLI、OpenCode、Pi を使って実験を実行する場合に読みます。