44 lines
3.7 KiB
Markdown
44 lines
3.7 KiB
Markdown
# Skills（InstallSkill / ReadSkill / ListSkills）
|
||
|
||
Skill は「参照知識」（手順書・ガイド・規約）。実行テンプレートの Piece とは別物。
|
||
Piece の取得・編集には GetPiece / CreatePiece / UpdatePiece を使う。
|
||
|
||
利用可能なスキル一覧はシステムプロンプトの **Skills Index** に出る。本文を読むには
|
||
`ReadSkill({ name: "..." })` を呼ぶ。
|
||
|
||
> **重要: スキルを `Read` で直接読もうとしないこと。** スキルは workspace の外に
|
||
> 保存されており、`Read("skills/<name>/SKILL.md")` のようなパスは（ディレクトリ型を
|
||
> ReadSkill で展開する前は）存在しない。まず `ReadSkill({ name })` を呼ぶ。ディレクトリ型は
|
||
> それで `skills/<name>/` に展開され、以後は `skills/<name>/...` を `Read` で読める。
|
||
|
||
## ツール
|
||
|
||
- **InstallSkill** — スキルを保存する。通常は `content` に SKILL.md 全文（YAML frontmatter + 本文）を渡す。workspace 内に `SKILL.md` と `scripts/` 等を含むディレクトリを組み立て済みなら `sourcePath` に **workspace 相対パス**（例: `output/my-skill`）を渡す。ホスト上のフルパスは不要（パス中に workspace の実配置（`space/{id}/files` 等）が含まれていれば自動で workspace 相対に読み替える）。`scope` は `user`（個人 or 共有ワークスペース）か `system`（全ユーザー共有・admin のみ）。**`name` パラメータは SKILL.md frontmatter の `name:` と完全一致が必須**（不一致だと一覧上の表示名と保存フォルダ名がズレて UI から管理不能になるため、インストール自体を拒否する）。frontmatter に有効な `name:`（`[a-z0-9_-]`）が無い SKILL.md も拒否される。
|
||
- **ReadSkill** — スキル本文を取得する。ディレクトリ型スキルは workspace の `skills/{name}/` に展開され、その相対パスでスクリプトを実行できる。展開済みでもスキル元が更新されていれば、次の ReadSkill でコピーを丸ごと最新版に置き換える（元が未変更なら workspace 内コピーへの手直しは維持される）。
|
||
- **ListSkills** — インストール済みスキルの一覧を返す。
|
||
|
||
## スコープと可視性（重要）
|
||
|
||
`scope: 'user'` で保存したスキルの置き場所は、**いま作業しているワークスペースで決まる**。
|
||
AGENTS.md・メモリ・Piece と同じ考え方。
|
||
|
||
| 作業中のワークスペース | 保存先 | 見える人 |
|
||
|---|---|---|
|
||
| 共有ワークスペース（案件など） | `data/spaces/{spaceId}/skills/` | そのワークスペースのメンバー全員 |
|
||
| 個人ワークスペース | `data/users/{userId}/skills/` | 自分だけ |
|
||
|
||
つまり、共有ワークスペースで作ったスキルはメンバー間で共有され、Skills Index にも
|
||
全メンバー分が出る。個人ワークスペースで作ったスキルは自分専用で、他人には見えない。
|
||
|
||
`scope: 'system'` は作業中のワークスペースに関係なく常に全ユーザー共有（admin 専用）。
|
||
この挙動はワークスペーススコープの影響を受けない。
|
||
|
||
### 共有時の注意
|
||
|
||
共有ワークスペースのスキルは他メンバーのジョブからも実行され得る（共有 Piece・
|
||
共有 AGENTS.md と同じ信頼境界）。秘匿情報や自分専用の手順は、共有ワークスペースでは
|
||
保存しないこと。個人ワークスペースで作れば自分だけのものになる。
|
||
|
||
InstallSkill のセキュリティスキャン（高深刻度をブロック、中深刻度を警告）と
|
||
sourcePath の workspace 外参照拒否・サイズ/深さ上限は、スコープに関係なく常に適用される。
|