@thinkingai/ae-cli 6.0.24 → 6.0.27

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

@@ -0,0 +1,39 @@
+# agent +accept-skill-share (Accept Skill Share)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Share (peer-to-peer) / write**
+
+## Use Cases
+- Accept a received Skill share.
+- Endpoint: `POST /api/sandbox/agent/skills/shares/[id]/accept`.
+- Accepting creates an independent personal copy of the Skill for the recipient.
+- 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 accepted.
+
+## Command
+```bash
+ae-cli agent +accept-skill-share --id <share-cuid> --yes
+ae-cli agent +accept-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) — `+share-skill` takes a Skill ID instead.
+- Use this after receiving a share (`+list-skill-shares --direction received --status pending`).
+- Accepting creates an independent personal copy; the source Skill is unaffected.
+- Cannot accept 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` → `+accept-skill-share` → `+list-skills` (verify the new copy)

package/skills/ae-agent/references/add-attachment.md

@@ -0,0 +1,57 @@
+# agent +add-attachment (Upload Attachments)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Attachments / write**
+
+## Use Cases
+- Upload sandbox file(s) to the attachment library.
+- Endpoint: `POST /api/sandbox/agent/attachments/upload`.
+- Supports single-file (`--file`) or batch (`--files`) uploads.
+- MIME type is inferred from the file extension.
+
+## Mandatory Rules (MUST)
+- Exactly one of `--file` or `--files` must be provided (they are mutually exclusive).
+- `--files` must be a valid JSON array of string paths, e.g. `'["./a.png","./b.pdf"]'`.
+- Each file must exist on disk; non-existent paths raise an error.
+- Attachment upload supports files up to 50MB each, with a 1GB user quota.
+- Batch uploads support partial success — individual file failures don't affect others.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+# Single file
+ae-cli agent +add-attachment --file ./output/report.png --yes
+
+# Multiple files
+ae-cli agent +add-attachment --files '["./report.png", "./data.csv", "./chart.pdf"]' --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +add-attachment --dry-run --file ./output/report.png
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--file` | No* | Single file path |
+| `--files` | No* | JSON array of file paths, e.g. `'["./a.png","./b.pdf"]'` |
+
+\* Exactly one of `--file` or `--files` is required.
+
+## Decision Rules
+- For a single file, use `--file`; for multiple files, use `--files` with a JSON array.
+- Do not pass both `--file` and `--files` — they are mutually exclusive.
+- Verify file paths exist before uploading; the CLI reads them from disk.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Supported MIME Types (inferred from extension)
+`.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` `.pdf` `.md` `.txt` `.csv` `.json` `.html` `.xml` `.doc` `.docx` `.xls` `.xlsx` `.pptx` `.zip` (others fall back to `application/octet-stream`).
+
+## Next Steps on Failure
+- `--file and --files cannot be used together`: pick one.
+- `File not found: <path>`: verify the path and that the file exists.
+- `--files must be a valid JSON array`: check the JSON syntax.
+- Partial failure in batch: check the response for per-file errors; successful files are still uploaded.
+
+## Recommended Chaining
+- `+add-attachment` → `+list-attachments` (verify)

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

@@ -0,0 +1,75 @@
+# agent +add-mcp (Add MCP Server)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Servers / write**
+
+## Use Cases
+- Add an MCP server to the personal or company scope.
+- Returns the newly created MCP server object including its `id`.
+- `--scope personal` (default) creates a personal MCP server; `--scope company` creates a company MCP server (requires root/agent_admin).
+- Optional market meta (`--category` / `--icon-emoji` / `--icon-color`) is applied via a follow-up PATCH to `/api/sandbox/agent/mcp-servers/[id]/meta`.
+
+## Mandatory Rules (MUST)
+- `--name` and `--url` are required.
+- `--name` must start with a letter and contain only letters, digits, `_`, or `-` (2–64 chars).
+- `--url` must be a valid `http://` or `https://` URL (file://, ftp://, and other protocols are blocked).
+- `--transport` must be `sse` or `http` (default `http`).
+- `--headers` must be a valid JSON object when provided.
+- `--category` must be one of the market category keys (see below) when provided.
+- **MCP creation does NOT validate server connectivity** — an unreachable URL is accepted at create time and only fails when the agent calls the MCP at runtime. Double-check the URL.
+- `--scope` controls target scope: `personal` (default) or `company`. Company scope requires root/agent_admin.
+- 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 +add-mcp \
+  --name my-mcp \
+  --url "https://mcp.example.com/mcp" \
+  --transport http \
+  --headers '{"Authorization":"Bearer token"}'
+
+# With market category and icon
+ae-cli agent +add-mcp \
+  --name my-mcp \
+  --url "https://mcp.example.com/mcp" \
+  --transport http \
+  --headers '{"Authorization":"Bearer token"}' \
+  --category dev_tool \
+  --icon-emoji robot \
+  --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +add-mcp --dry-run --name my-mcp --url "https://mcp.example.com/mcp"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--name` | Yes | Server name (2–64 chars, letter start, `[a-zA-Z0-9_-]`) |
+| `--url` | Yes | MCP server URL (`http://` or `https://` only) |
+| `--display-name` | No | Display name (max 100) |
+| `--description` | No | Description (max 255) |
+| `--transport` | No | `sse` \| `http` (default `http`) |
+| `--headers` | No | HTTP headers as JSON object |
+| `--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`) |
+| `--scope` | No | Target scope: `personal` (default) or `company` (requires root/agent_admin) |
+
+## Decision Rules
+- If the user provides an MCP spec, map the server identifier to `--name` and the endpoint to `--url`.
+- Always verify the URL is reachable before creating — the CLI will not check connectivity.
+- `--category` / `--icon-emoji` / `--icon-color` are optional market meta; they are applied via a follow-up PATCH after creation. If the meta update fails, the MCP is still created and a warning is printed to stderr.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `--name must start with a letter...`: rename the server to match the pattern.
+- `--url only supports http:// or https:// protocols`: switch to an http(s) URL.
+- Warning `MCP created but meta update failed`: the MCP exists; retry the meta with `+set-mcp-meta`.
+
+## Recommended Chaining
+- `+list-mcp-market` (browse) → `+add-mcp` → `+list-mcps` (verify) → `+set-mcp-meta` (adjust meta)

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

