@thinkingai/ae-cli 6.0.24 → 6.0.27

package/skills/ae-agent/references/mcp-stats.md

@@ -0,0 +1,68 @@
+# agent +mcp-stats (MCP Call Statistics)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / read**
+
+## Use Cases
+- Show MCP tool call statistics for the current user over the last N days.
+- Endpoint: `GET /api/sandbox/agent/mcp-servers/stats`.
+- Returns aggregations: total calls, by-server, daily, and daily-by-server.
+
+## Mandatory Rules (MUST)
+- `--days` must be an integer between 1 and 365 when provided; defaults to 30.
+- Statistics are scoped to the authenticated user's own MCP usage.
+
+## Command
+```bash
+# Default: last 30 days
+ae-cli agent +mcp-stats
+
+# Last 7 days
+ae-cli agent +mcp-stats --days 7
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-stats --dry-run --days 7
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--days` | No | Lookback window in days (1-365, default 30) |
+
+## Response Shape
+```json
+{
+  "days": 30,
+  "totalCalls": 128,
+  "byServer": { "clxxx-server-a": 80, "clxxx-server-b": 48 },
+  "daily": [
+    { "date": "2026-06-07", "calls": 5 },
+    { "date": "2026-06-08", "calls": 0 }
+  ],
+  "dailyByServer": {
+    "clxxx-server-a": { "2026-06-07": 3, "2026-06-08": 0 }
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `days` | The lookback window used for this query |
+| `totalCalls` | Sum of all MCP tool calls over the window |
+| `byServer` | Map of `mcpServerId` → call count |
+| `daily` | Array of `{ date, calls }` for each day in the window (oldest → newest) |
+| `dailyByServer` | Map of `mcpServerId` → `{ date: calls }` |
+
+## Decision Rules
+- Use `--days 7` for a weekly review, `--days 30` (default) for a monthly review.
+- `daily` always contains one entry per day in the window (zero-filled), so it is safe to chart directly.
+- `byServer` only contains servers with at least one call in the window; cross-reference IDs with `+list-mcps` to resolve names.
+
+## Next Steps on Failure
+- `--days must be an integer between 1 and 365`: pass an integer in range.
+- `500` 获取 MCP 调用统计失败: an internal aggregation error — retry, then contact the platform maintainer if it persists.
+
+## Recommended Chaining
+- `+mcp-stats` (which servers are active) → `+list-mcps` (resolve server IDs to names)
+- `+mcp-stats` (low/no calls) → `+mcp-tools` (verify the server exposes tools) → `+mcp-auth-start` if `needs_auth`

package/skills/ae-agent/references/mcp-token.md

@@ -0,0 +1,63 @@
+# agent +mcp-token (Get MCP Token)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Credentials / read**
+
+## Use Cases
+- Get the plaintext MCP token for `useMcpToken=true` system MCP servers.
+- Endpoint: `GET /api/sandbox/agent/mcp-credentials/mcp-token`.
+- All such servers share one token; the server decrypts and returns it.
+- This is a product behavior (consistent with the web UI) — the token is returned in plaintext so it can be used as a Bearer credential for MCP API calls.
+
+## Mandatory Rules (MUST)
+- No flags required.
+- The returned token is **plaintext** — handle it as a secret:
+  - Do NOT write it to shell history (avoid `export MCP_TOKEN=$(ae-cli agent +mcp-token)` without precautions).
+  - Do NOT log it or commit it to version control.
+  - Prefer piping directly to the consuming process or a secure store.
+- The command prints a security warning to stderr (when a TTY is detected) reminding the user to safeguard the token.
+
+## Command
+```bash
+# Get the MCP token (prints to stdout as JSON)
+ae-cli agent +mcp-token
+
+# Pipe to a file (avoid shell history)
+ae-cli agent +mcp-token --format json > /dev/shm/mcp-token.json 2>/dev/null
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-token --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| (none) | — | — |
+
+## Decision Rules
+- If the user needs the shared MCP token to call MCP-enabled APIs, use this command.
+- The token is shared across all `useMcpToken=true` system MCP servers — a single call returns it.
+- If `token` is `null`, no credential has been provisioned yet — run `+auto-provision-mcp-credentials` first.
+- Prefer `+list-mcp-credentials` to check credential status without exposing the plaintext token.
+
+## Response Shape
+```json
+{
+  "token": "mcp-xxxxxxxxxxxxxxxx"
+}
+```
+
+When no token is provisioned:
+```json
+{
+  "token": null
+}
+```
+
+## Next Steps on Failure
+- `401` / auth expired: run `ae-cli auth login`.
+- `token: null`: run `+auto-provision-mcp-credentials` to provision the token first.
+
+## Recommended Chaining
+- `+auto-provision-mcp-credentials` (provision) → `+mcp-token` (retrieve) → use as `Authorization: bearer <token>` for MCP API calls

