mcpField
S
skills-creation

skills-creation

github.com/editframeエージェントワークフロー1969 回インストール2 週間前に更新
リポジトリ

skills-creation について

Editframe の一元管理された skills システムで、スキルの作成、更新、検証、同期を行うためのエージェント向けガイドです。内容の陳腐化を避ける方法も含む、構造化された執筆手順を示します。

主な機能

  1. 01要件の収集とスキル構成の計画
  2. 02スキルファイルの作成と更新
  3. 03構成と frontmatter の検証
  4. 04古くなりやすい内容の確認
  5. 05複数のエージェント用ディレクトリ間で同期

活用シーン

  1. 01要件に基づく新しいエージェントスキルの作成
  2. 02既存スキルの改訂と品質確認
  3. 03スキルのメタデータとファイル構成の検証
  4. 04複数のエージェント用ディレクトリへの変更同期

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/editframe/skills --skill skills-creation

インストール後、Claude Code で/skills-creationを入力して読み込まれたか確認します。

詳細

スキルの作成とメンテナンス

Editframe の一元管理型スキルシステムでスキルを作成・更新するためのエージェントガイドです。

概要

スキルはエージェントの能力の基盤です。このスキルでは、次の指針を示します。

  • 新しいスキルを作成する：ユーザーの案内を受けながらゼロから作成します
  • 既存のスキルを更新する：検証を行いながら更新します
  • スキルの品質を維持する：構造化された執筆を通じて維持します
  • スキルを同期する：変更後にエージェントのディレクトリ間で同期します

クイックスタート：新しいスキルの作成

  1. ユーザーに尋ねます：作成したいスキルを確認します
  2. 要件を収集します：目的、機能、ユースケースを確認します
  3. スキルの構造を作成します：.skills/internal/{skill-name}/ 内に作成します
  4. コンテンツを記述します：SKILL.md と、必要に応じて references/ を作成します
  5. 検証します：構造とフロントマターを確認します
  6. 変更を同期します：エージェントのディレクトリ間で同期します
  7. コミットします：git にコミットします

エージェントのワークフローに関する指針

フェーズ 1：要件の確認

ユーザーから新しいスキルの作成またはスキルの更新を依頼された場合：

  1. 確認の質問をします：

    • 「このスキルの主な目的は何ですか？」
    • 「誰がこのスキルを使いますか（どのエージェント／ユーザーですか）？」
    • 「主な機能やトピックは何ですか？」
    • 「既存のスキルを更新しますか、それとも新しく作成しますか？」

  2. 要件を記録します：

    • スキル名（kebab-case：my-skill-name）
    • 説明（LLM 向けの一文）
    • 扱う主なセクション／トピック
    • ユースケースの例
フェーズ 2：構造の計画

執筆を始める前に、スキルの構造を計画します。

  1. スキルの種類を決定します：

    • リファレンススキル：既存のシステム／API を文書化します（最も一般的）
    • チュートリアルスキル：例を交えながら、段階的に学べるようにします
    • ハウツースキル：特定のタスクの進め方を示します
    • 解説スキル：概念を深く理解できるようにします

  2. 計画したコンテンツを分類します：

    執筆を始める前に、含める予定の各セクションを分類します。

    • 手順的な内容 — 何かを行う方法（デプロイ、ロールバック、リリースの作成など）。安定しています。散文で記述します。
    • アーキテクチャに関する内容 — システムが大まかにどのように動くか（何が何につながるか、なぜそのような構造なのか）。比較的安定しています。簡潔な説明文で記述し、具体的な項目の列挙は避けます。
    • 列挙データ — 項目のリスト、値の表、数、名前、バージョン（サービスのリスト、リソースの割り当て、パッケージ名、シークレット名、ルートテーブルなど）。変わりやすいため、スキルには記載しないでください。 代わりに、エージェントが参照するソースファイルを示すか、値を照会する補助スクリプトを作成します（下記の「補助スクリプト」を参照）。

    目標は、設定ファイルが変更されてもスキル文書の更新が不要な状態にすることです。スキルはエージェントにドメインについての 推論方法 を教え、スクリプトとソースファイルが 最新の事実 を提供します。

  3. ファイル構成を計画します：

    .skills/internal/{skill-name}/