@@ -0,0 +1,70 @@
+# agent +add-model (Add Custom Model)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Models / write**
+
+## Use Cases
+- Add a custom model to the personal or company scope.
+- Returns the newly created model object including its `id`.
+- `--scope personal` (default) creates a personal model; `--scope company` creates a company model (requires root/agent_admin).
+
+## Mandatory Rules (MUST)
+- `--model-id`, `--name`, and `--base-url` are required.
+- `--base-url` must be a valid URL.
+- `--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
+ae-cli agent +add-model \
+  --model-id gpt-4o \
+  --name "GPT-4o" \
+  --base-url "https://api.openai.com/v1" \
+  --api-key "sk-xxx" \
+  --provider openai
+
+ae-cli agent +add-model \
+  --model-id claude-sonnet \
+  --name "Claude Sonnet" \
+  --base-url "https://api.anthropic.com/v1" \
+  --provider anthropic \
+  --context-length 200000 \
+  --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +add-model --dry-run --model-id gpt-4o --name "GPT-4o" --base-url "https://api.openai.com/v1"
+
+# Company scope (requires root/agent_admin)
+ae-cli agent +add-model \
+  --model-id gpt-4o-company \
+  --name "GPT-4o (company)" \
+  --base-url "https://api.openai.com/v1" \
+  --provider openai \
+  --scope company \
+  --yes
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--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 |
+| `--provider` | No | Provider name |
+| `--description` | No | Description |
+| `--context-length` | No | Context window length |
+| `--scope` | No | Target scope: `personal` (default) or `company` (requires root/agent_admin) |
+
+## Decision Rules
+- If the user provides a model spec, map the model identifier to `--model-id` and the human name to `--name`.
+- `--api-key` is optional at the CLI level but usually required by the upstream provider; pass it when the user supplies one.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `--base-url must be a valid URL`: check the URL formatting.
+- After success, capture the returned `id` for `+toggle-model` / `+del-model` calls.
+
+## Recommended Chaining
+- `+list-models` (verify) → `+add-model` → `+toggle-model` (enable) → `+create-automation --model <id>`

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

@@ -0,0 +1,71 @@
+# agent +add-skill (Create Custom Skill)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skills / write**
+
+## Use Cases
+- Create a custom Skill in the personal or company scope.
+- Returns the newly created Skill object including its `id`.
+- `--scope personal` (default) creates a personal Skill; `--scope company` creates a company Skill (requires root/agent_admin). Company scope bypasses the submit-approve flow — the Skill is directly created as a company asset (consistent with `+upload-skill --scope company`).
+- Optional market meta (`--category` / `--icon-emoji` / `--icon-color`) is applied via a follow-up PATCH to `/api/sandbox/agent/skills/[id]/meta`.
+
+## Mandatory Rules (MUST)
+- `--name`, `--description`, and `--instructions` are required.
+- `--name` must be 1–80 chars.
+- `--instructions` supports `@-` to read from stdin (useful for piping long instruction text).
+- `--category` must be one of the market category keys (see below) when provided.
+- `--scope` controls target scope: `personal` (default) or `company`. Company scope requires root/agent_admin and bypasses the submit-approve flow (directly creates a company Skill, consistent with `+upload-skill --scope company`).
+- 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
+# Inline instructions
+ae-cli agent +add-skill \
+  --name code-reviewer \
+  --description "Reviews code for best practices" \
+  --instructions "You are a code reviewer. Analyze the code for..."
+
+# Instructions from stdin (useful for long text)
+echo "You are a helpful assistant that..." | \
+  ae-cli agent +add-skill --name helper --description "Helper skill" --instructions @-
+
+# With market category and icon
+ae-cli agent +add-skill \
+  --name code-reviewer \
+  --description "Reviews code for best practices" \
+  --instructions "You are a code reviewer..." \
+  --category dev_tool \
+  --icon-emoji robot \
+  --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +add-skill --dry-run --name helper --description "Helper" --instructions "x"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--name` | Yes | Skill name (1–80 chars) |
+| `--description` | Yes | Skill description |
+| `--instructions` | Yes | Skill instructions (use `@-` to read from stdin) |
+| `--display-name` | No | Display name (max 100) |
+| `--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`) |
+| `--scope` | No | Target scope: `personal` (default) or `company` (requires root/agent_admin; bypasses submit-approve flow) |
+
+## Decision Rules
+- If the user provides long instruction text, pipe it via stdin with `--instructions @-` instead of an oversized inline string.
+- `--category` / `--icon-emoji` / `--icon-color` are optional market meta; they are applied via a follow-up PATCH after creation. If the meta update fails, the Skill is still created and a warning is printed to stderr.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `stdin is empty; cannot read instructions`: ensure stdin has content when using `@-`.
+- Warning `Skill created but meta update failed`: the Skill exists; retry the meta with `+set-skill-meta`.
+
+## Recommended Chaining
+- `+add-skill` → `+list-skills` (verify) → `+set-skill-meta` (adjust meta) → `+submit-skill` (publish) or `+share-skill` (peer share)

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

