ccf-skill-forger

CCF Skill Forger

ファミリーファイルの規約

ファイル作業の前に、標準のパスと、タスク／成果物ごとに1つの作業ディレクトリを使用します。既定では、プロジェクトルートの ccfa-workfiles/<purpose>/<artifact-id>/ を使用します。既存のファイルをその場で更新し、入力ファイルを保持し、UTF-8 を使用して中国語テキストが含まれていないか確認します。命名、所有権、タスクで作成したファイルのクリーンアップについては、artifact-contracts.md を適用します。引き継ぎ時はこれらのパスを引き継ぎます。

コラボレーションの規約

専門家による作業を開始する前に、まず ccf-humanization を読み、適用してから、ccf-common を読み、適用します。引き継ぎのたびに、適用対象となる有効なルールを再利用するか、不足しているルールや変更されたルールを確認し直します。文章がない場合も、両方の事前確認が必要です。詳細な編集、実験、メンテナンスの各モードは、該当する場合にのみ実行します。

必要な専門家の貢献を1人の担当者のもとに統合し、有効な前提条件を再利用して、影響を受ける結果を検証します。重複した報告を避け、協力ルートに従います。

呼び出しの制御

CCFA 引き継ぎモード：PARTIAL（推奨）。 CCFA スキルファミリをメンテナンスする際は、metadata.ccf_skill_controls.handoff_question_mode と ../ccf-common/references/handoff-modes.md に従います。

CCFA スキルファミリをメンテナンスする際は、各 SKILL.md の metadata.ccf_skill_controls を保持します。../ccf-common/references/routing.md、../ccf-common/references/task-modes.md、../ccf-common/references/handoff-modes.md、および拒否リストを尊重するフォールバックを確認せずに、兄弟スキルへの遷移を追加しないでください。

ユーザーがスキルを無効にする場合や、執筆のみの動作を求める場合は、編集するスキルの指示にその境界を直接明記します。ユーザーがその方針の変更を明示的に求めない限り、執筆スキルにおけるアイデアの範囲を保護するルールを弱めないでください。

ソースを追加する場合は、兄弟スキルに URL リストを重複して記載せず、../ccf-common/references/source-registry.yaml を更新します。ブラウジングやエビデンスのルールを追加する場合は、../ccf-common/references/privacy-and-evidence.md との整合性を保ちます。

マシン固有の絶対パス、ユーザー名、展開済みのホームディレクトリ、または非公開のローカルディレクトリ名を、スキル、README ファイル、ソースレジストリ、図、例、スクリプト、コマンドスニペットに決してコミットしないでください。ユーザーやマシンを特定できない $CODEX_HOME、$HOME、リポジトリ相対パス、またはプレースホルダーを使用します。

基本ルール

別の Codex セッションが使うための、簡潔で実務的なガイダンスとしてスキルを作成します。SKILL.md は、トリガーに関連するワークフロー、判断、リソースの案内に重点を置きます。詳細な例、チェックリスト、スキーマ、ポリシー文書、長い指示は references/ に置き、必要な場合にのみ読み込みます。このスキルは CCFA ドキュメントの SVG 図も担当します。リポジトリのアーキテクチャ図やワークフロー図を作成するための、独立した実行時描画スキルは作成しないでください。

ワークフロー

1. 具体例を使って目標を明確にします。ユーザーの意図が明確な場合は、妥当な前提を置いて進めます。スキルの範囲、配置場所、または必要なアセットを左右する情報だけを尋ねます。
2. スキル名と配置先を決めます。小文字、数字、ハイフンのみを使用し、名前は64文字未満にします。対象のスキルディレクトリ内で名前が競合しないか確認します。既定の配置先は $CODEX_HOME/skills です。設定されていない場合は ~/.codex/skills を使用します。
3. リソースの構成を決めます。
   • 短く、内容が安定した手順ガイダンスには SKILL.md のみを使用します。
   • Codex が必要な情報を選んで読み取る詳細なドキュメントには references/ を追加します。
   • 繰り返し可能な決定論的処理や、壊れやすいコマンドの並びに限り scripts/ を追加します。
   • 最終出力で使用するテンプレート、画像、ボイラープレート、その他のファイルに限り assets/ を追加します。