└── SKILL.md                    # Main entry point (required)

    または、詳細な構成の場合：

    .skills/internal/{skill-name}/
├── SKILL.md                    # Overview + quick start
└── references/
    ├── topic-1.md              # Deep dive on topic 1
    ├── topic-2.md              # Deep dive on topic 2
    └── topic-3.md              # Examples/guides

  4. クイックリファレンスのテンプレート：

    • SKILL.md：スキルを紹介する 200～400 語の文書
    • 各リファレンス：1 つのトピックを扱う 400～800 語の文書
    • LLM が理解しやすい明確さを重視します
フェーズ 3：コンテンツの作成

SKILL.md のフロントマター（必須）：

---
name: skill-name-kebab-case
description: One sentence describing what this skill does and who should use it.
---

name は、空白を含まないダッシュケースにしてください。スキルを名前で読み込むツールは、名前にスペースが含まれていると、エラーを通知せずに失敗したり、正しく動作しなかったりすることがあります。name フィールドは機械向けの識別子です。人が読みやすい表示には、本文の # Heading を使ってください。

SKILL.md 本文（推奨される構成）：

# {Skill Title}

{2-3 sentence overview}

## Quick Start

{Most essential information to start using - code snippet, key concept, or first steps}

## Key Concepts

{Explain the main ideas or capabilities}

## Common Patterns

{Show 2-3 typical use cases with examples}

## When to Use This Skill

{Guidance on when agents should invoke this skill}

参照ファイル（複雑なスキル向け。任意）：

---
name: reference-title
description: What this reference covers
---

# Reference Title

{Introduction}

## Section 1
{Content}

## Section 2
{Content}

執筆ガイドライン：

  • SKILL.md は 300～500 語を目安にしてください
  • 抽象的な説明より、具体例を使ってください
  • 関連する場合は、コードブロックやスニペットを含めてください
  • 相対パスを使ってスキル間をリンクしてください：[skill-name](...)
  • LLM が利用しやすいよう、明確で構造化された、宣伝文句のない文章にしてください
  • ソースファイルにあるデータを重複して記載しないでください。 既存のリポジトリ内にある設定ファイル、スクリプト、定義から情報を導き出せる場合は、それをスキルにコピーしないでください。代わりに、エージェントに参照先を示してください（"Run scripts/deploy-info telecine for current service list" のように実行を指示するか、"See telecine/deploy/worker-resources.config.ts for current allocations" のように読むべきファイルを示します）。スキルは事実のキャッシュではなく、推論の手引きにしてください。
  • 情報の陳腐化を確認してください： セクションを仕上げる前に、「明日、誰かが設定ファイルを変更したら、この文章は誤った内容になるだろうか？」と自問してください。そうなる場合は、内容を繰り返すのではなく、参照元を示すように書き直してください。
補助スクリプト

一部のスキルには、補助スクリプトが必要です。これはローカルの設定ファイルを照会し、エージェントが利用できる最新データを出力するスクリプトです。スキルの文章にハードコードされた表やリストを記載する代わりに使います。

補助スクリプトを作成する場合：

  • スキルの対象領域に、変化する設定（サービス一覧、リソース割り当て、パッケージのバージョン、ルーティングテーブル、シークレット名）が含まれる
  • よくある質問に答えるために、複数のソースファイルを読み取って相互に照合する必要がある
  • ソースファイルの形式を解析するのに、ドメイン知識が必要（Pulumi TypeScript、GitHub Actions YAML、複雑な設定など）