@@ -0,0 +1,41 @@
+# agent +approve-skill (Approve Skill Submission)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Approval (company-scope publish) / write**
+
+## Use Cases
+- Approve a pending Skill submission (root only).
+- Endpoint: `POST /api/sandbox/agent/skills/submissions/[id]/approve`.
+- Approving creates an independent company-scope copy of the Skill.
+- 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.
+- **Root only** — non-root users cannot approve submissions.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Only `pending` submissions can be approved.
+
+## Command
+```bash
+ae-cli agent +approve-skill --id <submission-cuid> --yes
+ae-cli agent +approve-skill --dry-run --id <submission-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Submission record ID (CUID) |
+
+## Decision Rules
+- `--id` here is a submission ID (not a Skill ID).
+- Use this after reviewing a pending submission (`+list-skill-submissions --status pending`).
+- Approving creates a company-scope copy; the original personal Skill remains.
+- Cannot approve a submission that is already `approved` / `rejected` / `cancelled`.
+
+## Next Steps on Failure
+- `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` → `+approve-skill` (or `+reject-skill`)

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

@@ -0,0 +1,50 @@
+# agent +attachment-stats (Attachment Library Statistics)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Attachments / read**
+
+## Use Cases
+- Show the current user's attachment library statistics: total file count, total size, image count, document count.
+- Endpoint: `GET /api/sandbox/agent/attachments/stats`.
+- No parameters; returns a single statistics object for the authenticated user's own data.
+
+## Mandatory Rules (MUST)
+- No flags. The command always returns the current user's own attachment statistics.
+
+## Command
+```bash
+ae-cli agent +attachment-stats
+
+# Dry-run to inspect the request
+ae-cli agent +attachment-stats --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| _(none)_ | — | This command takes no flags. |
+
+## Response Shape
+```json
+{
+  "totalCount": 42,
+  "totalSize": 10485760,
+  "imageCount": 15,
+  "documentCount": 27
+}
+```
+
+| Field | Description |
+|---|---|
+| `totalCount` | Total number of ready attachments |
+| `totalSize` | Total size in bytes (sum of all ready attachments) |
+| `imageCount` | Number of image attachments (type=image) |
+| `documentCount` | Number of document attachments (type=document) |
+
+## Next Steps on Failure
+- `500` 获取附件统计失败: an internal aggregation error — retry, then contact the platform maintainer if it persists.
+
+## Recommended Chaining
+- `+attachment-stats` (overview) → `+list-attachments` (drill into the list)
+- `+add-attachment` (upload) → `+attachment-stats` (verify totals changed)