package/skills/ae-agent/references/mcp-tools.md

@@ -0,0 +1,55 @@
+# agent +mcp-tools (List MCP Server Tools)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / read**
+
+## Use Cases
+- List the tools exposed by an MCP server (name, description, input schema).
+- Endpoint: `GET /api/sandbox/agent/mcp-servers/[id]/tools`.
+- Includes OAuth auto-refresh: if the credential is about to expire, the server attempts a refresh before listing tools.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- The MCP server must be enabled and properly configured; otherwise the server returns a structured error.
+
+## Command
+```bash
+ae-cli agent +mcp-tools --id <mcp-cuid>
+
+# Dry-run to inspect the request
+ae-cli agent +mcp-tools --dry-run --id <mcp-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+
+## Decision Rules
+- If the user wants to see what tools an MCP server provides, use this command.
+- The response includes `server` (id, name, transport) and `tools` (array of `{name, description, inputSchema}`).
+- If the server returns `needs_auth` (400), run `+mcp-auth-start` to start OAuth, then retry.
+- If the server returns `reauth_required` (428), the credential has expired — run `+mcp-auth-start` to re-authorize.
+- If the server returns `disabled` (400), enable the MCP first with `+toggle-mcp --enabled true`.
+
+## Response Shape
+```json
+{
+  "server": { "id": "clxxx", "name": "my-mcp", "transport": "http" },
+  "tools": [
+    { "name": "search", "description": "Search the web", "inputSchema": { "type": "object", "properties": {} } }
+  ]
+}
+```
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID.
+- `400` needs_auth: run `+mcp-auth-start --id <id>`, then poll `+mcp-auth-status`.
+- `428` reauth_required: credential expired — run `+mcp-auth-start` to re-authorize.
+- `400` disabled: run `+toggle-mcp --id <id> --enabled true`.
+- `502` connection_failed: verify the MCP server URL is reachable.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+mcp-tools`
+- `+mcp-tools` (fails needs_auth) → `+mcp-auth-start` → `+mcp-auth-status` → `+mcp-tools`

package/skills/ae-agent/references/read-skill-asset.md

@@ -0,0 +1,51 @@
+# agent +read-skill-asset (Read Skill Asset)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- Read a Skill asset file's raw binary content (binary-safe).
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/assets/[...path]`.
+- By default returns `{ content, fileName }` where content is best-effort UTF-8 text.
+- Use `--output <path>` to save the raw binary content to a local file (preserves binary data).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- `--path` is required and specifies the relative file path within the assets directory.
+- For binary files (images, PDFs, etc.), always use `--output` to avoid UTF-8 corruption.
+
+## Command
+```bash
+# Read a text asset (default JSON output)
+ae-cli agent +read-skill-asset --id <skill-cuid> --path guide.txt
+
+# Save binary asset to local file
+ae-cli agent +read-skill-asset --id <skill-cuid> --path icon.png --output ./icon.png
+
+# Read from a sub-directory
+ae-cli agent +read-skill-asset --id <skill-cuid> --path "sub/data.csv" --output ./data.csv
+
+# Dry-run to inspect the request before executing
+ae-cli agent +read-skill-asset --dry-run --id <skill-cuid> --path icon.png
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--path` | Yes | Relative file path within assets (e.g. `"icon.png"` or `"sub/data.csv"`) |
+| `--output` | No | Write binary content to a local file (preserves binary data) |
+
+## Decision Rules
+- Use `+list-skill-assets` to discover available file paths before reading.
+- For text files (.md, .txt, .csv, .json), the default JSON output `{ content }` is sufficient.
+- For binary files (.png, .pdf, .zip, etc.), always use `--output <path>` to save to disk — the default text output may corrupt binary data.
+- Read operation: no confirmation prompt needed.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skill-assets` to verify the file path.
+- `文件不存在`: the file path does not exist in the assets directory.
+
+## Recommended Chaining
+- `+list-skill-assets` → confirm `path` → `+read-skill-asset --output` → `+del-skill-asset` (if cleanup needed)

