new-skill

スキル：new-skill

スキルの追加では、4 つの場所に手を加えます。正本の skills/<name>/SKILL.md、そのミラーである llmwiki/skills/<loop>/<name>.md、sync-skills.py の LOOP_MAP、marketplace.json の公開リスト、そして AGENT.md/CLAUDE.md の ## Skills テーブルの行です。どれか 1 つでも見落とすと、各ツリーにずれが生じます（これが marketplace.json が約 30 個のスキル分遅れた原因です）。このスキルは fdk/tools/new-skill.py を実行し、機械的に生成される 2 つのファイルを同一内容で作成するとともに、curated な 3 つの場所に追加する正確な行を出力します。これらの場所自体は編集しません。

内容

目的とコンテキスト

• 目的： 2 つの公開ツリー（正本 + ミラー）に、新しいスキルを solid-what-how/1 の枠組みで同時に作成します（バイト単位で同一）。その後、curated な各サーフェスに登録するために貼り付ける正確な行を提示します。
• トリガー（使用するタイミング）：
• ユーザーが新しいスキルの作成／追加／ひな形の生成を依頼した場合、または /new-skill を実行した場合。
• skills/<name>/SKILL.md を手作業で作成しようとしていて、ミラーやレジストリの各サーフェスを忘れそうな場合。

職人らしいスキルを書くには、まず [[skill-craft]] を読んでください。 スキルが予測可能になるための語彙を確認します。2 種類のコスト（コンテキスト読み込み ↔ 認知負荷。手動でのみ呼び出すスキルは disable-model-invocation: true を設定して、コンテキストを節約します）、各ステップの完了条件、3 つの質問を置き換える先頭の語句、そして避けるべき 5 つの失敗モード（duplication/sediment/sprawl/no-op/negation）です。/lint のステップ 8b では、これらを機械的に測定します。

• 対象外： LOOP_MAP / marketplace.json / AGENT.md / CLAUDE.md を自動で修正しません。既存のスキルを移行しません（その場で編集します）。upstream から取り込むスキルは作成しません（その場合は skills/external/ に追加します）。

メンタルモデル

名前 + loop + description（トリガー）→ new-skill.py → skills/<名前>/SKILL.md（WHAT/HOW の枠組み）+ llmwiki/skills/<loop>/<name>.md → TODO を埋める → swh-lint → sync-skills → curated な 3 つのサーフェスに登録 → sync-skills --check + skill-registry --check。

入力と出力の契約

	Field	Required?	意味
In	<name>	はい	kebab-case で、skills/ にまだ存在しない名前
In	--loop	はい	dev-loop · orchestrate · wiki-loop · utils
In	--desc	はい	トリガーフレーズを豊富に含む 1 行（ルーターはこれに基づいて一致を判定します）
Out	skills/<name>/SKILL.md + mirror	はい	SWH の枠組みが完成し、TODO がすべて埋まった同一内容の 2 ファイル
Out	curated な 3 つのサーフェスへの登録	はい	最後の 2 つのチェックコマンドが両方とも成功すること

ルールと機能

• RULE-01（必須）：ツールが書き込むのは、機械的に生成する 2 つのファイル（正本 + ミラー）だけです。LOOP_MAP、marketplace.json、AGENT.md、CLAUDE.md は編集しません。これらはユーザーが curated するものなので、出力された行を手作業で追加してください。
• RULE-02（必須）：生成されたひな形を編集した後は、必ず sync-skills.py を再実行してください。パリティが強制されているため、編集によってミラーが古くなります。
• RULE-03（必須）：曖昧な --desc ではスキルが呼び出されません。具体的なトリガーフレーズと / コマンドを含めてください。
• RULE-04（必須）：既存のスキルを上書きしてはいけません。名前が使用済みの場合は、skills/<name>/SKILL.md をその場で編集するか、別の名前を選んでください。
• 機能：2 つのスキルファイルを作成します。既存のスキル索引（BM25）を読み取り、重複の可能性を警告します。curated なサーフェスは人が手作業で追加します。

失敗時の境界

• 名前がすでに存在する → ブロック（ツールが拒否します）。その場で編集するか、名前を変更してください。
• BM25 のしきい値を超える能力の重複 → 警告します。--strict を指定した場合は ブロック されます。
• swh-lint または最後の 2 つのチェックが失敗した場合 → 未完了です。修正して再実行してください。