package/skills/ae-agent/references/auto-provision-mcp-credentials.md

@@ -0,0 +1,57 @@
+# agent +auto-provision-mcp-credentials (Auto-Provision MCP Credentials)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **MCP Credentials / write**
+
+## Use Cases
+- Auto-provision per-user credentials for all system-scope MCP servers in one call.
+- Endpoint: `POST /api/sandbox/agent/mcp-credentials/auto-provision`.
+- Uses the current user's access token to mint MCP tokens via the central token-generation endpoint.
+- For `useMcpToken=true` system servers, a shared MCP token is generated and stored; for OAuth system servers, the access token is stored as the credential.
+
+## Mandatory Rules (MUST)
+- `--access-token` is optional; when omitted, the current session token is used automatically (via `ctx.token()`).
+- The access token must be valid — an invalid/expired token causes the MCP token generation to fail (reported via `mcpTokenFailed: true` in the response).
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- This is a bulk operation — it upserts credentials for ALL system MCP servers visible to the current user.
+
+## Command
+```bash
+# Auto-provision using the current session token (recommended)
+ae-cli agent +auto-provision-mcp-credentials --yes
+
+# Explicitly pass an access token
+ae-cli agent +auto-provision-mcp-credentials --access-token "eyJhbGci..." --yes
+
+# Dry-run to inspect the request
+ae-cli agent +auto-provision-mcp-credentials --dry-run
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--access-token` | No | Access token (defaults to the current session token) |
+
+## Decision Rules
+- If the user wants to set up all system MCP credentials in one step, use this command.
+- Prefer running without `--access-token` — the CLI automatically sources the current session token.
+- The response reports `count` (total system servers processed), `mcpTokenCount` (servers that got a shared MCP token), and `mcpTokenFailed` (whether the MCP token generation failed).
+- If `mcpTokenFailed` is `true`, the MCP token endpoint may be down or the access token invalid — check the access token and retry.
+- For individual credential control, use `+set-mcp-credential` instead.
+
+## Response Shape
+```json
+{
+  "count": 3,
+  "mcpTokenCount": 1,
+  "mcpTokenFailed": false
+}
+```
+
+## Next Steps on Failure
+- `401` / auth expired: run `ae-cli auth login`, then retry.
+- `mcpTokenFailed: true`: the MCP token generation failed — verify the access token is valid and the MCP token endpoint is configured.
+
+## Recommended Chaining
+- `ae-cli auth login` → `+auto-provision-mcp-credentials` → `+list-mcp-credentials` (verify) → `+mcp-token` (get shared token)

