skill trigger declaration in description - Liplus-Project/liplus-language GitHub Wiki

skill の発火条件は description 内に置く — when_to_use は移植性で却下

Question

skill の発火条件（いつ invoke されるべきか）の記述形式を統一するとき、Claude Code 独自フィールド when_to_use に分離すべきか、description 内に留めるべきか。

Current resolution

description 内に留める。書き出しを固定形に揃えることで統一する（案 A）。

理由は三つ、いずれも Agent Skills オープン標準（agentskills.io/specification、2026-07-28 一次ソース確認）に基づく。

  1. when_to_use は標準に存在しない。 Claude Code 独自拡張。Li+ は Claude / Codex 両アダプタを持つため、片側でしか効かない形式は「統一」にならない。
  2. 標準の作法は「description に what と when を両方書く」。 標準の description 定義は "Should describe both what the skill does and when to use it" であり、Li+ の現状はすでに標準どおり。分離するほうが標準から離れる。
  3. 字数は減らない。 Claude Code の listing 切り詰めは description + when_to_use の合算 1,536 字に対して働くため、フィールドを分けても listing 圧は変わらない。

段階的な逃げ道（現時点では未着手）:

  • 固定形の正規表現照合で発火数の機械カウントが不足する場合 → 標準が「クライアント独自プロパティの置き場」と明記する metadata: に構造化して置く（案 B）。description との二重管理になるため CI 整合チェックとセット。
  • when_to_use の採用（案 C）は、Codex 側が当該フィールドをどう扱うかの実機確認が取れた後でのみ再評価する。

Edges

  • supersede / conflict edge なし。
  • 隣接: li-plus-always-on-footprint-load-bearing — always-on footprint を rules + adapter CLAUDE.md + output-style（実測 ~21,500 tok）で測り「安全な圧縮余地は枯渇」と結論している。本 entry は同 entry が測っていない第4の always-on 面を追加する: skill listing（description 合計 10,224 字 / 38本）。listing 予算はコンテキスト窓の 1% で、溢れると呼び出し頻度の低い skill の description から黙って落とされる（Claude Code 仕様）。圧縮判断そのものは同 entry の結論を変えない（本 entry は形式の話であり削減の話ではない）が、skill 本数が増える変更は listing 圧を上げるという副作用軸を新設する。
  • depends on（外部前提）: Agent Skills オープン標準が when_to_use を採用しないこと。標準側が将来これを取り込めば案 C は再評価対象。

Background

Master「スキルの条件式は公式に合わせて統一化したい」。Li+ の skill description は発火条件を Invoke when X / Invoke for A / B / C / Invoke immediately after X と各ファイルが別々の文法で書いており、発火数の機械的カウントも skill 間の発火重複検出もできない状態だった。

この形式非固定は実害を出している: 同日の対話で親 AI が when|whenever|before|after のみを拾う正規表現で発火数を計測し、Invoke for A / B / C 形と「1個の when が3項目を束ねる」形を取りこぼして、存在しない分類（単発火・長手続き型）を立てて Master に報告した。Master の指摘で発覚。

Constraints

Agent Skills オープン標準（一次ソース確認済、2026-07-28）:

field 要否 制約
name 必須 64字以内、小文字英数とハイフン、親ディレクトリ名と一致
description 必須 最大 1024 字。what と when の両方。照合キーワードを含める
license / compatibility / metadata / allowed-tools 任意 compatibility は 500 字以内。metadata は標準外プロパティの公式な置き場

本文の推奨 = 5,000 トークン未満 / 500 行以内。

Li+ 側の実測（2026-07-28、全38本）:

  • description > 1024 字 = 0本（最長 860）
  • 500 行超 = 0本
  • 本体 > 5,000 tok = 3本（evolution-parallel-agent-eval 6,172 / model-agentic-search 5,659 / operations-on-release 5,329）

Claude Code 拡張（標準外）: when_to_use フィールド、description + when_to_use 合算 1,536 字で listing 切り詰め、listing 予算 = 窓の 1%（skillListingBudgetFraction / SLASH_COMMAND_TOOL_CHAR_BUDGET / skillListingMaxDescChars で調整可）。

Conclusion

  • 採用: 案 A — description 内の発火条件記述を固定形に揃える。追加機構ゼロ、標準準拠、両アダプタで等価に効く。
  • 却下（保留）: 案 B（metadata: 構造化）— 標準準拠だが description との二重管理と CI 整合チェックを要する。案 A で機械カウントが不足した場合の次手。
  • 却下（条件付き保留）: 案 C（when_to_use）— 標準外につき Codex 側の挙動が未確認。確認が取れるまで採用しない。

Related