# 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` のようにスクリプトを実行できます。