package/skills/ae-agent/references/cancel-skill-submission.md

@@ -0,0 +1,39 @@
+# agent +cancel-skill-submission (Cancel Skill Submission)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Skill Approval (company-scope publish) / write**
+
+## Use Cases
+- Cancel a pending Skill submission.
+- Endpoint: `POST /api/sandbox/agent/skills/submissions/[id]/cancel`.
+- Only pending submissions can be cancelled; the submitter or root can cancel.
+- 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.
+- Only the submitter or root can cancel a submission.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+
+## Command
+```bash
+ae-cli agent +cancel-skill-submission --id <submission-cuid> --yes
+ae-cli agent +cancel-skill-submission --dry-run --id <submission-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Submission record ID (CUID) |
+
+## Decision Rules
+- `--id` here is a submission ID (not a Skill ID) — `+submit-skill` / `+share-skill` / `+copy-skill` take a Skill ID instead.
+- Use this when the submitter wants to withdraw a pending submission before review.
+- Cannot cancel a submission that is already `approved` / `rejected` / `cancelled`.
+
+## Next Steps on Failure
+- `404` / not found: re-run `+list-skill-submissions --status pending` to verify the submission ID.
+- Permission error: only the submitter or root can cancel.
+
+## Recommended Chaining
+- `+list-skill-submissions --status pending` → confirm submission `id` → `+cancel-skill-submission`

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

@@ -0,0 +1,53 @@
+# agent +copy-skill (Copy Skill to Personal)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Copy to personal / write**
+
+## Use Cases
+- Copy a system/company Skill to an independent personal copy.
+- Endpoint: `POST /api/sandbox/agent/skills/[id]/copy`.
+- The copy is an independent duplicate — changes to the source do not affect the copy and vice versa.
+- Optional `--category` / `--icon-emoji` / `--icon-color` override the copy's market meta; omit them to inherit the source's.
+
+## Mandatory Rules (MUST)
+- `--id` is required. Obtain the real source Skill record ID (CUID, system or company scope) via `+list-skill-market` or `+list-skills` — do not guess.
+- `--category` must be one of the market category keys (see below) when provided.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- MCP has no copy flow (use `+toggle-mcp` to enable a system/company MCP per-user).
+
+## Market Category Keys
+`ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`
+
+## Command
+```bash
+# Copy with inherited meta
+ae-cli agent +copy-skill --id <skill-cuid> --yes
+
+# Copy with overridden category and icon
+ae-cli agent +copy-skill --id <skill-cuid> --category dev_tool --icon-emoji robot --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +copy-skill --dry-run --id <skill-cuid>
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--id` | Yes | Source Skill record ID (CUID, system or company scope) |
+| `--category` | No | Market category key for the copy (see above) |
+| `--icon-emoji` | No | Override market icon emoji (e.g. `robot`) |
+| `--icon-color` | No | Override market icon color (e.g. `#1E76F0`) |
+
+## Decision Rules
+- If the user wants a personal version of a system/company Skill, use `+copy-skill` (not `+add-skill`).
+- Omit `--category` / `--icon-emoji` / `--icon-color` to inherit the source's meta; provide them to override.
+- MCP has no copy — to use a system/company MCP, toggle it on per-user with `+toggle-mcp`.
+- Use `--dry-run` first to verify the request shape before executing.
+
+## Next Steps on Failure
+- `--category must be one of...`: use one of the category keys.
+- `404` / not found: re-run `+list-skill-market` / `+list-skills` to verify the source Skill ID and scope.
+
+## Recommended Chaining
+- `+list-skill-market` (browse) → `+copy-skill` (copy to personal) → `+list-skills` (verify) → `+set-skill-meta` (adjust)

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

