# Skillの操作

standalone Skillのoperation catalog、必要なscope、決定論的終了コード、およびruntime制限を確認します。

- Canonical: https://docs.xmemo.dev/ja/docs/skills/operations
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 6dd1506da83ca3c235a2b184eef2543b5c83a2510312e734028559bf4772ef75
- Edition-Digest: 94261a8648e0c51693673324569e716412323ddd9c963295fb675e4c21edb24e
- Source-Revision: sha256:7b422494897f606128295ed70568337bc1353a0d7822638452970f4081f9e0ef

## Direct HTTPSによる操作と認証ヘッダー

standalone SkillはHTTPS経由でXMemoと直接通信します。パブリックRESTエンドポイントは Authorization: Bearer <token> または X-API-Key: <key> ヘッダーを受け入れ、standalone Skill runtimeは解決されたcredentialから Authorization: Bearer <token> を使用して送信リクエストを自動的にフォーマットします。

- Skill runtimeトランスポート: https://xmemo.dev/v1/skill/operations へのすべてのリクエストに Authorization: Bearer <token> を自動的に注入します。
- REST APIの柔軟性: RESTエンドポイントを直接呼び出すスタンドアロンHTTPクライアントは、Authorization: Bearer <token> または X-API-Key: <key> のいずれかを提供できます。
- ディスカバリコントラクト: ランタイムモデルと操作エンドポイントは /.well-known/agent-discovery.json および /.well-known/memory-os.json で検出可能です。

```http
# Skill runtime uses Bearer token authorization:
POST /v1/skill/operations
Authorization: Bearer <skill-token>
Content-Type: application/json

# Direct REST endpoints also accept X-API-Key:
GET /v1/memories/search?query=onboarding&limit=5
X-API-Key: <your-assigned-api-key>
```

## タスク別の完全なコマンドインベントリ

standalone Skillパッケージ（v1.1.35）は32個のコマンドを提供します。すべてのコマンドはhelp.mjsの正確な使用法文字列と必要な認可scopeとともに以下に一覧表示されています。

- 認証とセットアップ: login --allow-plaintext, register --reason <unattended|declined> --allow-plaintext, logout [--revoke-environment-token], auth status [--verify], auth add --from-stdin --allow-plaintext, auth claim-status [--allow-plaintext], auth claim-confirm [--allow-plaintext], auth claim-deny [--allow-plaintext]。
- 記憶と検索: read --id <id> [--offset <n>] [--limit <n>] [--bucket <bucket>] [--scope <scope>] (memory:read), update --id <id> [--content <text>] [--path <path>] [--metadata <json>] [--bucket <bucket>] [--scope <scope>] (memory:write), forget --id <id> [--reason <text>] --confirm (memory:delete or memory:write), remember (--content <text> | --content - | --file <path>) [--path <path>] [--metadata <json-object>] (memory:write), recall --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--expand-documents] [--compact] (memory:read), search --query <text> [--limit <n>] [--explain <true|false>] [--prefer_working <true|false>] [--expand-documents] [--compact] (memory:read)。
- Knowledgeコンテキスト: recall-context --query <text> [--max_items <n>] [--max_tokens <n>] [--prefer_working <true|false>] [--include_knowledge <true|false>] (memory:read; opting into Knowledge with --include_knowledge true requires knowledge:read)。
- タスクの継続性とスナップショット: save-state --key <key> [--content <text>] [--ttl_seconds <0..604800>] (memory:write, alias: state-save), restore-state --key <key> (memory:read, alias: state-restore), state-save --key <key> [--content <text>] [--ttl_seconds <0..604800>] (legacy alias), state-restore --key <key> (legacy alias), restart-snapshot [--state_key <key>] [--session_id <id>] [--ttl_seconds <0..2592000>] (memory:write), restart-restore [--snapshot_id <id> | --source_session_id <id>] [--target_session_id <id>] (memory:read)。
- タスクTODO: todo-add --content <text> (memory:write), todo-list (memory:read), todo-done --id <todo_id> (memory:write)。
- 財務元帳とアナリティクス: expense-add --item <text> --amount <number> --currency <code> (ledger:write), ledger-list [--month <YYYY-MM>] [--from <date>] [--to <date>] [--currency <code>] [--category <name>] [--type <type>] [--min-amount <n>] [--max-amount <n>] [--limit <n>] [--offset <n>] (ledger:read), ledger-summary [--months <n>] [--currency <code>] [--type <type>] (ledger:read), overview (memory:read), activity [--limit <n>] (memory:read), stats [--scope <scope>] [--path <path>] [--bucket <bucket>] [--memory-type <type>] [--status <status>] [--source <src>] [--since <iso>] [--until <iso>] [--group-by <dims>] [--top-n <1..200>] [--team-id <id>] (memory:read)。
- 診断とプロファイリング: doctor [--anonymous] (no scope required), profile [--status <later|never>] (no scope required)。