package/skills/ae-agent/references/read-skill-reference.md

@@ -0,0 +1,50 @@
+# agent +read-skill-reference (Read Skill Reference)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- Read a Skill reference `.md` file's raw content (binary-safe).
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/references/[...path]`.
+- By default returns `{ content, fileName }` where content is UTF-8 text.
+- Use `--output <path>` to save the raw content to a local file.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- `--path` is required and specifies the relative file path within the references directory.
+
+## Command
+```bash
+# Read a reference (default JSON output)
+ae-cli agent +read-skill-reference --id <skill-cuid> --path guide.md
+
+# Save reference to local file
+ae-cli agent +read-skill-reference --id <skill-cuid> --path guide.md --output ./guide.md
+
+# Read from a sub-directory
+ae-cli agent +read-skill-reference --id <skill-cuid> --path "advanced/tips.md"
+
+# Dry-run to inspect the request before executing
+ae-cli agent +read-skill-reference --dry-run --id <skill-cuid> --path guide.md
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--path` | Yes | Relative file path within references (e.g. `"guide.md"` or `"advanced/tips.md"`) |
+| `--output` | No | Write content to a local file |
+
+## Decision Rules
+- Use `+list-skill-references` to discover available file paths before reading.
+- References are `.md` files — the default JSON output `{ content }` is usually sufficient.
+- Use `--output` to save the content to a local file for editing or backup.
+- Read operation: no confirmation prompt needed.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skill-references` to verify the file path.
+- `文件不存在`: the file path does not exist in the references directory.
+
+## Recommended Chaining
+- `+list-skill-references` → confirm `path` → `+read-skill-reference` → `+del-skill-reference` (if cleanup needed)

package/skills/ae-agent/references/read-skill-script.md

