@thinkingai/ae-cli 6.0.24 → 6.0.28

package/skills/ae-agent/references/toggle-model.md

@@ -0,0 +1,37 @@
+# agent +toggle-model (Toggle Model)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Models / write**
+
+## Use Cases
+- Enable or disable a model.
+- Toggle operations on company/system resources only affect the current user's preference, not the global state.
+
+## Mandatory Rules (MUST)
+- `--id` and `--enabled` are required.
+- Obtain the real model record ID (CUID) via `+list-models` — do not guess.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+ae-cli agent +toggle-model --id <model-cuid> --enabled true --yes
+ae-cli agent +toggle-model --id <model-cuid> --enabled false --yes
+ae-cli agent +toggle-model --dry-run --id <model-cuid> --enabled false
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Model record ID (CUID) |
+| `--enabled` | Yes | `true` to enable, `false` to disable |
+
+## Decision Rules
+- If the user wants to turn a model on/off, use `--enabled true` / `--enabled false`.
+- Toggling a company/system model only changes the current user's preference.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-models` to verify the model ID.
+
+## Recommended Chaining
+- `+list-models` → confirm `id` → `+toggle-model`

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

@@ -0,0 +1,37 @@
+# agent +toggle-skill (Toggle Skill)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Enable or disable a Skill.
+- Toggle operations on company/system resources only affect the current user's preference, not the global state.
+
+## Mandatory Rules (MUST)
+- `--id` and `--enabled` are required.
+- Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+ae-cli agent +toggle-skill --id <skill-cuid> --enabled true --yes
+ae-cli agent +toggle-skill --id <skill-cuid> --enabled false --yes
+ae-cli agent +toggle-skill --dry-run --id <skill-cuid> --enabled false
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--enabled` | Yes | `true` to enable, `false` to disable |
+
+## Decision Rules
+- If the user wants to turn a Skill on/off, use `--enabled true` / `--enabled false`.
+- Toggling a company/system Skill only changes the current user's preference.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skills` to verify the Skill ID.
+
+## Recommended Chaining
+- `+list-skills` → confirm `id` → `+toggle-skill`

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

