creating-skills

スキルの作成

このスキルでは、Letta Code で効果的なスキルを作成するためのガイダンスを提供します。公式仕様の全文については、agentskills.io をご覧ください。

スキルについて

スキルはモジュール式の自己完結型パッケージであり、専門知識、ワークフロー、ツールを提供して Letta Code の機能を拡張します。特定の分野やタスク向けの「オンボーディングガイド」と考えてください。手続きに関する知識を備えた専門エージェントへと Letta Code エージェントを変えるものであり、その知識をどのモデルも完全には持ち得ません。

スキルが提供するもの

1. 専門的なワークフロー — 特定の分野における複数ステップの手順
2. ツール連携 — 特定のファイル形式や API を扱うための手順
3. 分野の専門知識 — 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース — 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

基本原則

簡潔さが重要

コンテキストウィンドウは共有資源です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Letta Code エージェントが必要とするあらゆるものとコンテキストウィンドウを共有します。

前提として、Letta Code エージェントはすでに非常に高い能力を備えています。 Letta Code エージェントがまだ持っていないコンテキストだけを追加してください。情報の一つひとつについて、「Letta Code エージェントに本当にこの説明が必要か？」「この段落はトークンを使うだけの価値があるか？」と考えてください。

冗長な説明より、簡潔な例を優先してください。

適切な自由度を設定する

タスクの壊れやすさと変動性に応じて、具体性のレベルを調整してください。

自由度が高い（テキストベースの指示）：複数の方法が有効な場合、判断が状況に左右される場合、またはヒューリスティックに基づいて進める場合に使用します。

自由度が中程度（擬似コードまたはパラメーター付きスクリプト）：推奨されるパターンがある場合、ある程度の差異が許容される場合、または設定が動作に影響する場合に使用します。

自由度が低い（具体的なスクリプト、少数のパラメーター）：操作が壊れやすくエラーが発生しやすい場合、一貫性が重要な場合、または特定の順序に従う必要がある場合に使用します。

Letta Code エージェントを道を探る存在として考えてください。崖に挟まれた狭い橋には具体的なガードレール（自由度が低い）が必要ですが、広々とした野原なら多くの経路を選べます（自由度が高い）。

スキルの構成

各スキルは必須の SKILL.md ファイルと、任意の同梱リソースで構成されます。