```bash
# Memory read and write operations:
node scripts/xmemo-skill.mjs remember --content "Production build uses node 22.22" --path "ops/build"
node scripts/xmemo-skill.mjs recall --query "build node version" --limit 3
node scripts/xmemo-skill.mjs read --id mem_01hxyz... --offset 0 --limit 1000
node scripts/xmemo-skill.mjs update --id mem_01hxyz... --content "Production build uses node 22.22.0 LTS"
node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm

# Context assembly with optional Knowledge inclusion:
node scripts/xmemo-skill.mjs recall-context --query "TLS root configuration" --include_knowledge true

# Task continuity and restart snapshots:
node scripts/xmemo-skill.mjs save-state --key active_task --content "Refactoring migration script"
node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928

# Ledger and analytics:
node scripts/xmemo-skill.mjs expense-add --item "Cloud hosting" --amount 120 --currency USD
node scripts/xmemo-skill.mjs overview
node scripts/xmemo-skill.mjs doctor
```

## 決定論的終了コード

すべてのstandalone Skillコマンドは、対話型およびプログラムによる実行全体で厳格かつ決定論的な終了コードに準拠します。

- コード0（成功）: 操作が成功した、有効な空の結果セットが返された、--help、または --version。
- コード1（ユーザーエラー）: パラメータ検証エラー、相互排他的な引数、524,288バイトを超えるコンテンツ、forget時の必須の --confirm の欠落、入力ファイルの欠落/読み取り不可、またはHTTP 4xx応答。
- コード2（認証エラー）: credentialの欠落、期限切れまたは無効なtoken、HTTP 401 Unauthorized、HTTP 403 Forbidden、またはdoctor認証検証の失敗。
- コード3（サーバー / ネットワークエラー）: HTTP 5xx応答、ネットワーク接続の失敗（ECONNREFUSED、ENOTFOUND、ETIMEDOUT）、または安全上限を超える応答ペイロード（> 8 MiB）。

## コンテンツの安全性、ドキュメントスタブ、および削除の確認

standalone Skillは、データの安全性とクライアントの安定性を確保するために、ネットワークリクエストを発行する前に厳格なガードレールを適用します。

- 512 KiBの書き込み上限: 記憶コンテンツは524,288バイト（MAX_MEMORY_CONTENT_BYTES）に制限されています。この上限を超える入力は、ネットワークリクエストがディスパッチされる前にコード1で直ちに終了します。
- 相互排他的な入力ソース: remember は --content <text>、--content -（パイプされたstdin）、または --file <path> を受け入れます。複数のソースを指定すると、終了コード1でローカルで中止されます。
- ドキュメントに基づく記憶スタブ: recall または search がドキュメントに基づく記憶と一致すると、コンパクトな1行スタブ（Document-backed memory: <title>）が返されます。--expand-documents を渡すと最大3つのスタブかつ合計最大20,000文字まで展開されます。または、対象を絞ったページネーション読み取りには read --id <id> を使用します。
- 必須確認ガード: forget --id <id> --confirm には厳格に --confirm が必要です。このフラグを省略すると、ネットワークリクエストなしで終了コード1でローカルで中止されます。
- グローバル実行オプション: すべてのコマンドは --json（未加工のJSON出力）、--terminal（パイプ時に人間向けフォーマットを維持）、--timeout-ms <ms>、--base-url <url>、および --version を受け入れます。