@@ -0,0 +1,71 @@
+# agent +update-agent (Update Agent)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Agents / write**
+
+## Use Cases
+- Update an existing Agent's name, description, system prompt, model, MCP servers, Skills, or enabled state.
+- Only the fields you pass are changed; omitted fields keep their current values.
+- `--enabled` on a system/company Agent writes the current user's personal preference (does not change the global state).
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Agent record ID (CUID) via `+list-agents` — do not guess.
+- Only `personal` Agents can be fully edited by their owner; `company` Agents require root.
+- `--instructions` supports `@-` to read from stdin.
+- `--mcp-ids` / `--skill-ids` must be JSON array strings when provided; they replace the full list.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- PATCH does NOT support `--auto-rename`; a name conflict returns `409`.
+
+## Command
+```bash
+# Rename
+ae-cli agent +update-agent --id <agent-cuid> --name "new-name" --yes
+
+# Replace instructions from stdin
+echo "You are now a code reviewer..." | \
+  ae-cli agent +update-agent --id <agent-cuid> --instructions @-
+
+# Swap model and MCP list
+ae-cli agent +update-agent \
+  --id <agent-cuid> \
+  --model-id "cm1newuuid" \
+  --mcp-ids '["mcp-cuid-new"]'
+
+# Enable a system/company Agent (writes personal preference)
+ae-cli agent +update-agent --id <agent-cuid> --enabled true
+
+# Disable
+ae-cli agent +update-agent --id <agent-cuid> --enabled false
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-agent --dry-run --id <agent-cuid> --name "new-name"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Agent record ID (CUID) |
+| `--name` | No | New Agent name (1–100 chars) |
+| `--description` | No | New description (max 2000 chars) |
+| `--instructions` | No | New system prompt (use `@-` to read from stdin) |
+| `--model-id` | No | New model identifier (uuid or legacy modelId); omit to keep |
+| `--mcp-ids` | No | MCP server record IDs as JSON array string (replaces the list; `[]` clears) |
+| `--skill-ids` | No | Skill record IDs as JSON array string (replaces the list; `[]` clears) |
+| `--enabled` | No | `true` to enable, `false` to disable (system/company: personal preference) |
+
+## Decision Rules
+- Confirm the Agent ID with `+list-agents` (or `+get-agent`) before updating.
+- `--enabled` is optional; omit it to leave the enabled state unchanged. Pass `--enabled true` / `--enabled false` explicitly to toggle.
+- `--mcp-ids` / `--skill-ids` replace the entire list on update — pass the full new set, not just additions.
+- Use `--dry-run` first to verify the request shape before executing.
+- To rename safely without `409`, check for name conflicts first or use `+create-agent --auto-rename` (PATCH has no auto-rename).
+
+## Next Steps on Failure
+- `404` / `Agent 不存在`: re-run `+list-agents` to verify the Agent ID.
+- `403` / `无权编辑该 Agent`: the Agent is not yours and you are not root.
+- `409` / `NAME_EXISTS`: pick a different `--name` (PATCH cannot auto-rename).
+- `模型不存在或已删除`: verify the model ID with `+list-models`.
+
+## Recommended Chaining
+- `+list-agents` → confirm `id` → `+update-agent` → `+get-agent` (verify)

package/skills/ae-agent/references/update-automation.md

@@ -0,0 +1,83 @@
+# agent +update-automation (Update Automation)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Automations / write**
+
+## Use Cases
+- Update an existing Agent automation task's name, instruction, schedule, or enabled state.
+- Used to pause (`--enabled false`) or resume (`--enabled true`) an automation, or to change its schedule/message.
+- Obtain the automation `id` via `+list-automations` — never guess.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real ID via `+list-automations` — do not guess.
+- At least one update field must be provided (`--name`, `--message`, `--enabled`, `--cron`, or a `--schedule-kind` with its time/day fields).
+- `--cron` and `--schedule-kind` are mutually exclusive.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies.
+
+## Schedule Kinds (when updating schedule)
+| `--schedule-kind` | Required fields | Notes |
+|---|---|---|
+| `hourly` | `--minute` (optional, 0–59) | Runs every hour at the given minute |
+| `daily` | `--time HH:mm` | Runs once a day at the given time |
+| `weekly` | `--time HH:mm`, `--weekday 0-6` | `0` = Sunday |
+| `monthly` | `--time HH:mm`, `--day-of-month 1-28` | Day 1–28 only |
+
+## Command
+```bash
+# Pause an automation
+ae-cli agent +update-automation --id <automation-id> --enabled false --yes
+
+# Resume an automation
+ae-cli agent +update-automation --id <automation-id> --enabled true --yes
+
+# Rename and change the instruction
+ae-cli agent +update-automation \
+  --id <automation-id> \
+  --name "Daily AI Brief v2" \
+  --message "Summarize yesterday's AI news and trends" \
+  --yes
+
+# Change the schedule to weekly on Sunday
+ae-cli agent +update-automation \
+  --id <automation-id> \
+  --schedule-kind weekly \
+  --time 10:00 \
+  --weekday 0 \
+  --yes
+
+# Switch to a cron expression
+ae-cli agent +update-automation --id <automation-id> --cron "0 9 * * 1-5" --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-automation --dry-run --id <automation-id> --enabled false
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Automation task ID from `+list-automations` |
+| `--name` | No | New automation task name |
+| `--message` | No | New instruction sent to the Agent |
+| `--enabled` | No | `true` to enable, `false` to pause |
+| `--cron` | No | Cron expression (mutually exclusive with `--schedule-kind`) |
+| `--schedule-kind` | No | `hourly` \| `daily` \| `weekly` \| `monthly` |
+| `--time` | No | Time in `HH:mm` for daily/weekly/monthly |
+| `--minute` | No | Minute 0–59 for hourly schedules |
+| `--weekday` | No | Weekday 0–6 for weekly schedules; `0` is Sunday |
+| `--day-of-month` | No | Day 1–28 for monthly schedules |
+
+## Decision Rules
+- If the user wants to pause/resume, use `--enabled false` / `--enabled true` (no other fields needed).
+- If the user wants to change the schedule, provide `--schedule-kind` with its required time/day fields, or `--cron`.
+- At least one update field is required; a bare `--id` is rejected.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `至少提供一个更新字段`: add at least one of `--name` / `--message` / `--enabled` / `--cron` / `--schedule-kind`.
+- `必须提供 --cron 或 --schedule-kind`: if schedule detail flags (`--time` / `--minute` / `--weekday` / `--day-of-month`) are present, a `--schedule-kind` (or `--cron`) must accompany them.
+- `--time 格式必须是 HH:mm`: use 24-hour `HH:mm` (e.g. `09:00`).
+
+## Recommended Chaining
+- `+list-automations` → `+update-automation`

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