processing-pdfs/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required, must match directory name)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (TypeScript/Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

Letta Code の各 SKILL.md は、次の要素で構成されます。

• フロントマター（YAML）：name フィールドと description フィールドが含まれます。これらはスキルをいつ使用するかの判断に Letta Code エージェントが読み取る唯一のフィールドであるため、スキルの内容と使用すべき状況を明確かつ包括的に説明することが非常に重要です。
• 本文（Markdown）：スキルの使用方法に関する指示とガイダンスです。スキルが起動した後にのみ読み込まれます（起動した場合）。

同梱リソース（任意）

スクリプト（scripts/）

確実な動作が必要なタスクや、繰り返し書き直されるタスクに使用する実行可能なコード（TypeScript/Python/Bash など）です。

• 含めるタイミング：同じコードを繰り返し書き直している場合、または確実な動作が必要な場合
• 例：PDF の回転タスク向けの scripts/rotate-pdf.ts
• メリット：トークン効率が高く、動作が決定論的で、コンテキストに読み込まずに実行できる場合があります
• 注記：パッチの適用や環境固有の調整のために、Letta Code エージェントがスクリプトを読み取る必要がある場合もあります

参照資料 (references/)

Letta Code エージェントのプロセスと思考に情報を提供するために、必要に応じてコンテキストへ読み込まれることを目的としたドキュメントおよび参照資料です。

• 含めるべき場合: Letta Code エージェントが作業中に参照すべきドキュメント
• 例: 財務スキーマ用の references/finance.md、会社の NDA テンプレート用の references/mnda.md、会社のポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• ユースケース: データベーススキーマ、API ドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• メリット: SKILL.md をスリムに保ち、Letta Code エージェントが必要と判断したときにのみ読み込まれます
• ベストプラクティス: ファイルが大きい場合（10k 語超）、SKILL.md に grep 検索パターンを含めてください
• 重複の回避: 情報は SKILL.md または参照資料ファイルのどちらか一方に置くべきで、両方に置かないでください。本当にスキルの中核でない限り、詳細情報には参照資料ファイルを優先してください。これにより SKILL.md をスリムに保ちつつ、コンテキストウィンドウを圧迫せずに情報を発見できるようにします。SKILL.md には必須の手順指示とワークフローガイダンスのみを残し、詳細な参照資料、スキーマ、例は参照資料ファイルに移してください。

アセット (assets/)

コンテキストに読み込まれることを目的とせず、むしろ Letta Code エージェントが生成する出力内で使用されるファイルです。

• 含めるべき場合: スキルが最終出力で使用されるファイルを必要とする場合
• 例: ブランドアセット用の assets/logo.png、PowerPoint テンプレート用の assets/slides.pptx、HTML/React ボイラープレート用の assets/frontend-template/、タイポグラフィ用の assets/font.ttf
• ユースケース: コピーまたは変更されるテンプレート、画像、アイコン、ボイラープレートコード、フォント、サンプルドキュメント
• メリット: 出力リソースをドキュメントから分離し、Letta Code エージェントがファイルをコンテキストに読み込まずに使用できるようにします

スキルに含めるべきでないもの

スキルには、その機能を直接サポートする必須のファイルのみを含めるべきです。以下を含め、無関係なドキュメントや補助ファイルを作成しないでください。

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• など

スキルには、AI エージェントが目の前の作業を行うために必要な情報のみを含めるべきです。スキルの作成に至ったプロセス、セットアップとテストの手順、ユーザー向けドキュメントなどに関する補助的なコンテキストを含めるべきではありません。追加のドキュメントファイルを作成することは、混乱を増やすだけです。

段階的開示の設計原則

スキルは、コンテキストを効率的に管理するために 3 段階の読み込みシステムを使用します。

1. メタデータ（名前 + 説明） - 常にコンテキスト内（約 100 語）
2. SKILL.md 本文 - スキルがトリガーされたとき（5k 語未満）
3. バンドルされたリソース - Letta Code エージェントが必要に応じて（スクリプトはコンテキストウィンドウに読み込まずに実行できるため無制限）

段階的開示のパターン

SKILL.md の本文は要点のみに絞り、コンテキストの肥大化を最小限に抑えるため、500 行未満にしてください。この上限に近づいたら、内容を別ファイルに分割してください。内容を別ファイルに分割する場合は、SKILL.md からそれらのファイルを参照し、いつ読むべきかを明確に説明することが非常に重要です。これにより、スキルを読む人がそれらのファイルの存在と使用するタイミングを把握できます。

重要な原則： スキルが複数のバリエーション、フレームワーク、またはオプションに対応する場合は、コアとなるワークフローと選択方法のガイダンスのみを SKILL.md に残してください。バリエーション固有の詳細（パターン、例、設定）は、別のリファレンスファイルに移してください。

パターン 1：リファレンス付きの概要ガイド

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Letta Code エージェントは、必要な場合にのみ FORMS.md、REFERENCE.md、または EXAMPLES.md を読み込みます。

パターン 2：ドメイン別の構成

複数のドメインを扱うスキルでは、関連性のないコンテキストを読み込まないよう、ドメインごとに内容を整理します。

querying-bigquery/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

ユーザーが営業指標について尋ねた場合、Letta Code エージェントは sales.md のみを読み込みます。

同様に、複数のフレームワークやバリエーションに対応するスキルでは、バリエーションごとに整理します。

deploying-to-cloud/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

ユーザーが AWS を選択した場合、Letta Code エージェントは aws.md のみを読み込みます。

パターン 3：条件付きの詳細

基本的な内容を示し、詳細な内容へのリンクを用意します。

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Letta Code エージェントは、ユーザーがこれらの機能を必要とする場合にのみ REDLINING.md または OOXML.md を読み込みます。

重要なガイドライン：

• 参照を深くネストしない - SKILL.md からの参照は 1 階層に留めてください。すべてのリファレンスファイルは SKILL.md から直接リンクしてください。
• 長いリファレンスファイルは構成を整える - 100 行を超えるファイルには、Letta Code エージェントがプレビュー時に全体の範囲を把握できるよう、冒頭に目次を含めてください。

スキルの作成プロセス

スキルの作成には、次の手順が含まれます。

1. 具体例を使ってスキルを理解する
2. 再利用可能なスキルの内容（スクリプト、リファレンス、アセット）を計画する
3. スキルを初期化する（init-skill.ts を実行する）
4. スキルを編集する（リソースを実装し、SKILL.md を作成する）
5. スキルをパッケージ化する（package-skill.ts を実行する）
6. 実際の使用状況を踏まえて反復する

明確な理由があって該当しない場合にのみ手順を省略し、それ以外は順番どおりに進めてください。

ステップ 1：具体例を使ってスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合にのみ、このステップを省略してください。既存のスキルに取り組む場合でも、このステップは有益です。

効果的なスキルを作成するには、そのスキルがどのように使われるのか、具体例を通じて明確に理解してください。この理解は、ユーザーから直接得た例、または生成した例をユーザーのフィードバックで検証することで得られます。

たとえば、editing-images スキルを構築する場合、関連する質問には次のようなものがあります。

• 「editing-images スキルでは、どのような機能に対応する必要がありますか？編集、回転、その他の機能ですか？」
• 「このスキルをどのように使うか、いくつか例を挙げてもらえますか？」
• 「『この画像の赤目を除去して』や『この画像を回転して』といった依頼を想定しています。他にも、このスキルがどのように使われると思いますか？」
• 「どのような依頼があれば、このスキルを起動すべきですか？」

ユーザーを圧倒しないよう、1 つのメッセージで質問しすぎないでください。最も重要な質問から始め、より効果的にするために必要に応じて追加で質問してください。

このスキルが対応すべき機能について明確な見通しが得られたら、このステップを終了します。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルにするには、各例について次のように分析します。

1. 例をゼロから実行する方法を検討します
2. これらのワークフローを繰り返し実行する際に、どのスクリプト、リファレンス、アセットが役立つかを特定します

例：「この PDF を回転させてください」のようなクエリに対応する editing-pdfs スキルを構築する場合、分析から次のことがわかります。

1. PDF を回転させるには、毎回同じコードを書き直す必要があります
2. scripts/rotate-pdf.ts スクリプトをスキル内に保存すると役立ちます

例：「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」のようなクエリに対応する building-frontend-apps スキルを設計する場合、分析から次のことがわかります。

1. フロントエンドのウェブアプリを作成するには、毎回同じ定型の HTML／React を記述する必要があります
2. 定型の HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキル内に保存すると役立ちます

例：「今日ログインしたユーザー数は？」のようなクエリに対応する querying-bigquery スキルを構築する場合、分析から次のことがわかります。

1. BigQuery にクエリするには、毎回テーブルのスキーマと関連を改めて調べる必要があります
2. テーブルのスキーマを記載した references/schema.md ファイルをスキル内に保存すると役立ちます

スキルの内容を決めるため、各具体例を分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）の一覧を作成します。

ステップ 3：スキルを初期化する

ここから、実際にスキルを作成します。

開発中のスキルがすでに存在し、反復作業やパッケージ化が必要な場合に限り、このステップをスキップします。その場合は次のステップに進みます。

新しいスキルをゼロから作成する場合は、必ず init-skill.ts スクリプトを実行してください。このスクリプトを使うと、スキルに必要なものがすべて自動的に含まれた新しいテンプレートスキルディレクトリが生成されるため、スキルの作成をより効率的かつ確実に進められます。

使い方：

npx tsx <SKILL_DIR>/scripts/init-skill.ts <skill-name> --path <output-directory>

<SKILL_DIR> は、スキルの読み込み時に表示されるスキルディレクトリです（インジェクションヘッダーに表示されます）。

このスクリプトは次の処理を行います。

• 指定したパスにスキルディレクトリを作成します
• 適切なフロントマターと TODO プレースホルダーを含む SKILL.md テンプレートを生成します
• リソース用のディレクトリの例として、scripts/、references/、assets/ を作成します
• 各ディレクトリに、カスタマイズまたは削除できるファイルの例を追加します

初期化後、必要に応じて、生成された SKILL.md とファイルの例をカスタマイズまたは削除します。

ステップ 4：スキルを編集する

新しく生成したスキルまたは既存のスキルを編集する際は、別の Letta Code エージェントインスタンスが使用するために作成していることを忘れないでください。Letta Code エージェントにとって役立つ、かつ自明ではない情報を含めます。別の Letta Code エージェントインスタンスがタスクをより効果的に実行するうえで役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討します。

実証済みの設計パターンを学ぶ

スキルのニーズに応じて、次のガイドを参照してください。

• 複数ステップのプロセス：順次ワークフローと条件分岐については、references/workflows.md を参照してください
• 特定の出力形式や品質基準：テンプレートと例のパターンについては、references/output-patterns.md を参照してください

これらのファイルには、効果的なスキル設計のために確立されたベストプラクティスが記載されています。

再利用可能なスキルの内容から始める

実装を始めるには、まず上記で特定した再利用可能なリソース、すなわち scripts/、references/、assets/ のファイルを確認します。この手順では、ユーザーからの入力が必要になる場合があります。たとえば、brand-guidelines スキルを実装する場合、ユーザーから提供されたブランドアセットやテンプレートを assets/ に、ドキュメントを references/ に保存する必要があるかもしれません。

追加したスクリプトは、実際に実行してバグがないことと、期待どおりの出力になることを確認する必要があります。類似したスクリプトが多数ある場合は、作業完了までの時間とのバランスを取りながら、すべてが動作するという確信を得るために、代表的なものだけをテストすれば十分です。

スキルに不要なサンプルファイルやディレクトリは削除してください。初期化スクリプトは構成例として scripts/、references/、assets/ にサンプルファイルを作成しますが、これらすべてを必要とするスキルはほとんどありません。

SKILL.md を更新する

文章作成のガイドライン： 常に命令形または不定詞形を使用してください。

フロントマター

name と description を含む YAML フロントマターを記述します。

name（必須）：

• 動名詞形を使用します：processing-pdfs、analyzing-data、creating-reports（pdf-processor ではありません）
• 小文字、数字、ハイフンのみを使用します
• ディレクトリ名と完全に一致させます
• 64 文字以内にします

description（必須）：

• 三人称で記述します：「PDF ファイルを処理します…」（「PDF の処理をお手伝いします…」や「これを使うと…できます」ではありません）
• スキルが実行する内容と、使用するタイミングの両方を含めます
• エージェントが関連するタスクを特定するのに役立つトリガーキーワードを含めます
• 1024 文字以内にします

例：

---
name: processing-pdfs
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

注： 仕様では任意のフィールド（license、compatibility、metadata、allowed-tools）が認められていますが、ほとんどのスキルでは必要ありません。詳細については、agentskills.io/specification を参照してください。

本文

スキルと同梱リソースの使用方法を記述します。

ステップ 5：スキルをパッケージ化する

スキルの開発が完了したら、ユーザーと共有できる配布可能な .skill ファイルにパッケージ化する必要があります。パッケージ化のプロセスでは、要件を満たしていることを確認するため、最初にスキルが自動で検証されます。

npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder>

出力ディレクトリの指定は任意です。

npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder> ./dist

パッケージ化スクリプトは次の処理を行います。

1. 検証：スキルを自動的に検証し、次の項目を確認します。

   • YAML フロントマターの形式と必須フィールド
   • スキルの命名規則とディレクトリ構造
   • 説明の完全性と品質
   • ファイルの整理とリソース参照

2. パッケージ化：検証に合格した場合、スキル名に基づく名前（例：my-skill.skill）の .skill ファイルを作成します。このファイルにはすべてのファイルが含まれ、配布に適したディレクトリ構造が維持されます。.skill ファイルは、拡張子が .skill の zip ファイルです。

検証に失敗すると、スクリプトはエラーを報告し、パッケージを作成せずに終了します。検証エラーを修正して、パッケージ化コマンドを再度実行してください。

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルを使用した直後に、スキルの動作についての記憶が新しいうちに依頼されます。

反復ワークフロー：

1. 実際のタスクでスキルを使用する
2. うまくいかない点や非効率な点を確認する
3. SKILL.md または同梱リソースのどこを更新すべきか特定する
4. 変更を実装し、再度テストする