@@ -0,0 +1,51 @@
+# agent +read-skill-script (Read Skill Script)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / read**
+
+## Use Cases
+- Read a Skill script file's raw binary content (binary-safe).
+- Endpoint: `GET /api/sandbox/agent/skills/[id]/scripts/[...path]`.
+- By default returns `{ content, fileName }` where content is best-effort UTF-8 text.
+- Use `--output <path>` to save the raw binary content to a local file (preserves binary data).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- `--path` is required and specifies the relative file path within the scripts directory.
+- For binary files, always use `--output` to avoid UTF-8 corruption.
+
+## Command
+```bash
+# Read a text script (default JSON output)
+ae-cli agent +read-skill-script --id <skill-cuid> --path helper.sh
+
+# Save binary script to local file
+ae-cli agent +read-skill-script --id <skill-cuid> --path tool.bin --output ./tool.bin
+
+# Read from a sub-directory
+ae-cli agent +read-skill-script --id <skill-cuid> --path "tools/run.py"
+
+# Dry-run to inspect the request before executing
+ae-cli agent +read-skill-script --dry-run --id <skill-cuid> --path helper.sh
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--path` | Yes | Relative file path within scripts (e.g. `"helper.sh"` or `"tools/run.py"`) |
+| `--output` | No | Write binary content to a local file (preserves binary data) |
+
+## Decision Rules
+- Use `+list-skill-scripts` to discover available file paths before reading.
+- For text files (.sh, .py, .js, etc.), the default JSON output `{ content }` is sufficient.
+- For binary files, always use `--output <path>` to save to disk.
+- Read operation: no confirmation prompt needed.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skill-scripts` to verify the file path.
+- `文件不存在`: the file path does not exist in the scripts directory.
+
+## Recommended Chaining
+- `+list-skill-scripts` → confirm `path` → `+read-skill-script --output` → `+del-skill-script` (if cleanup needed)

package/skills/ae-agent/references/reject-skill-share.md

@@ -0,0 +1,37 @@
+# agent +reject-skill-share (Reject Skill Share)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Share (peer-to-peer) / write**
+
+## Use Cases
+- Reject a received Skill share.
+- Endpoint: `POST /api/sandbox/agent/skills/shares/[id]/reject`.
+- Sharing is Skill-only — MCP has no share flow.
+
+## Mandatory Rules (MUST)
+- `--id` is required and must reference a **share** record (CUID), not a Skill ID. Obtain it via `+list-skill-shares --direction received` — do not guess.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Only `pending` shares can be rejected.
+
+## Command
+```bash
+ae-cli agent +reject-skill-share --id <share-cuid> --yes
+ae-cli agent +reject-skill-share --dry-run --id <share-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Share record ID (CUID) |
+
+## Decision Rules
+- `--id` here is a share ID (not a Skill ID).
+- Use this when the recipient does not want to accept a pending share.
+- Cannot reject a share that is already `accepted` / `rejected`.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skill-shares --direction received --status pending` to verify the share ID.
+
+## Recommended Chaining
+- `+list-skill-shares --direction received --status pending` → confirm share `id` → `+reject-skill-share` (or `+accept-skill-share`)

package/skills/ae-agent/references/reject-skill.md

@@ -0,0 +1,42 @@
+# agent +reject-skill (Reject Skill Submission)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Approval (company-scope publish) / write**
+
+## Use Cases
+- Reject a pending Skill submission with a reason (root only).
+- Endpoint: `POST /api/sandbox/agent/skills/submissions/[id]/reject`.
+- Approval is Skill-only — MCP has no approval flow.
+
+## Mandatory Rules (MUST)
+- `--id` is required and must reference a **submission** record (CUID), not a Skill ID. Obtain it via `+list-skill-submissions` — do not guess.
+- `--reason` is required (1–80 chars) — the rejection reason.
+- **Root only** — non-root users cannot reject submissions.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Only `pending` submissions can be rejected.
+
+## Command
+```bash
+ae-cli agent +reject-skill --id <submission-cuid> --reason "Needs more detail" --yes
+ae-cli agent +reject-skill --dry-run --id <submission-cuid> --reason "Needs more detail"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Submission record ID (CUID) |
+| `--reason` | Yes | Rejection reason (1–80 chars) |
+
+## Decision Rules
+- `--id` here is a submission ID (not a Skill ID).
+- Use this after reviewing a pending submission (`+list-skill-submissions --status pending`) when the submission should not be published.
+- Cannot reject a submission that is already `approved` / `rejected` / `cancelled`.
+
+## Next Steps on Failure
+- `--reason length must be between 1 and 80`: adjust the reason length.
+- `404` / not found: re-run `+list-skill-submissions --status pending` to verify the submission ID.
+- Permission error: the current user is not root.
+
+## Recommended Chaining
+- `+list-skill-submissions --status pending` → confirm submission `id` → `+reject-skill` (or `+approve-skill`)

package/skills/ae-agent/references/rescan-skills.md