設計原則：

  • ローカルのみ。 ネットワーク、Docker、認証は使いません。スクリプトはディスク上のファイルを解析し、1 秒以内に実行できるようにしてください。
  • ルート階層に配置。 補助スクリプトはパッケージ内ではなく、モノレポのルートにある scripts/ に配置してください。
  • 構造化されたプレーンテキスト出力。 YAML のように、1 行に 1 フィールドを出力してください。人にも LLM にも読みやすい形式にします。JSON（コンテキストウィンドウに対して冗長すぎます）や、整形された表（解析時に曖昧です）は使わないでください。
  • 薄いラッパーのパターン。 npx tsx scripts/{name}.ts を呼び出す bash スクリプト（scripts/{name}）を作成してください。既存の規約に合わせた形です（scripts/skills-sync を参照）。

補助スクリプトを作成しない場合：

  • データが単純な単一ファイル（例：package.json）にあり、エージェントが直接読める
  • スキルの対象領域が手順のみ（ハウツー手順、デバッグのワークフローなど）
  • データがほとんど変化しない（デプロイプロセス、ツールチェーンの選択など）

この場合は、エージェントに読むべきファイルを伝えてください。例："See telecine/deploy/worker-resources.config.ts for current allocations."

例： deployments スキルでは、scripts/deploy-info telecine と scripts/deploy-info elements を使って、ローカルの設定ファイルから現在のサービス、リソース、ルート、シークレット、パッケージ、およびリリースパイプラインの手順を照会します。

フェーズ 4：検証

同期する前に、スキルを検証します。

  1. ファイル構造の確認：

    # Verify files exist
ls -la .skills/internal/{skill-name}/

# Should see: SKILL.md (required)
# May see: references/ directory with additional .md files

  2. フロントマターの検証：

    • 必須フィールドが存在すること：name、description
    • name がケバブケースで、ディレクトリ名と一致していること
    • description が1文であること
    • 構文エラーがないこと（有効な YAML）

  3. コンテンツの検証：

    • 明確な導入セクションがあること
    • 小見出しが整理されていること
    • 具体例が含まれていること
    • リンクが正しく記述されていること：text または text

  4. 乖離の確認：

    • 各セクションを調べ、列挙されたデータ（値の表、名前の箇条書き、ハードコードされた件数やバージョン）を確認します
    • 各項目について、「このデータは独立して変更される可能性があるソースファイルに存在するか？」と確認します
    • 該当する場合は、ソースファイルまたは付属スクリプトへの参照に置き換えます
    • よくある対象：サービス／ワーカーの一覧、リソース割り当て、パッケージ名、シークレット名、ルートテーブル、パイプラインのステップ一覧、環境変数

  5. 例の確認：

    # Manually verify the content structure
cat .skills/internal/{skill-name}/SKILL.md
フェーズ 5：同期

スキルの作成と検証が完了したら、次の手順を実行します。

  1. ユーザーに確認：「このスキルをすべてのエージェントディレクトリに同期してもよろしいですか？」

  2. 同期スクリプトを実行：

    npm run skills:sync

  3. 同期を検証：

    # Check that files now exist in all 3 directories
ls -la .skills/internal/{skill-name}/SKILL.md
ls -la .cursor/skills/{skill-name}/SKILL.md
ls -la .claude/skills/{skill-name}/SKILL.md

  4. 成功を報告：

    ✅ Skill synced successfully!

Synced to:
- .skills/internal/ (canonical source)
- .cursor/skills/ (Cursor agent)
- .claude/skills/ (Claude Code agent)
フェーズ 6：Git にコミット

スキルの作成と承認が完了している場合：

  1. 変更をステージング：

    git add .skills/internal/{skill-name}/

  2. コミットを作成：

    git commit -m "Create {skill-name} skill"

  3. コミットを確認：

    git log -1 --name-status

完全な対話例

ユーザー：「動画レンダリングの問題をデバッグするスキルが必要です」

エージェント（調査フェーズ）：

動画レンダリングのデバッグスキルの作成をお手伝いします。詳細を確認させてください。

  1. よくあるレンダリングエラー（アーティファクト、再生の問題、エンコード）を対象にしますか？
  2. 主なユーザーは誰ですか（開発者、コンテンツ制作者など）？
  3. どのシステムを対象にしますか（Elements、React、API など）？

