article-prompts-to-skills

記事のプロンプトからスキルへ

元となるプロンプトを、小規模で実証可能な機能パッケージに変換します。元ページのブランドやレイアウトではなく、役立つ動作を維持してください。

1. 抽出する前に確認する

1. リポジトリの指示と、元記事の全文を読みます。
2. git status --short を実行し、無関係な変更を保持します。
3. 明示されたプロンプト、見出し、例、アセット、受け入れ基準をすべて一覧にします。
4. フォルダーを作成する前に、既存の SKILL.md ファイルを検索し、機能の重複がないか確認します。
5. 元データが生の HTML で、プロンプトがまだ存在しない場合は、先に $html-to-interaction-prompts を使ってから、ここに戻ります。

タイトルだけからスキル群を推測しないでください。提案する各スキルを、元データの根拠に結び付けてください。

2. 抽出台帳を作成する

ファイルを編集する前に、作業用の表を作成します。

元のプロンプト	再利用可能な機能	残す内容	削除する内容	スキル名	デモによる証明

次の基準を適用します。

• 独立して再利用できる動作ごとに、スキルを1つ作成します。
• 分割するとどちらかの手順が使えなくなる場合に限り、手順を統合します。
• 既存のスキルの仕様がその機能をすでに網羅している場合は、既存のスキルを更新します。
• 再現可能な手法を生み出さない装飾的または編集上の断片は除外します。
• スキル名には、元記事ではなく、得られる成果または仕組みを使います。

3. 移植可能な仕様を抽出する

元データでうまく機能している仕組みを維持します。

• 動作と状態遷移。
• データモデルとパラメーターのデフォルト値。
• タイミング、イージング、間隔、レスポンシブルール。
• アクセシビリティ、動きを抑える設定、キーボード操作。
• パフォーマンスの制約と失敗時の動作。
• 結果を検証する受け入れチェック。

元データ固有のパッケージングは削除します。

• ブランド名、マーケティング文、独自コンテンツ。
• 機能と無関係なページレイアウト。
• 固定の配色、アセット、セレクター。
• 結果に影響しない、付随的な実装上の選択。

中核の指示を書き換えなくても、異なる題材、レイアウト、ビジュアルシステムに適用できるものにします。

4. 各スキルをパッケージ化する

新しいフォルダーはすべて、インストール済みの skill-creator イニシャライザーで初期化してから、次の仕様を満たしてください。

agent-skills/<category>/<skill-name>/
  SKILL.md
  agents/openai.yaml
  references/          # only when detailed reusable guidance is needed
  assets/ or scripts/  # only when the workflow genuinely reuses them
  demo/
    index.html
    PROMPT.md
    preview.jpg
    input.md            # required for workflow skills
    expected-output.md  # required for workflow skills

SKILL.md は命令形で記述します。フロントマターには name と description だけを記載します。トリガーフレーズはすべて説明文に含めます。実行手順、制約、注意点、検証コマンドは本文に記載します。

最終的なスキルに基づいて agents/openai.yaml を作成します。

• 人が読みやすい表示名を使います。
• 短い説明は25〜64文字にします。
• デフォルトのプロンプトで $skill-name を明示的に呼び出します。

5. 役立つ例示プロンプトを3つ作成する

demo/PROMPT.md に次の見出しを記載します。

最小限のプロンプト

スキルを呼び出し、明確な成果を1つ求めます。

Use $skill-name to add <capability> to <target>.

デモの再現

参照する体験、実装仕様、成果物、受け入れチェックを説明します。ローカルで完結し、自己完結型であるべき要素を明記します。

リミックス用プロンプト

仕組み、アクセシビリティ動作、レスポンシブルール、パフォーマンス仕様を維持しつつ、題材、コンテンツ、配色、構成を変更します。

ビジュアル、複数ソース、ワークフローの例については、references/example-packages.md を参照してください。

6. 装飾ではなく、動作の証拠を作る

すべてのデモを独自性があり、自己完結していて、検証可能なものにします。

• 最初の画面で中核となる仕組みを示します。
• 「デモカード」のようなラベルではなく、現実的なコンテンツを使います。
• 意味のある状態を見せる場合にのみ、コントロールを追加します。
• 390pxから1440pxまでのレイアウトに対応します。
• セマンティック HTML と、視認できるフォーカス状態を使用します。
• アニメーションを含む場合は、動きを抑える設定に対応します。
• 依存関係はローカルに保ち、スキルに必要な場合を除いてビルド手順を設けません。
• 視覚以外のワークフローでは input.md と expected-output.md を使います。

スクリーンショットを実装の代わりとして扱わないでください。HTML デモが実際に動作する必要があります。

7. パッケージ全体を検証する

成果物に応じて、適切な範囲で検証します。

1. 新規または変更したすべてのスキルに対して、スキル作成者の quick_validate.py を実行します。
2. リポジトリのデモ検証と、対象を絞った構文チェックを実行します。
3. 許可されたブラウザーで各デモを開き、デスクトップとモバイルのサイズで確認します。
4. 主な操作、キーボードフォーカス、モーション軽減時の動作を試します。
5. コンソールにエラーがないことを確認します。
6. リポジトリで共有されているサイズで、実際のブラウザープレビューを取得します。
7. デモとギャラリーのスクリーンショットを再生成し、もう一度検証します。
8. 変更したファイルをスキャンして、シークレット、トークン、プライベートなパス、クライアントの非公開データが含まれていないか確認します。

静的なファイルの確認だけで、視覚的な検証やインタラクションの検証を行ったと主張してはいけません。

8. タスクに関係するものだけをコミットする

新しいスキルのフォルダーと、それらに必要なギャラリーファイルだけをステージングします。コミット前に git diff --cached --stat と git diff --cached を確認します。既存の未コミットファイルには手を加えないでください。

次の内容を報告します。

• ソースとスキルの対応関係。
• サンプルプロンプトとデモのパス。
• 検証結果とブラウザーでの確認内容。
• コミットハッシュ。
• コミット対象外として残る、無関係な変更済みファイル。

失敗につながるパターン

• ページの複製： 仕組みを抽出するのではなく、ソースのレイアウトをコピーする。
• 巨大なスキル： 独立したプロンプトを、曖昧なひとつのスキルにまとめる。
• 細分化しすぎた断片： 再利用可能な動作を持たないまま、すべての文をスキルにする。
• テーマの固定： ソースの配色、アセット、文言をハードコードする。
• プロンプトだけのパッケージ： 動作するデモやプレビューを含めない。
• 検証したふり： 実際に試さずにインタラクションを検証したと主張する。
• 作業ツリーの混入： 無関係な変更や生成ファイルをステージングする。