@@ -0,0 +1,79 @@
+# agent +update-mcp (Update MCP Server Config)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Update an existing MCP server's configuration (name, URL, transport, headers, auth mode, etc.).
+- Endpoint: `PATCH /api/sandbox/agent/mcp-servers/[id]`.
+- Personal scope: requires ownership. Company scope: requires root. System scope: read-only.
+- Includes connectivity validation and OAuth reauth cascade when relevant.
+- Use `--auto-rename` to auto-rename on name conflict instead of returning a 409.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real MCP server record ID (CUID) via `+list-mcps` — do not guess.
+- At least one update field must be provided (aside from `--id`).
+- `--name` (when provided) must start with a letter and contain only letters, digits, `_`, or `-` (2–64 chars).
+- `--url` (when provided) must be a valid `http://` or `https://` URL (file://, ftp://, and other protocols are blocked).
+- `--transport` (when provided) must be `sse`, `http`, or `streamable-http` (stdio is disabled by policy on the sandbox endpoint).
+- `--auth-mode` (when provided) must be `none`, `oauth2`, `header`, or `manual`.
+- `--enabled` accepts `true` or `false`; **omit it to leave the enabled state unchanged**. To simply toggle, prefer `+toggle-mcp`.
+- `--headers` / `--secret-headers` must be valid JSON objects when provided. `--secret-headers` values are encrypted server-side.
+- The server runs a connectivity check on update; an unreachable URL fails with `connectivity_failed`.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Rename + update URL
+ae-cli agent +update-mcp --id <mcp-cuid> --name my-mcp-renamed --url "https://mcp.example.com/mcp" --yes
+
+# Update transport + headers
+ae-cli agent +update-mcp --id <mcp-cuid> --transport streamable-http --headers '{"Authorization":"Bearer token"}'
+
+# Enable with auto-rename on conflict
+ae-cli agent +update-mcp --id <mcp-cuid> --enabled true --auto-rename --yes
+
+# Disable (explicit)
+ae-cli agent +update-mcp --id <mcp-cuid> --enabled false --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-mcp --dry-run --id <mcp-cuid> --name new-name
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | MCP server record ID (CUID) |
+| `--name` | No* | Server name (2–64 chars, letter start, `[a-zA-Z0-9_-]`) |
+| `--url` | No* | MCP server URL (`http://` or `https://` only) |
+| `--display-name` | No* | Display name (max 100) |
+| `--description` | No* | Description (max 255) |
+| `--transport` | No* | `sse` \| `http` \| `streamable-http` |
+| `--headers` | No* | HTTP headers as JSON object |
+| `--secret-headers` | No* | Secret headers as JSON object (encrypted server-side) |
+| `--auth-mode` | No* | `none` \| `oauth2` \| `header` \| `manual` |
+| `--enabled` | No* | `true` \| `false` (omit to leave unchanged) |
+| `--auto-rename` | No* | Auto-rename on name conflict (default `false`) |
+
+\* At least one of these must be provided.
+
+## Decision Rules
+- If the user wants to change any MCP config field, use this command.
+- To only enable/disable an MCP (no other changes), prefer `+toggle-mcp` — it is simpler and has no connectivity check.
+- `--enabled` is a string (`true`/`false`), not a boolean flag, so that omitting it leaves the state unchanged.
+- If the server returns `NAME_EXISTS` (409), re-run with `--auto-rename` or pick a different `--name`.
+- After updating URL/transport/headers, the server re-validates connectivity; if it fails, the old config is preserved.
+- Updating OAuth-related fields (URL, auth mode, secret headers) may trigger a reauth cascade — affected credentials are expired and `reauthRequired` / `reauthCredentialCount` are returned in the response.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-mcps` to verify the server ID and scope.
+- `403` company_admin_only: the current user is not root (company-scope update).
+- `403` system_mcp_readonly: system-scope MCPs cannot be updated.
+- `409` NAME_EXISTS: re-run with `--auto-rename` or a different `--name`.
+- `400` connectivity_failed: verify the URL is reachable and transport is correct.
+- `400` needs_auth: refresh credentials first (`+mcp-auth-start`), then re-enable.
+
+## Recommended Chaining
+- `+list-mcps` → confirm `id` → `+update-mcp`
+- `+update-mcp` → (if reauth required) → `+mcp-auth-start` → `+mcp-auth-status`

package/skills/ae-agent/references/update-model.md

@@ -0,0 +1,77 @@
+# agent +update-model (Update Custom Model)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Models / write**
+
+## Use Cases
+- Update an existing custom model (the `--id` determines which record to update).
+- All connection/display fields can be changed; `--api-key` may be omitted to preserve the stored key.
+- Encouraged to verify connectivity with `+test-model` first, then pass `--connectivity-verified true`.
+- `--scope` controls target scope: `personal` (default) or `company`. Company scope requires root/agent_admin.
+
+## Mandatory Rules (MUST)
+- `--id`, `--model-id`, `--name`, and `--base-url` are required.
+- `--base-url` must be a valid URL.
+- `--api-key` is optional; omit or leave empty to preserve the existing key (do NOT pass an empty string to clear — the stored key is kept).
+- `--scope` controls target scope: `personal` (default) or `company`. Company scope requires root/agent_admin; system models are read-only.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Update display name and provider
+ae-cli agent +update-model \
+  --id <model-cuid> \
+  --model-id gpt-4o \
+  --name "GPT-4o (prod)" \
+  --base-url "https://api.openai.com/v1" \
+  --provider openai \
+  --yes
+
+# Rotate the API key
+ae-cli agent +update-model \
+  --id <model-cuid> \
+  --model-id gpt-4o \
+  --name "GPT-4o" \
+  --base-url "https://api.openai.com/v1" \
+  --api-key "sk-newkey" \
+  --connectivity-verified true
+
+# Dry-run to inspect the request before executing
+ae-cli agent +update-model --dry-run \
+  --id <model-cuid> \
+  --model-id gpt-4o \
+  --name "GPT-4o" \
+  --base-url "https://api.openai.com/v1"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Model record ID (CUID) to update |
+| `--model-id` | Yes | Model identifier (e.g. `gpt-4o`) |
+| `--name` | Yes | Display name |
+| `--base-url` | Yes | API base URL (must be a valid URL) |
+| `--api-key` | No | API key; omit or empty to preserve the existing key |
+| `--provider` | No | Provider name |
+| `--description` | No | Description |
+| `--context-length` | No | Context window length (positive integer) |
+| `--connectivity-verified` | No | Whether connectivity was verified (default `false`; pass `true` after `+test-model`) |
+| `--auto-rename` | No | Auto-rename on display name conflict (append `-N` suffix) |
+| `--scope` | No | Target scope: `personal` (default) or `company` (requires root/agent_admin) |
+
+## Decision Rules
+- Confirm the model ID with `+list-models` before updating.
+- To rotate the API key, pass `--api-key <new>`; to keep the stored key, simply omit `--api-key`.
+- `--connectivity-verified` defaults to `false`. After a successful `+test-model`, pass `--connectivity-verified true` to confirm the new connection config.
+- On display name conflict, the server returns `409`; pass `--auto-rename` to auto-resolve.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `模型不存在` (404): re-run `+list-models` to verify the model ID and scope.
+- `模型名称已存在` (409): re-run with `--auto-rename`, or pick a different `--name`.
+- `--base-url must be a valid URL`: check the URL formatting.
+- `仅支持 LLM 类型模型测试` (from `+test-model`): the provider maps to a non-LLM type and cannot be tested.
+
+## Recommended Chaining
+- `+list-models` → confirm `id` → `+test-model` (verify connectivity) → `+update-model --connectivity-verified true` → `+list-models` (verify)

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

@@ -0,0 +1,49 @@
+# agent +upload-skill-asset (Upload Skill Asset)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Upload a single file to a Skill's `assets` directory (multipart upload).
+- Endpoint: `POST /api/sandbox/agent/skills/[id]/assets` (multipart/form-data).
+- Max file size: 1MB per file.
+- Dangerous file types are rejected server-side.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- `--file` is required and must point to an existing local file.
+- Max 1MB per file; server enforces `isDangerousFile` checks.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Upload a single asset
+ae-cli agent +upload-skill-asset --id <skill-cuid> --file ./icon.png --yes
+
+# Upload to a sub-directory
+ae-cli agent +upload-skill-asset --id <skill-cuid> --file ./data.csv --sub-path "sub/" --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +upload-skill-asset --dry-run --id <skill-cuid> --file ./icon.png
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--file` | Yes | Local file path to upload (max 1MB) |
+| `--sub-path` | No | Sub-directory under assets (e.g. `"sub/"`) |
+
+## Decision Rules
+- Verify the file exists locally before uploading.
+- Use `--sub-path` to organize assets into sub-directories.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `File not found`: verify the local file path.
+- `文件过大（上限 1MB）`: the file exceeds the 1MB limit — compress or split it.
+- `禁止上传危险文件类型`: the file type is blocked by server-side security checks.
+
+## Recommended Chaining
+- `+list-skills` → `+list-skill-assets` → `+upload-skill-asset` → `+list-skill-assets` (verify)

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

@@ -0,0 +1,51 @@
+# agent +upload-skill-reference (Upload Skill Reference)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Upload a single `.md` file to a Skill's `references` directory (multipart upload).
+- Endpoint: `POST /api/sandbox/agent/skills/[id]/references` (multipart/form-data).
+- Max file size: 1MB per file.
+- **Only `.md` files are allowed** — other extensions are rejected.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- `--file` is required, must be an existing local `.md` file.
+- Non-`.md` files are rejected — use `+upload-skill-asset` for other file types.
+- Max 1MB per file; server enforces `isDangerousFile` checks.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Upload a single reference
+ae-cli agent +upload-skill-reference --id <skill-cuid> --file ./guide.md --yes
+
+# Upload to a sub-directory
+ae-cli agent +upload-skill-reference --id <skill-cuid> --file ./advanced.md --sub-path "advanced/" --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +upload-skill-reference --dry-run --id <skill-cuid> --file ./guide.md
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--file` | Yes | Local `.md` file path to upload (max 1MB) |
+| `--sub-path` | No | Sub-directory under references (e.g. `"advanced/"`) |
+
+## Decision Rules
+- Verify the file exists locally and has a `.md` extension before uploading.
+- For non-markdown files, use `+upload-skill-asset` instead.
+- Use `--sub-path` to organize references into sub-directories.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `File not found`: verify the local file path.
+- `--file must be a .md file for references`: use `+upload-skill-asset` for non-markdown files.
+- `文件过大（上限 1MB）`: the file exceeds the 1MB limit — split the markdown.
+
+## Recommended Chaining
+- `+list-skills` → `+list-skill-references` → `+upload-skill-reference` → `+list-skill-references` (verify)

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

@@ -0,0 +1,49 @@
+# agent +upload-skill-script (Upload Skill Script)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Upload a single file to a Skill's `scripts` directory (multipart upload).
+- Endpoint: `POST /api/sandbox/agent/skills/[id]/scripts` (multipart/form-data).
+- Max file size: 1MB per file.
+- Dangerous file types are rejected server-side.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real Skill record ID (CUID) via `+list-skills` — do not guess.
+- `--file` is required and must point to an existing local file.
+- Max 1MB per file; server enforces `isDangerousFile` checks.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Upload a single script
+ae-cli agent +upload-skill-script --id <skill-cuid> --file ./helper.sh --yes
+
+# Upload to a sub-directory
+ae-cli agent +upload-skill-script --id <skill-cuid> --file ./run.py --sub-path "tools/" --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +upload-skill-script --dry-run --id <skill-cuid> --file ./helper.sh
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Skill record ID (CUID) |
+| `--file` | Yes | Local file path to upload (max 1MB) |
+| `--sub-path` | No | Sub-directory under scripts (e.g. `"tools/"`) |
+
+## Decision Rules
+- Verify the file exists locally before uploading.
+- Use `--sub-path` to organize scripts into sub-directories.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `File not found`: verify the local file path.
+- `文件过大（上限 1MB）`: the file exceeds the 1MB limit — compress or split it.
+- `禁止上传危险文件类型`: the file type is blocked by server-side security checks.
+
+## Recommended Chaining
+- `+list-skills` → `+list-skill-scripts` → `+upload-skill-script` → `+list-skill-scripts` (verify)

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

@@ -0,0 +1,89 @@
+# agent +upload-skill (Upload ZIP Skill)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Upload a ZIP-format Skill package. The server parses SKILL.md from the ZIP, extracts files to the target directory, and writes the DB record.
+- Endpoint: `POST /api/sandbox/agent/skills/upload` (multipart/form-data, 120s timeout).
+- Supports form-field overrides for name, displayName, description, instructions, icon, category.
+- `--scope` controls target scope: `personal` (default) or `company`.
+- `--replace-skill-id` replaces an existing Skill instead of creating a new one.
+- `--auto-rename` auto-renames on name conflict.
+
+## Mandatory Rules (MUST)
+- `--file` is required and must be a `.zip` file that exists on disk.
+- The ZIP must contain a `SKILL.md` file (with name and content at minimum).
+- `--scope` must be `personal` or `company` (default `personal`).
+- `--category` must be one of the market category keys when provided.
+- `--instructions` supports `@-` to read from stdin.
+- 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
+# Upload a personal Skill from ZIP
+ae-cli agent +upload-skill --file ./my-skill.zip --yes
+
+# Upload with overrides
+ae-cli agent +upload-skill \
+  --file ./my-skill.zip \
+  --scope personal \
+  --name custom-name \
+  --display-name "Custom Skill" \
+  --description "Override description" \
+  --category dev_tool \
+  --icon-emoji robot \
+  --yes
+
+# Instructions from stdin
+echo "You are a helpful assistant..." | \
+  ae-cli agent +upload-skill --file ./my-skill.zip --instructions @- --yes
+
+# Replace an existing Skill
+ae-cli agent +upload-skill --file ./updated.zip --replace-skill-id <skill-cuid> --yes
+
+# Auto-rename on conflict
+ae-cli agent +upload-skill --file ./my-skill.zip --auto-rename --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +upload-skill --dry-run --file ./my-skill.zip
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--file` | Yes | Local `.zip` file path |
+| `--scope` | No | Target scope: `personal` (default) or `company` |
+| `--auto-rename` | No | Auto-rename on name conflict |
+| `--replace-skill-id` | No | Replace an existing Skill (CUID) instead of creating new |
+| `--category` | No | Market category key (see above) |
+| `--name` | No | Override Skill name (from ZIP SKILL.md if omitted) |
+| `--display-name` | No | Override display name |
+| `--description` | No | Override description |
+| `--instructions` | No | Override instructions (use `@-` to read from stdin) |
+| `--icon-emoji` | No | Market icon emoji (e.g. `robot`) |
+| `--icon-color` | No | Market icon color (e.g. `#1E76F0`) |
+
+## Decision Rules
+- The ZIP must contain a `SKILL.md` with at least `name` and content — otherwise the upload fails with `missing_skill_md` or `missing_name_or_content`.
+- Form-field overrides take precedence over ZIP SKILL.md content.
+- Use `--replace-skill-id` to update an existing Skill's full content from a ZIP (different from `+edit-skill` which edits individual fields).
+- Use `--auto-rename` when the Skill name might conflict with an existing one.
+- `company` scope requires root privileges.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `File not found`: verify the local file path.
+- `--file must be a .zip file`: only ZIP format is supported.
+- `ZIP 中缺少 SKILL.md`: ensure the ZIP contains a `SKILL.md` file.
+- `缺少名称或内容`: the SKILL.md is missing the `name` field or content — fix the ZIP.
+- `缺少描述`: the SKILL.md is missing the description — fix the ZIP or use `--description`.
+- `数据库写入失败`: DB write failed — retry or check server logs.
+- `409` / name conflict: use `--auto-rename` or choose a different `--name`.
+
+## Recommended Chaining
+- `+upload-skill` → `+list-skills` (verify) → `+get-skill-content` (inspect) → `+edit-skill` (fine-tune) → `+submit-skill` (publish)