ユーザー：「すべて対象でお願いします。Elements のレンダリングをデバッグする開発者向けです」

エージェント（計画フェーズ）：

かしこまりました！elements-rendering-debug というリファレンススキルを作成します。内容は次のとおりです。

  • SKILL.md：デバッグワークフローの概要
  • references/common-issues.md：アーティファクト、再生、メモリの問題
  • references/diagnostics.md：調査とトラブルシューティングの方法
  • references/solutions.md：一般的な修正方法と回避策

エージェント（作成フェーズ）：

スキルの構造を作成しています……

[ファイルを書き込み]

エージェント（検証フェーズ）：

スキルを検証しています。 ✅ ディレクトリ構造は正しいです ✅ SKILL.md のフロントマターは有効です ✅ すべての参照ファイルが含まれています ✅ リンクは正しく記述されています

エージェント（同期フェーズ）：

このスキルをすべてのエージェントディレクトリに同期してもよろしいですか？

実行中：npm run skills:sync

✅ 同期に成功しました！

  • .skills/internal/elements-rendering-debug/（正規版）
  • .cursor/skills/elements-rendering-debug/
  • .claude/skills/elements-rendering-debug/

エージェント（コミットフェーズ）：

Git にコミットしています。

git add .skills/internal/elements-rendering-debug/
git commit -m "Add elements-rendering-debug skill"

✅ 完了しました！このスキルはすべてのエージェントディレクトリで利用できるようになりました。

例：変化しやすいデータの特定と抽出

この例では、初稿に時間とともに変化するデータが含まれている場合に何が起きるかを示します。

エージェントが、次の表を含むデプロイスキルを作成します。

サービスCPUメモリ最大インスタンス数
web1000m1Gi10
render-fragment2000m4Gi200

レビュー（フェーズ 4 のドリフトチェック）でこれを検出します。CPU、メモリ、インスタンス数はすべて、worker-resources.config.ts と Pulumi の cloudrun.ts ファイルに記載されています。誰かが render-fragment を 8Gi に調整すると、スキルのドキュメントはすぐに誤った内容になります。

解決策：これらのソースファイルを解析して最新の値を出力する付属スクリプト（scripts/deploy-info）を作成します。スキル内の表を次の内容に置き換えます。

scripts/deploy-info telecine を実行して、現在のサービスとリソース割り当てを確認します。

スキルには、手順やアーキテクチャに関する内容（デプロイの仕組み、リソースのスケーリング方法、ロールバック方法）を残します。変化しやすいデータは常に最新の状態で取得します。

既存のスキルの更新

既存のスキルを更新するには、次の手順に従います。

  1. スキルを特定する：

    ls .skills/internal/{skill-name}/

  2. 変更する：

    • SKILL.md の内容を編集する
    • 参照ファイルを追加・変更する
    • 必要に応じてフロントマターを更新する

  3. 検証する（上記のフェーズ 4 と同じです）

  4. 同期する：

    npm run skills:sync

  5. コミットする：

    git add .skills/internal/{skill-name}/
git commit -m "Update {skill-name} skill"

スキルディレクトリ

正規ディレクトリを確認して、現在のスキルを一覧表示します。

ls .skills/internal/

各サブディレクトリがスキルです。SKILL.md のフロントマターを読んで、名前と説明を確認します。

主なファイルとスクリプト

スクリプト
  • npm run skills:sync - 内部スキルをすべてのエージェントディレクトリに同期します
  • npm run skills:sync:dry - 同期される内容をプレビューします
  • npm run skills:sync:verbose - 詳細な同期結果を表示します
  • npm run skills:generate - 外部向けに公開するスキルを生成します
ディレクトリ
  • .skills/internal/ - 正規の信頼できるソース（git にコミットします）
  • .cursor/skills/ - Cursor エージェントの同期済みコピー
  • .claude/skills/ - Claude Code エージェントの同期済みコピー
  • .skills/external/ - 生成された外部向けスキル（gitignore 対象）