@@ -0,0 +1,71 @@
+# agent +create-agent (Create Agent)
+
+> **Prerequisite:** Follow the Global AE CLI Rules in [`../SKILL.md`](../SKILL.md).
+
+Domain: **Agents / write**
+
+## Use Cases
+- Create a new Agent in the personal scope (default) or company scope (requires root/agent_admin).
+- Returns the newly created Agent object including its `id`.
+- Wire up an existing model, MCP servers, and Skills in one call.
+
+## Mandatory Rules (MUST)
+- `--name` is required (1–100 chars).
+- `--scope` defaults to `personal`; `company` requires root/agent_admin privileges.
+- `--instructions` maps to the Agent's system prompt; supports `@-` to read from stdin.
+- `--mcp-ids` / `--skill-ids` must be JSON array strings when provided.
+- Write operation: keep the confirmation prompt unless `--yes` is explicitly requested.
+- Do not guess model / MCP / Skill IDs. Discover them with `+list-*` commands first.
+
+## Command
+```bash
+# Minimal create
+ae-cli agent +create-agent --name "daily-report" --description "Daily report agent"
+
+# With model, MCP servers, and Skills
+ae-cli agent +create-agent \
+  --name "daily-report" \
+  --description "Daily report agent" \
+  --model-id "cm1uuid" \
+  --mcp-ids '["mcp-cuid-1","mcp-cuid-2"]' \
+  --skill-ids '["skill-cuid-1"]' \
+  --yes
+
+# Instructions from stdin (useful for long prompts)
+echo "You are a helpful assistant that..." | \
+  ae-cli agent +create-agent --name helper --instructions @-
+
+# Auto-rename on name conflict (appends -1, -2, ...)
+ae-cli agent +create-agent --name "daily-report" --auto-rename --yes
+
+# Dry-run to inspect the request before executing
+ae-cli agent +create-agent --dry-run --name "daily-report" --description "x"
+```
+
+## Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `--name` | Yes | Agent name (1–100 chars) |
+| `--description` | No | Agent description (max 2000 chars) |
+| `--instructions` | No | Agent system prompt (use `@-` to read from stdin) |
+| `--scope` | No | `personal` \| `company` (default `personal`; `company` requires root/agent_admin) |
+| `--model-id` | No | Model identifier (`Model.id` uuid or legacy `modelId`); omit to use the global default |
+| `--mcp-ids` | No | MCP server record IDs as JSON array string (e.g. `["id1","id2"]`) |
+| `--skill-ids` | No | Skill record IDs as JSON array string |
+| `--auto-rename` | No | Auto-rename on name conflict (append `-N` suffix) |
+
+## Decision Rules
+- If the user provides long instruction text, pipe it via stdin with `--instructions @-` instead of an oversized inline string.
+- `--model-id` accepts both the model record UUID and the legacy model identifier; the server resolves and stores the UUID. Omit it to use the global default model.
+- `--mcp-ids` / `--skill-ids` replace the full list on create; pass `[]` or omit to leave the list empty.
+- Use `--dry-run` first to verify the request shape before executing.
+- On name conflict, the server returns `409 NAME_EXISTS`; pass `--auto-rename` to auto-resolve.
+
+## Next Steps on Failure
+- `Agent 名称已存在` (409): re-run with `--auto-rename`, or pick a different `--name`.
+- `模型不存在或已删除`: verify the model ID with `+list-models`.
+- `MCP 数量超过上限` / `Skill 数量超过上限`: reduce the IDs in `--mcp-ids` / `--skill-ids`.
+- `stdin is empty; cannot read instructions`: ensure stdin has content when using `@-`.
+
+## Recommended Chaining
+- `+list-models` / `+list-mcps` / `+list-skills` (discover IDs) → `+create-agent` → `+get-agent` (verify) → `+create-automation --agent-id <id>`