docs/extending.md

# カスタマイズと拡張

note Workspaceは、5つの担当を使う標準運用と、1つの執筆サポーターにまとめる簡易運用を選べます。独自の機能を足す場合は、配布版を更新しやすいよう、別のSkillやadapterとして管理します。

変更の大きさに応じて、次の三つを使い分けます。

| したいこと | 推奨する方法 |
|---|---|
| taskを減らして一つの会話で使いたい | 組み込みの1task簡易運用を選ぶ |
| 自分だけの質問、記事形式、保存処理、役割を足したい | 同じ利用者workspaceを読む別のlocal Skillを作る |
| 製品全体の方針、schema、標準workflowを変え、再配布したい | GitHub repositoryをforkして別のSkill Packとして管理する |

どの方法でも、利用者workspaceのfileを正本にし、元のSkill Pack更新と利用者データの移行を別の操作にします。

## 1task簡易運用

複数taskが合わない場合は、`📝 note｜執筆サポーター`一つが戦略、計測、記事制作、画像制作、日記の役割を切り替えます。

- 共通の`STUDIO.md`、運用設定、継続指示を読む。
- 計測と戦略、記事と画像の工程順を保つ。
- 原稿品質、画像QA、記事ごとのnote下書き承認を省略しない。
- 会話が長くなっても、継続状態はworkspaceのfileへ残す。

## 自分専用のlocal Skillを足す

本人だけの運用変更は、既存Skillのfolderを直接編集せず、独立したSkillとして作る方が更新しやすくなります。例として、次のような拡張があります。

- 特定の連載だけで使う構成テンプレート。
- 音声メモを受け取る独自入口。
- 業務用と個人用を混ぜない追加の公開範囲確認。
- 自分だけの月次振り返り。
- 別の画像表現や、追加のQA手順。

追加Skillは、必要なworkspace fileだけを読み、書き込むfile、外部操作、承認境界を明示します。既存schemaへ未知のfieldを黙って足したり、記事本文や指標を別の中央保存先へ自動送信したりしません。

利用中のhostに公式または信頼できるSkill Creatorが導入済みなら、Skillの雛形作成と検証に使えます。追加導入や実行権限の変更が必要な場合は、その内容を確認してから進めます。

Skill Creatorがなくても、既存Skillの`SKILL.md`、references、schema、合成evalを見本にして手動で独立Skillを作れます。

## GitHub forkで製品全体を変える

標準の役割、schema、製品名、配布内容を変えて再配布する場合は、元repositoryをforkし、別のSkill Pack IDとversionで管理します。

- 元の`skill-pack.json`、各`SKILL.md`、schema、adapter、eval、testを同じ変更で揃える。
- 元製品と区別できる表示名、source、license表示を保つ。
- 利用者workspaceとの互換性を約束する場合はmigrationを用意する。
- upstream更新を取り込む前に、自分の変更と安全境界の差を確認する。
- 実利用者のworkspace、記事、画像、指標、認証情報をforkへ入れない。

再配布する場合は、変更者が自分の配布物としてinstall、update、uninstall、移行を検証します。

ソースを変更した後は、リポジトリのルートで同梱の品質確認を実行できます。配布構成、データ形式、文章ファイル、合成テストをまとめて検証します。必要な環境はPython 3.9以降とGitです。

```sh
python3 scripts/run_local_quality_gate.py
```

Git履歴を含まないダウンロード済みフォルダでは、末尾に`--skip-git`を付けて実行します。画像生成やnoteへの下書き登録を変更した場合は、実際の表示・保存状態も確認してください。

## 役割taskを増やす時

標準5task以外の役割を追加する時は、task数を増やす前に責任分離の価値を確認します。

1. 既存5taskのどれにも自然に置けない責任か。
2. 独立した会話文脈が、利用者の理解や品質を実際に良くするか。
3. どのworkspace fileを読み書きするか。
4. 誰が開始し、誰へ完了receiptを返すか。
5. taskがなくてもcore workflowを続けられるか。
6. 外部状態の作成、定期実行、権限に個別承認が必要か。

画像taskの追加は、同時に複数記事を制作する場合や、既存taskが長期化して動作しづらい場合だけを標準の例外にします。hidden subtaskを増やして利用者から進行が見えなくなる構成にはしません。

## 変えない安全境界

カスタマイズ後も、少なくとも次は明示的に変更・検証しない限り維持します。

- 会話だけを継続状態の正本にしない。
- 本人の一次情報を一般論や架空の経験で置き換えない。
- 取得不能な指標を`0`にしない。
- noteの公開、予約投稿、既存記事の上書きを初期動作にしない。
- 記事、画像、URLが完成した後に、その一件だけの下書き登録承認を取る。
- Skill更新と利用者workspaceの移行・削除を分ける。
- 認証情報、private URL、実利用者データを公開repositoryへ入れない。