ドキュメント
  • skills/SYNC.md - スキル同期システムの完全なドキュメント
  • .skills/internal/skills-docs/SKILL.md - スキルのドキュメントシステムに関する詳細なドキュメント

使用を通じたスキルの改善

内部スキルは使用を通じて自己改善されるべきです。エージェントがスキルに従った結果が誤っていた、不完全だった、または最適でなかった場合に、ユーザーからフィードバックがあれば、エージェントはタスクを完了する前にスキルを更新するべきです。

スキルを更新するタイミング：

  • スキルの指針に従った結果が誤っており、ユーザーによる修正が必要になった
  • ユーザーが補う必要のある手順や考慮事項がスキルに欠けていた
  • ユーザーが、現在のタスクを超えて一般化できる原則や制約を提示した

更新方法：

  • 一般化する。 具体的な事例から再利用できる教訓を抽出します。「コンテンツは手順、アーキテクチャ、列挙データに分類する」のであり、「デプロイスキルの作成時に、サービスの表は古くなると分かった」ではありません。
  • 簡潔に保つ。 スキルの改善では、内容を長くするのではなく、より正確にします。段落を追加する場合は、削除または簡潔にできる段落がないか確認します。
  • 末尾に追加しない。 スキルはログではありません。「学んだ教訓」のセクションを追加したり、例を積み重ねたりしないでください。ガイドラインを改訂する、検証項目を追加する、フェーズの説明を調整するなど、既存の構成に改善点を組み込みます。
  • 同期してコミットする。 スキルの更新も同じワークフローに従います。.skills/internal/ を編集し、npm run skills:sync を実行して、コミットします。

してはいけないこと：

  • セッション固有の詳細を記録しないでください（「2 月 17 日に発見した……」など）
  • あらゆるエッジケースを新しい箇条書きとして追加しないでください。スキルは一般性を保つ必要があります
  • 例外的な一度きりのケースに対応するために、既存の指針を弱めないでください

スキルを作成すべきでない場合

スキルが不要なのは、次のような場合です。

  • 一度限りのタスクやデバッグ作業
  • 一時的なユーティリティやスクリプト
  • コードコメントに記載すべき内容
  • エージェントがその場で回答できる質問

スキルが適切なのは、次のような場合です。

  • 繰り返し実行するプロセス（新しいプロジェクトの作成、デバッグのパターンなど）
  • 複数のエージェントが従うべきガイダンス
  • 見つけやすくする必要がある知識
  • 標準化すべき手法

優れたスキルを作成するためのヒント

✅ 目的が明確 - 1つのスキルにつき、目的または領域は1つです ✅ 自己完結型 - 単独で理解できます ✅ 実用的 - 実際の例やパターンが含まれています ✅ 見つけやすい - 対象範囲が名前から明確にわかります ✅ リンク可能 - 関連する場合は他のスキルを参照します ✅ 最新 - 手法の変更に応じて更新されます

トラブルシューティング

Q: スキルが同期されません。 A: npm run skills:sync:dry を実行して、エラーがないか確認してください。.skills/internal/ のファイル権限も確認してください。

Q: .cursor/ と .skills/ のどちらで編集すべきですか？ A: 必ず .skills/internal/（正式なソース）で編集してください。Git にコミットされるのはこちらです。

Q: エージェントごとに異なるスキルを設定できますか？ A: いいえ。すべてのエージェントに同じスキルが適用されます。単一のソースとして .skills/internal/ を使用してください。

Q: スキルを削除するにはどうすればよいですか？ A: .skills/internal/ から削除してから、npm run skills:sync を実行してください。スキルはエージェントのディレクトリから自動的に削除されます。

Q: スキルの変更を元に戻すにはどうすればよいですか？ A: git を使用します。git checkout HEAD -- .skills/internal/{skill-name}/ を実行してから、npm run skills:sync を実行してください。

コメント

Markdown 対応