起動契約
Piまたは他のエージェントランタイム向けの再利用可能なAIスキルを作成または更新する際にこのスキルを使用してください。
以下の場合にスキルを作成します：
- ワークフローや慣行がセッション間で再利用される場合
- 汎用的なエージェント動作にプロジェクト固有の制約が必要な場合
- 意思決定ツリーがエージェントの安全な選択を支援する場合
- 例、テンプレート、参照情報が将来の実行の信頼性を高める場合
一回限りのタスク、汎用的なドキュメント、またはコードやテストに属するルールについてはスキルを作成しないでください。
厳格なルール
docs/skill-style-guide.mdをスキルの構造とスタイルに関する規範的な情報源として従います。- スキルはLLMランタイム契約であり、人間向けのドキュメントではありません。
SKILL.mdは簡潔に保ちます：目標180～450トークン、最大1000トークン。- 命令形の指示と具体的なゲートを使用し、チュートリアルや背景説明は避けます。
- フロントマターの
descriptionは1行のYAMLセーフな文字列で、トリガーワードを先頭に含めます。 Keywordsセクションは追加せず、必須のトリガーワードはdescriptionに含めます。- テンプレート、スキーマ、生成例は
assets/に配置します。 - 長い根拠やローカルドキュメントへのリンクは
references/に配置します。 - プロジェクトのスキルを変更した後、利用可能な場合は
/skill-registry:refreshでレジストリを更新します。
意思決定ゲート
| ニーズ | アクション |
|---|---|
| 小さな再利用可能な動作 | skills/{skill-name}/SKILL.mdのみ作成 |
| テンプレート、スキーマ、フィクスチャ | skills/{skill-name}/assets/を追加 |
| 長い説明やエッジケース | skills/{skill-name}/references/を追加 |
| 既存のスキルがカバーしている | 既存のスキルを更新 |
| スキルがデリゲーション検出に影響する | トリガーワードがdescriptionに含まれていることを確認 |
実行手順
- スキルを作成または更新する前に
docs/skill-style-guide.mdを読む。 - 既存のスキルを確認し、新しいスキルが重複していないことを確認する。
- ユーザー向けトリガーに一致するケバブケースのスキル名を選ぶ。
- 以下の構造を作成または更新する：
skills/{skill-name}/
├── SKILL.md
├── assets/ # オプション
└── references/ # オプション
- 以下のフロントマターシェイプを使用する：
---
name: {skill-name}
description: "Trigger: {ユーザーまたはエージェントが言うフレーズ}. {このスキルの機能}."
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
- セクションは以下の順序で記述する：起動契約、厳格なルール、意思決定ゲート、実行手順、出力契約、参考文献。
- これがパッケージ化された
gentle-piスキルの場合は、scripts/verify-package-files.mjsに追加する。 - スキルレジストリの更新パスをリフレッシュまたは文書化する。
出力契約
以下を返します：
- 作成または変更されたファイル。
- 新しいスキルを作成したのか、既存のスキルを更新したのか。
- 追加された
assets/またはreferences/ファイル。 - パッケージ検証またはスキルレジストリのリフレッシュが必要かどうか。
参考文献
docs/skill-style-guide.md— LLMファーストのスキルスタイルガイド（規範的）。skills/skill-registry/SKILL.md— レジストリのリフレッシュとインデックス契約。