3.7 KiB
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 外参照拒否・サイズ/深さ上限は、スコープに関係なく常に適用される。