writing-skills

スキル作成の卓越性

互換性：これらのテンプレートは慣例であり、汎用ローダーのスキーマではありません。対象ホストで文書化されているスキルディレクトリと現行のスキーマを使用してください。カスタムの metadata.triggers は任意であり、それだけで検出が保証されるわけではありません。同梱されている上流のガイダンスは、過去のスナップショットです。レンダリングには Node.js と、ローカルにインストールされた Graphviz dot が必要です。信頼できる DOT のみを確認し、生成された SVG は慎重に開いてください。--combine はグラフ間でノード ID を共有するためのもので、意味を保ったマージではなく、視覚上の利便性を目的としています。出力先は排他的に使用されます。再実行する前に、意図的に既存の出力ディレクトリを削除するか、別の出力ディレクトリを選択してください。

対象範囲：例は作成・テスト用のフィクスチャであり、実行中の指示ではありません。ユーザー、ホスト、リポジトリの指示の優先順位に従ってください。許可された隔離フィクスチャでのみ負荷テストを実行してください。スキルを適用するために、ユーザーの作業を削除したり、安全性や承認の境界を弱めたりしないでください。既存の作業を保持し、ベースラインがすでに合格している場合は検証計画を調整してください。サンプルでの適合は、普遍的な信頼性を証明するものではありません。

スキル作成の卓越性を高めるためのディスパッチャーです。以下の決定木を使って、適切なテンプレートと標準を見つけてください。

⚡ クイック決定木

何をする必要がありますか？

1. 新しいスキルを作成する：

   • シンプルですか（単一ファイル、200行未満）？ → Tier 1 アーキテクチャ
   • 複雑ですか（複数の概念、200～1000行）？ → Tier 2 アーキテクチャ
   • 大規模なプラットフォームですか（10以上の製品、AWS、Convex）？ → Tier 3 アーキテクチャ

2. 既存のスキルを改善する：

   • 「長すぎる」を解決する → モジュール化（Tier 3）
   • 「AI がルールを無視する」を解決する → 合理化への対策
   • 「ユーザーが見つけられない」を解決する → CSO（検索最適化）

3. 適合性を確認する：

   • メタデータ／命名を確認する → 標準
   • テストを追加する → テストガイド

📚 コンポーネント一覧

コンポーネント	目的
CSO	「LLM 向けの SEO」です。呼び出しにつながる説明の書き方です。
標準	ファイル名、YAML フロントマター、ディレクトリ構造です。
合理化への対策	エージェントが無視しないルールの書き方です。
テスト	スキルが実際に機能することを確かめる方法です。

🛠️ テンプレート

• テクニックスキル（手順）
• リファレンススキル（ドキュメント）
• 規律スキル（ルール）
• パターンスキル（デザインパターン）

使用するタイミング

• 新しいスキルをゼロから作成するとき
• エージェントに無視される既存のスキルを改善するとき
• スキルが呼び出されない理由をデバッグするとき
• チーム内でスキルを標準化するとき

仕組み

1. 目標を特定する → 上記の決定木を使います
2. テンプレートを選ぶ → references/templates/ から選びます
3. CSO を適用する → 検出されやすい説明に最適化します
4. 合理化への対策を追加する → 規律スキルに適用します
5. テストする → RED-GREEN-REFACTOR サイクル

簡単な例

---
name: my-technique
description: Use when [specific symptom occurs].
metadata:
  category: technique
  triggers: error-text, symptom, tool-name
---

# My Technique

## When to Use
- [Symptom A]
- [Error message]

よくある間違い

間違い	修正方法
説明がワークフローを要約している	機能と具体的な使用条件を簡潔に説明します
metadata.triggers がない	ホスト固有の任意メタデータです。説明に有用な用語を含めます
汎用的な名前（「helper」）	説明的で、小文字とハイフンを使った ID にします
長大で一枚岩の SKILL.md	references/ に分割します

詳しくは gotchas.md を参照してください。

✅ デプロイ前チェックリスト

スキルをデプロイする前に、次の項目を確認してください。

• name フィールドがディレクトリ名と完全に一致している
• SKILL.md のファイル名がすべて大文字になっている
• 説明にスキルの機能と使用するタイミングが記載されている
• フロントマターが対象ホストおよびリポジトリのスキーマに準拠している
• 合計行数が 500 未満である（それ以上の場合は references/ を使用してください）
• 相互参照で @ による強制読み込みを使用していない
• 実際のシナリオでテスト済みである

🔗 関連スキル

• opencode-expert：OpenCode 環境の設定について
• ホストで /write-skill が定義されている場合、ガイド付きの作成機能を利用できることがあります。このコマンドはここには含まれていません

例

Tier 1 スキルを作成する：

mkdir -p ~/.config/opencode/skills/my-technique
touch ~/.config/opencode/skills/my-technique/SKILL.md

Tier 2 スキルを作成する：

mkdir -p ~/.config/opencode/skills/my-skill/references/core
touch ~/.config/opencode/skills/my-skill/{SKILL.md,gotchas.md}
touch ~/.config/opencode/skills/my-skill/references/core/README.md

制限事項

• タスクが上記の説明にある範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中止して確認を求めてください。