@@ -0,0 +1,44 @@
+# agent +rescan-skills (Rescan Skills)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Rescan Skill files on the server filesystem and sync them to the database.
+- Endpoint: `POST /api/sandbox/agent/skills/rescan`.
+- **Root-only**: requires root privileges; non-root users get a 403.
+- No flags — the scan covers all Skill directories on the server.
+
+## Mandatory Rules (MUST)
+- This command takes no flags.
+- **Root-only operation**: non-root users will receive a 403 error.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Prefer `--dry-run` before executing — rescan has filesystem side effects.
+
+## Command
+```bash
+# Rescan and sync
+ae-cli agent +rescan-skills --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +rescan-skills --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| _(none)_ | — | This command takes no flags |
+
+## Decision Rules
+- Use this command when Skill files on disk are out of sync with the database (e.g. after manual filesystem changes or migration).
+- This is a root-only operation — confirm the user has root privileges before running.
+- The scan covers all Skill directories (system, company, personal) on the server.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `403` / 无权限: the current user is not root — rescan requires root privileges.
+- `扫描同步失败`: the scan encountered filesystem errors — check server logs and Skill directory permissions.
+
+## Recommended Chaining
+- `+rescan-skills` → `+list-skills` (verify the synced state)

package/skills/ae-agent/references/set-mcp-credential.md

@@ -0,0 +1,67 @@
+# agent +set-mcp-credential (Set MCP Credential)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Credentials / write**
+
+## Use Cases
+- Upsert a per-user credential for a system-scope MCP server (by `mcpServerId` + `userId`).
+- Endpoint: `POST /api/sandbox/agent/mcp-credentials`.
+- The `token` (when provided) is encrypted server-side before storage.
+- Use this to manually set an API key or OAuth token for a system MCP server.
+
+## Mandatory Rules (MUST)
+- `--mcp-server-id` is required. Obtain the real system MCP server record ID (CUID) via `+list-mcps` (scope=system) or `+list-mcp-credentials` — do not guess.
+- `--auth-type` defaults to `oauth`; must be `oauth` or `apikey` when provided.
+- `--token` is optional but recommended — without it, only the credential record is created/enabled without a stored token.
+- `--expires-at` (when provided) must be a valid ISO 8601 datetime (e.g. `2026-12-31T23:59:59Z`).
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Set an OAuth token with expiry
+ae-cli agent +set-mcp-credential --mcp-server-id <mcp-cuid> --token "abc123" --expires-at "2026-12-31T23:59:59Z" --yes
+
+# Set an API key (no expiry)
+ae-cli agent +set-mcp-credential --mcp-server-id <mcp-cuid> --auth-type apikey --token "sk-xxx" --yes
+
+# Dry-run to inspect the request
+ae-cli agent +set-mcp-credential --dry-run --mcp-server-id <mcp-cuid> --token "abc123"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--mcp-server-id` | Yes | System MCP server record ID (CUID) |
+| `--auth-type` | No | `oauth` \| `apikey` (default `oauth`) |
+| `--token` | No | Token / API key (plaintext; encrypted server-side) |
+| `--expires-at` | No | ISO 8601 datetime (e.g. `2026-12-31T23:59:59Z`) |
+
+## Decision Rules
+- If the user wants to manually set a token/API key for a system MCP server, use this command.
+- For OAuth-based servers, prefer `+mcp-auth-start` (full OAuth flow with auto-refresh). Use `+set-mcp-credential` only when you have a pre-obtained token.
+- For API-key-based servers (`--auth-type apikey`), this is the primary way to set the key.
+- The token is encrypted at rest; it is never returned in plaintext via `+list-mcp-credentials` (use `+mcp-token` for useMcpToken servers).
+- To bulk-provision credentials for all system MCP servers at once, use `+auto-provision-mcp-credentials`.
+
+## Response Shape
+```json
+{
+  "item": {
+    "mcpServerId": "clxxx",
+    "userId": "uyyy",
+    "authType": "oauth",
+    "enabled": true,
+    "expiresAt": "2026-12-31T23:59:59.000Z",
+    "hasToken": true
+  }
+}
+```
+
+## Next Steps on Failure
+- `404` not_found_or_forbidden: the MCP server does not exist or is not a system-scope server.
+- `401` / auth expired: run `ae-cli auth login`.
+
+## Recommended Chaining
+- `+list-mcp-credentials` (check) → `+set-mcp-credential` (set) → `+list-mcp-credentials` (verify)
+- For OAuth servers: `+mcp-auth-start` (preferred) → `+mcp-auth-status` → `+mcp-tools`

