スキルマニフェスト

外部スキルは、manager の allow-list ディレクトリの 1 つに置かれた skill.json ファイルで記述されるサブプロセス実行可能ファイルです。ローダーは起動時にそれらのディレクトリを walk し、各 skill.json をパースし、グローバルスキルレジストリに SubprocessSkill を登録します。LLM はそのスキルを組み込みツールと並んで見ます。

真実の出所：internal/skill/loader.go。

ディスク上のレイアウト

/etc/ongrid/skills/                  ← one entry in $ONGRID_SKILLS_EXTERNAL_DIRS
└── disk-cleaner/
    ├── skill.json
    └── run.sh                       ← the executable

各 skill.json は自身のサブディレクトリのトップにあります。ディレクトリツリーは再帰的に walk され、skill.json という名前のファイルはマニフェストとして扱われます。複数のスキルが同じ allow-list ルート下に住めます。

マニフェストスキーマ

{
  "name": "disk_cleaner",
  "description": "Free up disk by clearing stale build caches and journals.",
  "schema": {
    "type": "object",
    "properties": {
      "path":   { "type": "string", "description": "Root path to clean." },
      "dry_run": { "type": "boolean", "default": true }
    },
    "required": ["path"]
  },
  "entry": "run.sh",
  "env_allow": ["PATH", "HOME"],
  "timeout_seconds": 60,
  "class": "mutating",
  "category": "ops"
}

フィールド	型	必須	説明
name	string	はい	スキルキー。[a-z0-9_]+ にマッチする lower_snake であること。LLM 向け関数名になる。
description	string	はい	ヒューマン（UI）と LLM（関数 description）に表示。
schema	JSON Schema	いいえ	args オブジェクトの生 JSON Schema。欠落 = 空オブジェクトスキーマ。
entry	string	はい	実行可能ファイルへのパス。相対パスは skill.json を持つディレクトリに対して解決。絶対パスは allow-list ルート下にある必要あり。
env_allow	string[]	いいえ	子に転送される env-var 名の明示リスト。空リスト = env なし（PATH さえも）。"PATH" を追加して PATH をオプトイン。
timeout_seconds	int	いいえ	サブプロセスタイムアウト。ゼロは DefaultSubprocessTimeout（30s）にフォールバック。
class	enum	いいえ	safe（デフォルト）、mutating、dangerous。クラス分類 参照。
category	string	いいえ	自由形式グループラベル。external がデフォルト。UI がサブプロセススキルをこれでグルーピング。

ワイヤープロトコル

サブプロセスは stdin = JSON args オブジェクト、stdout = JSON 結果オブジェクト、stderr = manager 用ログ行 で発動されます。

$ cat /tmp/args.json
{"path": "/var/cache", "dry_run": true}

$ run.sh < /tmp/args.json
{"freed_bytes": 1048576, "files_deleted": 17}

非ゼロ終了コードは失敗として扱われます。stderr はツール呼び出しイベントタイムラインに捕捉され、LLM が部分進捗を読めます。

結果オブジェクトは LLM に逐語で返されます。エージェントカーネルはこれをツール呼び出しのレスポンスとしてフォーマットします。LLM は JSON 形について推論することが期待されます。

クラス分類

同じ {safe, mutating, dangerous} 分類がネイティブスキルとサブプロセススキル両方に適用されます。

クラス	何ができるか	必須ペルソナパーミッション
safe	読み取り専用 —— ホストやシステムへの副作用なし。	read-only（任意のペルソナ）
mutating	状態の作成 / 更新。可逆。	mutating-with-confirm または dual-sign-required
dangerous	不可逆（削除、再起動、exec-arbitrary）。	dual-sign-required（SOP）

ペルソナの permission_mode フィールドが確認なしでどのクラスが動くかゲートします。エージェントペルソナフォーマット 参照。

Allow-list ルール

operator は ONGRID_SKILLS_EXTERNAL_DIRS（コロンまたはカンマ区切り絶対パス）で allow-list ディレクトリを設定します。ローダーは厳密に強制します：

• 各ディレクトリは 絶対 パスであること。相対パスはログ行付きでスキップ。
• 存在しないパスはスキップ（なので /etc/ongrid/skills がない新規インストールはちゃんと起動）。
• 各マニフェストの entry は filepath.EvalSymlinks で正規化され、allow-list ルート下に住むかチェックされます。ルートの外を指すシンボリックリンクは拒否されます（entry %s escapes allowlist root %s）。

それ以上のサンドボックスはサブプロセスの責任です。スキルがタイトに封じ込められる必要があれば、entry として参照されるラッパー（bwrap、firejail、nsenter）下で走らせてください。

ローダー挙動

LoadDirs(cfg)
  for each dir in cfg.Dirs:
    filepath.Walk(dir)
      for each skill.json found:
        parseManifest(path)
        buildSubprocessSkill(manifest, path, root)
        if skill already registered: skip (log line)
        else Register(skill)

• マニフェストごとの検証失敗は ログされてスキップ されます。1 つの壊れたパックが起動をブロックしないように。
• 重複名はエラーではなくスキップされます（古いマニフェストを削除する前に新しいマニフェストを投下するリデプロイで manager がクラッシュしないように）。
• ローダーは正常に登録されたスキルの数を返します。manager 起動はスキルローダーで非ブロッキング：空の外部 dir は no-op。

起動時のログ

manager はマニフェストごとに 1 行ログします：

skill loader: registered subprocess skill "disk_cleaner" from /etc/ongrid/skills/disk-cleaner/skill.json
skill loader: skill "broken_one" already registered, skipping /etc/ongrid/skills/broken-one/skill.json
skill loader: parse /etc/ongrid/skills/typo/skill.json: invalid character ',' looking for beginning of object key
skill loader: build "bad_path": entry /tmp/escape.sh escapes allowlist root /etc/ongrid/skills

何が拾われたかを確認するには journalctl -u docker-compose@ongrid または docker compose logs ongrid を tail。

関連

• 機能 → スキル —— 組み込みスキルカタログ。
• エージェントペルソナフォーマット —— ペルソナがどのスキルを呼べるかをどう選ぶか。
• マーケットプレース —— スキルのパックを 1 単位としてインストール。
• REST API → /v1/skills —— リスト化と直接実行。

ネイティブスキルメタデータ（SKILL.md フロントマター）

./skills/ 下で出荷される組み込みスキルは、openclaw / claude-code スキルエコシステムと相互運用するより豊かな YAML フロントマター SKILL.md フォーマットを使います。スキーマは internal/manager/biz/aiops/chatruntime/types.go で定義されています：

---
name: query_promql
description: Run a PromQL query and return the result matrix.
when_to_use: When the user asks for current or recent metric values.
activation:
  mode: always
metadata:
  os: [linux, darwin]
  requires:
    bins: []
    config: []
  ongrid:
    scope: manager
    activation:
      mode: always
tools:
  - name: query_promql
    impl: builtin:prom.QueryPromQL
    class: read
    description: Execute a PromQL query and return the matrix.
---

# query_promql

PromQL query tool ...

サードパーティが書くサブプロセススキルには、上のシンプルな skill.json フォーマットを推奨します。SKILL.md は manager バイナリにコンパイルされるスキル用です。