手順

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	ユーザーの要求	<name>、--loop、トリガーフレーズを豊富に含む--descを確定	3つの入力	曖昧 → 質問
W02	effect	3つの入力	new-skill.py --dry-runを実行（合致するカタログ例を表示）してから本実行 — 合致する例があれば--from <asset_id> --params p.json	2ファイル + レシピreuse_decision	名前が重複 → blocked · パラメーターが不正 → INVALID_PARAMETER
W03	judgment	骨組み	WHAT/HOWのすべてのTODOを埋め、swh-lintを実行	構造を満たしたスキル	エラー → 修正してW03を繰り返す
W04	effect	スキル	sync-skills.pyで完全に一致するミラーを作成	完全一致するミラー	—
W05	effect	出力されたツールの行	LOOP_MAP、マーケットプレイス、AGENT/CLAUDEの一覧に登録	3つの掲載箇所	—
W06	deterministic	リポジトリ	sync-skills.py --check + skill-registry.py --check	両方とも成功	エラー → 不一致の掲載箇所を修正

各ステップの詳細（W01–W06の信頼できる情報源）：

1. 3つの入力を確定します。kebab-caseの<name>、--loop（dev-loop | orchestrate | wiki-loop | utils）、そしてトリガーフレーズを豊富に含む--desc（説明文はスキルルーターが照合する対象です）。手動呼び出し専用のスキル（ユーザーが入力して呼び出し、ほかのスキルからは呼び出されない）の場合は、disable-model-invocation: trueを追加し、--descを読者向けの1行に短縮します（[[skill-craft]]を参照）。
2. まずプレビューしてから作成します：

   python3 fdk/tools/new-skill.py <name> --loop <loop> --desc "<description>" --dry-run   # preview body + next steps
   python3 fdk/tools/new-skill.py <name> --loop <loop> --desc "<description>"             # write both files
   

   skills/<name>/がすでに存在する場合は処理を拒否します。
3. 生成されたskills/<name>/SKILL.mdに内容を記入します。骨組みは簡潔なsolid-what-how/1テンプレートです（## WHATには目的／契約／ルール／失敗時の対応、## HOWにはメインワークフローの表／分岐／例が含まれます。[[solid-what-how]]を参照）。すべてのTODOを、実際に検証可能な内容に置き換えてから、構成を確認します：

   python3 fdk/tools/swh-lint.py --skills <name> --ci
   

4. 編集後に再度ミラーを作成し、llmwikiのコピーをバイト単位で一致させます：

   python3 harness/scripts/sync-skills.py
   

5. ツールが出力した行をそのまま貼り付け、指定された掲載箇所に登録します。harness/scripts/sync-skills.pyにLOOP_MAPのエントリを追加し、（任意で）.claude-plugin/marketplace.jsonに./skills/<name>の行を追加し、llmwiki/AGENT.mdとllmwiki/CLAUDE.mdの両方にある## Skillsの表に1行追加します。
6. すべての掲載箇所が一致することを確認します。両方とも成功する必要があります：

   python3 harness/scripts/sync-skills.py --check        # mirror parity
   python3 harness/scripts/skill-registry.py --check      # cross-surface drift
   

分岐

ID	Kind	Guard	動作	Skip / failure	Rejoin
B01	conditional_required	手動呼び出し専用のスキル	disable-model-invocation: trueを追加し、--descを読者向けの1行に短縮	モデルから呼び出されるスキル → スキップ	W02
B03	user_optional	コントラクトに合致するテンプレートがカタログにある（先にeffectで絞り込み、その後に順位付け）	--fromで型付きテンプレートをレンダリングし、sha256をfdk/skill-catalog/recipes/<name>.recipe.jsonに固定します。合致しない場合は--reasonを付けてスクラッチから作成	カタログを読み込めない → decision catalog_unavailable。簡潔な骨組みを引き続き生成	W03
B02	recovery	BM25で能力の重複が報告された	バリエーション名に変更して説明を差別化するか、既存のスキルを修正	--strict → 停止	W01

検証と停止条件

実行のたびにreuse_decision（reuse · scratch · catalog_unavailable）が記録されます — Reuse Layer SWH v1.1、カタログfdk/skill-catalog/、ツールfdk/tools/skill-reuse.py。再利用しても検証を省略することはできません。テンプレートから生成したスキルも、swh-lintに合格する必要があります。 swh-lint --skills <name> --ci、sync-skills.py --check、skill-registry.py --checkがすべてrc 0になれば完了です。実際の動作（スキルが正しく呼び出されるか）は、例文を1～2個使って試してください。lintでは検証できません。

例

• 成功例： new-skill.py csv-preview --loop utils --desc "CSVをプレビュー… Trigger: 'preview csv'" → 2つの骨組みファイルを生成し、WHAT/HOWを記入して、3つのチェックすべてに合格します。
• 境界条件／失敗例： new-skill.py ship … → skills/ship/がすでに存在するため、ツールが拒否します。既存のskills/ship/SKILL.mdをその場で修正します。