package/skills/ae-agent/references/set-mcp-meta.md

@@ -0,0 +1,52 @@
+# agent +set-mcp-meta (Set MCP Market Meta)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Category & Icon (meta) / write**
+
+## Use Cases
+- Update an MCP server's market category and/or icon.
+- Endpoint: `PATCH /api/sandbox/agent/mcp-servers/[id]/meta`.
+- Company scope requires root; system scope is read-only.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- At least one of `--category` / `--icon-emoji` / `--icon-color` must be provided.
+- `--category` must be one of the market category keys (see below) when provided.
+- Company scope meta requires root; system scope meta is read-only.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Command
+```bash
+ae-cli agent +set-mcp-meta --id <mcp-cuid> --category dev_tool --icon-emoji robot --yes
+ae-cli agent +set-mcp-meta --id <mcp-cuid> --icon-color "#1E76F0"
+ae-cli agent +set-mcp-meta --id <mcp-cuid> --category data_query
+ae-cli agent +set-mcp-meta --dry-run --id <mcp-cuid> --category dev_tool
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+| `--category` | No* | Market category key (see above) |
+| `--icon-emoji` | No* | Market icon emoji (e.g. `robot`) |
+| `--icon-color` | No* | Market icon color (e.g. `#1E76F0`) |
+
+\* At least one of these three must be provided.
+
+## Decision Rules
+- If the user wants to change an MCP server's market category or icon, use this.
+- For company-scope MCP servers, only root users can set meta; for system-scope, meta is read-only.
+- `+add-mcp` also accepts `--category` / `--icon-emoji` / `--icon-color` at creation; use `+set-mcp-meta` to adjust them afterwards.
+
+## Next Steps on Failure
+- `Provide at least one of --category / --icon-emoji / --icon-color`: add at least one meta field.
+- `--category must be one of...`: use one of the category keys.
+- Permission error on company scope: the current user is not root.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+set-mcp-meta`
+- `+add-mcp` → `+set-mcp-meta` (adjust meta after creation)

package/skills/ae-agent/references/set-skill-meta.md

@@ -0,0 +1,51 @@
+# agent +set-skill-meta (Set Skill Market Meta)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Category & Icon (meta) / write**
+
+## Use Cases
+- Update a Skill's market category and/or icon.
+- Endpoint: `PATCH /api/sandbox/agent/skills/[id]/meta`.
+- Company scope requires root; system scope is read-only.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- At least one of `--category` / `--icon-emoji` / `--icon-color` must be provided.
+- `--category` must be one of the market category keys (see below) when provided.
+- Company scope meta requires root; system scope meta is read-only.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Command
+```bash
+ae-cli agent +set-skill-meta --id <skill-cuid> --category data_query --yes
+ae-cli agent +set-skill-meta --id <skill-cuid> --icon-emoji robot --icon-color "#1E76F0"
+ae-cli agent +set-skill-meta --dry-run --id <skill-cuid> --category dev_tool
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--category` | No* | Market category key (see above) |
+| `--icon-emoji` | No* | Market icon emoji (e.g. `robot`) |
+| `--icon-color` | No* | Market icon color (e.g. `#1E76F0`) |
+
+\* At least one of these three must be provided.
+
+## Decision Rules
+- If the user wants to change a Skill's market category or icon, use this.
+- For company-scope Skills, only root users can set meta; for system-scope, meta is read-only.
+- `+add-skill` and `+copy-skill` also accept `--category` / `--icon-emoji` / `--icon-color`; use `+set-skill-meta` to adjust them afterwards.
+
+## Next Steps on Failure
+- `Provide at least one of --category / --icon-emoji / --icon-color`: add at least one meta field.
+- `--category must be one of...`: use one of the category keys.
+- Permission error on company scope: the current user is not root.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+set-skill-meta`
+- `+add-skill` / `+copy-skill` → `+set-skill-meta` (adjust meta after creation/copy)