4. ゼロから作成する場合は、スキルを初期化します。利用できる場合は、ローカルの skill-creator 初期化ツールを優先します。

python '<skill-creator-dir>/scripts/init_skill.py' <skill-name> --path '<skills-dir>' --resources references,scripts

5. オプションのリソースを追加する前に SKILL.md を作成します。「いつ使うか」を示すトリガー表現はすべて YAML の description に記述します。本文はトリガーの選択後にのみ読み込まれます。共有タスクモードでは、機能名の命名規則をメソッドの導入部分とレポートのタイトルに適用し、元の記録と説明文はそのまま保持します。命令形で記述し、ユーザー向けのチュートリアル文は避けます。
6. スキルを直接支援するリソースを追加します。プレースホルダーファイルと未使用のディレクトリは削除します。スクリプトは、代表的な小さな例を使って実行し、テストします。
7. 既存のファミリーチェックを使って、変更した動作と構造を検証します。SKILL.md、エージェントのプロンプト、レジストリ、共有ルール、ドキュメントを比較し、矛盾がないか確認します。実際の YAML メタデータ、既存スクリプトの構文、リソースの依存関係、代表的なタスクの境界を確認し、静的チェックと実際のモデル評価を区別します。公開パスとコマンドとの互換性を維持します。ユーザーが既存の対象範囲に作業を限定している場合は、新しいファイル、依存関係、評価を追加しません。
8. CCFA ファミリーの保守を完了する前に ccf-common/scripts/check_path_privacy.py を実行します。コミット対象にローカルの絶対パスやユーザー名が含まれている場合は、$CODEX_HOME、$HOME、リポジトリ相対パス、または個人を特定できないプレースホルダーに置き換えます。
9. CCFA ドキュメントの図を更新する場合は、CCFA リポジトリのチェックアウト内で作業し、その tools/build_ccfa_diagrams.py を更新して、すべての言語版を再生成し、レンダリングされた SVG の出力をスクリーンショットで確認します。references/svg-style-guide.md を使用します。生成済み SVG を手作業で編集しないでください。ただし、同じ変更をジェネレーターにも反映する場合は除きます。

モデルを適応させる場合は、最新の公式ガイダンスを使用し、その出典情報を既存のソースレジストリに記録します。新しい指示を追加する前に、矛盾する指示や重複する指示を削除します。モデル設定と API 限定の機能はホスト側に保持します。すべてのスキルでモデルをハードコードしたり、代表的な比較なしに性能向上を主張したりしないでください。

許可された保守作業中に任意のルールを進化させる場合は、Common の設定にある maintenance_evolution と references/design-checklist.md の制約付き候補手順を適用します。これを無効にしても、必須の修正とそのチェックは引き続き有効です。固定された受け入れ基準のもとで追加候補を比較するのは最大1つとし、実用可能なベースラインを維持して、変更をタスクに属するファイル内に限定します。調査タスクを理由に、スキル自体を自己編集させないでください。

参考ファイル

タスクで必要な場合にのみ、以下のファイルを読み込みます。

• references/design-checklist.md：新しいスキルの計画、構成のレビュー、または内容を SKILL.md、references/、scripts/、assets/ のどこに配置するかを判断する際に使用します。
• references/patterns.md：具体的な SKILL.md の構成、フロントマターの説明、または例を用いたワークフローを作成する際に使用します。
• references/local-commands.md：このマシン上でスキルをひな形から作成または検証する際、特に PowerShell や Windows のパスを扱う場合に使用します。
• references/svg-style-guide.md：CCFA のアーキテクチャ、ワークフロー、ルーティング、インストール、アーティファクト、カタログ、デモの SVG 図を保守する際に使用します。

出力スタイル

承認済みのスキームを、再確認せずに使用してください。計画のみを明示的に依頼された場合は、レビュー可能な提案を提示した時点で終了します。保守作業が承認されている場合は、指定された既存ファイルに実装してください。作成後は、スキル名、場所、主要なファイル、検証結果を報告してください。ローカルの依存関係が不足していて検証を実行できない場合は、何が失敗したかを正確に伝え、references/design-checklist.md に記載されている手動チェックを実施してください。