88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
# Skills
|
||
|
||
スキルはエージェントが参照する**手順書・知識ベース**です。Claude Code / Codex / gstack と互換のフォーマット（Markdown + YAML frontmatter）で記述し、エージェントが必要に応じて `ReadSkill` で読み込みます。
|
||
|
||
## Piece との違い
|
||
|
||
| | Piece | Skill |
|
||
|---|-------|-------|
|
||
| 役割 | **実行テンプレート** — ツール権限・遷移フローを制御 | **参照知識** — 手順・規約・ガイドを提供 |
|
||
| フォーマット | YAML（MAESTRO 固有） | Markdown（Claude Code / Codex 互換） |
|
||
| 選択 | piece-classifier が自動選択 | エージェントが ReadSkill で任意に参照 |
|
||
| 実行制御 | `allowed_tools` でツールを制限 | 制御なし（エージェントの判断に委ねる） |
|
||
|
||
**判断基準:**
|
||
- ツールの許可・禁止や movement フローを定義したい → **Piece**
|
||
- 手順書・コーディング規約・デバッグガイドをエージェントに参照させたい → **Skill**
|
||
|
||
## スキルの構造
|
||
|
||
### 単一ファイル形式
|
||
|
||
```
|
||
data/skills/my-workflow.md
|
||
```
|
||
|
||
### ディレクトリ形式（スクリプト同梱）
|
||
|
||
```
|
||
data/skills/tdd/
|
||
SKILL.md ← 本体（frontmatter + 手順）
|
||
scripts/ ← 実行可能スクリプト（任意）
|
||
references/ ← 参照ドキュメント（任意）
|
||
```
|
||
|
||
### Frontmatter
|
||
|
||
```yaml
|
||
---
|
||
name: tdd
|
||
description: テスト駆動開発の手順
|
||
triggers:
|
||
- テスト
|
||
- 新機能
|
||
---
|
||
```
|
||
|
||
- `name`（必須）: `[a-z0-9_-]` のみ
|
||
- `description`（必須）: 1 行の説明
|
||
- `triggers`（任意）: 関連キーワード
|
||
|
||
## スコープ
|
||
|
||
| スコープ | 場所 | 書き込み | 読み取り |
|
||
|---------|------|---------|---------|
|
||
| system | `data/skills/` | admin のみ | 全ユーザー |
|
||
| user | `data/users/{userId}/skills/` | 本人のみ | 本人のみ |
|
||
|
||
ユーザースキルがシステムスキルと同名の場合、ユーザースキルが優先されます。
|
||
|
||
## インストール方法
|
||
|
||
### UI から
|
||
Settings → Skills タブで：
|
||
- 「Install from URL」に Git リポジトリの HTTPS URL を入力
|
||
- 「+ New Skill」で手動作成
|
||
|
||
### エージェント経由
|
||
```
|
||
InstallSkill({ name: "my-skill", content: "...", scope: "user" })
|
||
InstallSkillFromDir({ sourcePath: "/workspace/output/skill-dir", name: "my-skill", scope: "user" })
|
||
```
|
||
|
||
### 手動
|
||
`data/skills/` または `data/users/{userId}/skills/` に `.md` ファイルまたはディレクトリを配置すると自動検出されます（60 秒のキャッシュ TTL）。
|
||
|
||
## セキュリティ
|
||
|
||
- インストール時にセキュリティスキャンが実行されます
|
||
- `high` 重大度（prompt injection、他ユーザーリソース参照等）はインストールをブロック
|
||
- `medium` 重大度（外部 URL、ネットワークコマンド等）は警告表示
|
||
- スクリプト実行は `bash_unrestricted: true` 時のみ可能（bwrap sandbox 内で隔離実行）
|
||
|
||
## エージェントからの利用
|
||
|
||
movement 開始時にスキルインデックス（名前 + 説明の一覧）がシステムプロンプトに自動注入されます。エージェントは `ReadSkill({ name: "tdd" })` で本文を取得し、指示に従って作業します。
|
||
|
||
ディレクトリ形式のスキルでは、レスポンスに sandbox 内パス（`/skills/tdd`）が含まれ、`bash /skills/tdd/scripts/run.sh` のようにスクリプトを実行できます。
|