@thinkingai/ae-cli 6.0.24 → 6.0.28

package/skills/ae-agent/SKILL.md

@@ -1,174 +1,205 @@
 ---
 name: ae-agent
-version: 1.1.0
+version: 1.2.0
 description: "AE Agent platform resource management CLI for listing Agents, creating and updating automations, adding/removing/listing/toggling custom models, MCP servers, Skills, uploading sandbox files to the attachment library, browsing the MCP/Skill market, setting market category/icon, copying system/company Skills to personal, and submitting/approving/sharing Skills. Use when the user asks to manage Agent platform resources, browse the market, or create scheduled Agent automations. Must use ae-cli agent commands."
 ---
 
 # ae-agent
 
+> **CRITICAL — Before running any `+<command>` command, you MUST first read the corresponding `references/<command>.md`.** The reference filename equals the command name without the leading `+`, for example `+add-mcp` → `references/add-mcp.md`.
+> **CRITICAL — Never guess record IDs (Agent / automation / model / MCP / Skill / submission / share / attachment).** Always use the appropriate `+list-*` command to discover real IDs first.
+> **CRITICAL — All Agent platform resources are served under the `/api/sandbox/agent/*` path.** Do not reference legacy paths.
+
 AE CLI (`ae-cli`) agent platform resource commands are invoked through:
 
 ```bash
 ae-cli agent +<command> [options]
 ```
 
-## Global Rules
+All commands live under the `agent` service. Quick help:
+
+```bash
+ae-cli agent --help
+ae-cli agent +list-agents --help
+ae-cli agent +create-automation --help
+```
+
+## Global AE CLI Rules
 
 - Use this skill for Agent platform resource management: Agents, automations, models, MCP servers, Skills, attachments, the MCP/Skill market, and Skill copy/approval/share flows.
-- Read operations can run directly. Write operations require explicit user intent and normally keep the confirmation prompt unless `--yes` is passed.
-- Prefer `--dry-run` before destructive writes.
-- Only personal scope resources can be created or deleted; company/system resources are read-only in the CLI (exception: root users can approve/reject submissions and set company-scope meta).
+- **Read operations** (`+list-*`) can run directly once required IDs are known.
+- **Write operations** require explicit user intent and keep the confirmation prompt by default. Pass `--yes` only in fully automated pipelines.
+- Prefer `--dry-run` before destructive writes to inspect the request shape without executing.
+- Personal and company scope resources can be created/updated/deleted; company scope requires root/agent_admin role; system resources are read-only (exception: root users can approve/reject submissions and set company-scope meta).
 - Toggle operations on company/system resources only affect the current user's preference, not the global state.
+- Never invent record IDs. Discover them with `+list-*` commands or accept them from the user.
 - JSON flags must be valid JSON strings, usually wrapped in single quotes in shell.
-- Successful commands return JSON by default. Use `--format table` when a table is easier to scan.
-- `--host <url>` overrides the active AE host. It is available on every command and may be placed after the subcommand, e.g. `ae-cli agent +<command> --host <url>`.
 
-## Commands
+### Global Parameters
 
-### Agents
+| Parameter | Description |
+|---|---|
+| `--format <json\|table>` | Output format. Default is JSON. |
+| `--host <url>` | Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli agent +<command> --host <url>`. |
+| `--yes` | Skip confirmation for write operations. |
+| `--dry-run` | Show request details (method + URL + body) without executing. |
 
-| Command        | Risk | Purpose                                                        |
-| -------------- | ---: | -------------------------------------------------------------- |
-| `+list-agents` | read | List Agents visible to current user (personal/company/system). |
+### Output and Errors
 
-### Automations
+- Successful commands return machine-readable JSON by default. Use `--format table` when a table is easier to scan.
+- Failed commands return `{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }` and exit non-zero.
 
-| Command              |  Risk | Purpose                                |
-| -------------------- | ----: | -------------------------------------- |
-| `+create-automation` | write | Create an Agent automation task. |
+## When to Use
 
-### Models
+Use `ae-agent` for all Agent platform resource work:
 
-| Command         |  Risk | Purpose                                                        |
-| --------------- | ----: | -------------------------------------------------------------- |
-| `+list-models`  |  read | List models visible to current user (personal/company/system). |
-| `+add-model`    | write | Add a custom model (personal scope).                           |
-| `+del-model`    | write | Delete a personal model.                                       |
-| `+toggle-model` | write | Enable or disable a model.                                     |
+- **Agents & automations**: list Agents, create / list / update scheduled Agent automations.
+- **Models**: list, add, delete, toggle custom models.
+- **MCP servers**: list, add, delete, toggle MCP servers; browse the MCP market; set market meta.
+- **Skills**: list, add, delete, toggle Skills; browse the Skill market; set market meta; copy system/company Skills to personal; submit/approve/reject company-scope Skills; share/accept/reject peer-to-peer Skills.
+- **Attachments**: list, upload, soft-delete sandbox files in the attachment library.
 
-### MCP Servers
+If the user's intent is data analysis, audience management, metadata governance, TeamRuns, or knowledge bases, switch to `ae-analysis` / `ae-engage` / `ae-dataops` / `ae-team` / `ae-kb`.
 
-| Command       |  Risk | Purpose                                   |
-| ------------- | ----: | ----------------------------------------- |
-| `+list-mcps`  |  read | List MCP servers visible to current user. |
-| `+add-mcp`    | write | Add an MCP server (personal scope).       |
-| `+del-mcp`    | write | Delete a personal MCP server.             |
-| `+toggle-mcp` | write | Enable or disable an MCP server.          |
+## Tool Groups (66 commands)
 
-### Skills
+### Agents (5)
 
-| Command         |  Risk | Purpose                                    |
-| --------------- | ----: | ------------------------------------------ |
-| `+list-skills`  |  read | List Skills visible to current user.       |
-| `+add-skill`    | write | Create a custom Skill (personal scope).    |
-| `+del-skill`    | write | Delete a personal Skill (physical delete). |
-| `+toggle-skill` | write | Enable or disable a Skill.                 |
+- `+list-agents` ([doc](references/list-agents.md)) — list Agents visible to current user (personal/company/system)
+- `+create-agent` ([doc](references/create-agent.md)) — create a new Agent (personal/company scope; company requires root/agent_admin; name/description/instructions/model/mcp-ids/skill-ids)
+- `+update-agent` ([doc](references/update-agent.md)) — update an Agent's name/description/instructions/model/mcp-ids/skill-ids/enabled
+- `+del-agent` ([doc](references/del-agent.md)) — soft-delete a personal/company Agent (company requires root/agent_admin; system Agents cannot be deleted)
+- `+get-agent` ([doc](references/get-agent.md)) — get a single Agent's detail
 
-### Market (browse)
+### Automations (3)
 
-| Command              | Risk | Purpose                                                                  |
-| -------------------- | ----: | ------------------------------------------------------------------------ |
-| `+list-mcp-market`   | read | List MCP servers from the market (filter by scope/category/search/sort). |
-| `+list-skill-market` | read | List Skills from the market (only approved; same filters).              |
+- `+list-automations` ([doc](references/list-automations.md)) — list current user's Agent automation tasks
+- `+create-automation` ([doc](references/create-automation.md)) — create an Agent automation task (hourly/daily/weekly/monthly or cron)
+- `+update-automation` ([doc](references/update-automation.md)) — update an automation's name, instruction, schedule, or enabled state
 
-### Category & Icon (meta)
+### Models (6)
 
-| Command           |  Risk | Purpose                                                                       |
-| ----------------- | ----: | ----------------------------------------------------------------------------- |
-| `+set-mcp-meta`   | write | Update an MCP server market category/icon. Company requires root; system RO. |
-| `+set-skill-meta` | write | Update a Skill market category/icon. Company requires root; system RO.       |
+- `+list-models` ([doc](references/list-models.md)) — list models visible to current user (personal/company/system)
+- `+add-model` ([doc](references/add-model.md)) — add a custom model (personal/company scope; company requires root/agent_admin)
+- `+update-model` ([doc](references/update-model.md)) — update a custom model (personal/company scope; company requires root/agent_admin; apiKey left blank to keep existing)
+- `+del-model` ([doc](references/del-model.md)) — delete a personal/company model (company requires root/agent_admin)
+- `+toggle-model` ([doc](references/toggle-model.md)) — enable or disable a model
+- `+test-model` ([doc](references/test-model.md)) — test custom model connectivity (LLM only)
 
-### Copy to personal
+### MCP Servers (14)
 
-| Command       |  Risk | Purpose                                                                |
-| ------------- | ----: | ---------------------------------------------------------------------- |
-| `+copy-skill` | write | Copy a system/company Skill to a personal copy (independent duplicate). |
+- `+list-mcps` ([doc](references/list-mcps.md)) — list MCP servers visible to current user
+- `+add-mcp` ([doc](references/add-mcp.md)) — add an MCP server (personal/company scope; company requires root/agent_admin)
+- `+update-mcp` ([doc](references/update-mcp.md)) — update an MCP server's config (url/transport/headers/auth-mode; connectivity validated)
+- `+del-mcp` ([doc](references/del-mcp.md)) — delete a personal MCP server
+- `+toggle-mcp` ([doc](references/toggle-mcp.md)) — enable or disable an MCP server
+- `+mcp-tools` ([doc](references/mcp-tools.md)) — list tools provided by an MCP server (OAuth auto-refresh)
+- `+mcp-auth-start` ([doc](references/mcp-auth-start.md)) — start OAuth authorization (cliMode; print authorizeUrl, then poll with +mcp-auth-status)
+- `+mcp-auth-status` ([doc](references/mcp-auth-status.md)) — query OAuth status (not_required/needs_auth/authenticated/reauth_required/disabled)
+- `+mcp-auth-disconnect` ([doc](references/mcp-auth-disconnect.md)) — disconnect OAuth, clear token and disable
+- `+list-mcp-credentials` ([doc](references/list-mcp-credentials.md)) — list per-user credentials for system MCPs
+- `+set-mcp-credential` ([doc](references/set-mcp-credential.md)) — upsert a per-user MCP credential (oauth/apikey)
+- `+auto-provision-mcp-credentials` ([doc](references/auto-provision-mcp-credentials.md)) — auto-inject credentials for all system MCPs (uses session token by default)
+- `+mcp-token` ([doc](references/mcp-token.md)) — get the shared MCP token (useMcpToken=true; plaintext, mind shell history)
+- `+mcp-stats` ([doc](references/mcp-stats.md)) — MCP call stats for recent N days (`--days` 1-365 default 30; by server / by day)
 
-### Skill Approval (company-scope publish)
+### Skills (4)
 
-| Command                    |  Risk | Purpose                                                            |
-| -------------------------- | ----: | ------------------------------------------------------------------ |
-| `+submit-skill`            | write | Submit a personal Skill for company-scope review.                  |
-| `+list-skill-submissions`  |  read | List submissions (root sees all; others see only their own).       |
-| `+cancel-skill-submission` | write | Cancel a pending submission (submitter or root).                   |
-| `+approve-skill`           | write | Approve a submission (root only). Creates a company-scope copy.    |
-| `+reject-skill`            | write | Reject a submission with a reason (root only).                     |
+- `+list-skills` ([doc](references/list-skills.md)) — list Skills visible to current user
+- `+add-skill` ([doc](references/add-skill.md)) — create a custom Skill (personal/company scope; company requires root/agent_admin)
+- `+del-skill` ([doc](references/del-skill.md)) — delete a personal Skill (physical delete)
+- `+toggle-skill` ([doc](references/toggle-skill.md)) — enable or disable a Skill
 
-### Skill Share (peer-to-peer)
+### Skill content & assets (16)
 
-| Command               |  Risk | Purpose                                                           |
-| --------------------- | ----: | ----------------------------------------------------------------- |
-| `+share-skill`        | write | Share a personal Skill to a same-company user.                    |
-| `+list-skill-shares`  |  read | List Skill shares (received by default; `--direction sent`).     |
-| `+accept-skill-share` | write | Accept a received share (creates a personal copy for recipient).  |
-| `+reject-skill-share` | write | Reject a received share.                                          |
+- `+edit-skill` ([doc](references/edit-skill.md)) — edit a Skill's content (name/description/instructions/category/icon)
+- `+get-skill-content` ([doc](references/get-skill-content.md)) — read a Skill's SKILL.md source
+- `+list-skill-assets` ([doc](references/list-skill-assets.md)) — list asset files of a Skill
+- `+upload-skill-asset` ([doc](references/upload-skill-asset.md)) — upload an asset file (`isDangerousFile` checked; 1MB)
+- `+read-skill-asset` ([doc](references/read-skill-asset.md)) — read an asset file (binary-safe with `--output`)
+- `+del-skill-asset` ([doc](references/del-skill-asset.md)) — delete an asset file
+- `+list-skill-references` ([doc](references/list-skill-references.md)) — list reference files (`.md` only)
+- `+upload-skill-reference` ([doc](references/upload-skill-reference.md)) — upload a reference file (`.md` only; 1MB)
+- `+read-skill-reference` ([doc](references/read-skill-reference.md)) — read a reference file
+- `+del-skill-reference` ([doc](references/del-skill-reference.md)) — delete a reference file
+- `+list-skill-scripts` ([doc](references/list-skill-scripts.md)) — list script files of a Skill
+- `+upload-skill-script` ([doc](references/upload-skill-script.md)) — upload a script file (`isDangerousFile` checked; 1MB)
+- `+read-skill-script` ([doc](references/read-skill-script.md)) — read a script file (binary-safe with `--output`)
+- `+del-skill-script` ([doc](references/del-skill-script.md)) — delete a script file
+- `+upload-skill` ([doc](references/upload-skill.md)) — create/replace a Skill from a ZIP package (parses SKILL.md; 5MB)
+- `+rescan-skills` ([doc](references/rescan-skills.md)) — rescan local filesystem and sync Skills to DB (root only)
 
-### Attachments
+### Market (browse) (2)
 
-| Command             |  Risk | Purpose                                       |
-| ------------------- | ----: | --------------------------------------------- |
-| `+list-attachments` |  read | List user attachments (paginated).            |
-| `+add-attachment`   | write | Upload sandbox file(s) to attachment library. |
-| `+del-attachment`   | write | Soft-delete an attachment.                    |
+- `+list-mcp-market` ([doc](references/list-mcp-market.md)) — list MCP servers from the market (filter by scope/category/search/sort)
+- `+list-skill-market` ([doc](references/list-skill-market.md)) — list Skills from the market (only approved; same filters)
 
-## Usage Examples
+### Category & Icon (meta) (2)
 
-### List all visible models
+- `+set-mcp-meta` ([doc](references/set-mcp-meta.md)) — update an MCP server market category/icon (company requires root; system RO)
+- `+set-skill-meta` ([doc](references/set-skill-meta.md)) — update a Skill market category/icon (company requires root; system RO)
 
-```bash
-ae-cli agent +list-models
-ae-cli agent +list-models --scope personal --format table
-```
+### Copy to personal (1)
 
-### List all visible Agents
+- `+copy-skill` ([doc](references/copy-skill.md)) — copy a system/company Skill to a personal copy (independent duplicate)
 
-```bash
-ae-cli agent +list-agents
-ae-cli agent +list-agents --scope personal --q "daily"
-```
+### Skill Approval (company-scope publish) (5)
 
-### Create an enabled daily automation
+- `+submit-skill` ([doc](references/submit-skill.md)) — submit a personal Skill for company-scope review
+- `+list-skill-submissions` ([doc](references/list-skill-submissions.md)) — list submissions (root sees all; others see only their own)
+- `+cancel-skill-submission` ([doc](references/cancel-skill-submission.md)) — cancel a pending submission (submitter or root)
+- `+approve-skill` ([doc](references/approve-skill.md)) — approve a submission (root only). Creates a company-scope copy
+- `+reject-skill` ([doc](references/reject-skill.md)) — reject a submission with a reason (root only)
 
-```bash
-ae-cli agent +create-automation \
-  --name "Daily AI Brief" \
-  --schedule-kind daily \
-  --time 09:00 \
-  --message "Summarize yesterday's AI news" \
-  --yes
+### Skill Share (peer-to-peer) (4)
 
-# Create but keep paused when the user explicitly asks not to enable it.
+- `+share-skill` ([doc](references/share-skill.md)) — share a personal Skill to a same-company user
+- `+list-skill-shares` ([doc](references/list-skill-shares.md)) — list Skill shares (received by default; `--direction sent`)
+- `+accept-skill-share` ([doc](references/accept-skill-share.md)) — accept a received share (creates a personal copy for recipient)
+- `+reject-skill-share` ([doc](references/reject-skill-share.md)) — reject a received share
+
+### Attachments (4)
+
+- `+list-attachments` ([doc](references/list-attachments.md)) — list user attachments (paginated)
+- `+add-attachment` ([doc](references/add-attachment.md)) — upload sandbox file(s) to attachment library
+- `+del-attachment` ([doc](references/del-attachment.md)) — soft-delete an attachment
+- `+attachment-stats` ([doc](references/attachment-stats.md)) — attachment library stats (total count/size, image/document breakdown)
+
+## Cross-Command Notes
+
+- **Automation IDs**: use `+list-automations` to find the target ID internally, but do not surface raw automation IDs, raw JSON, or concrete detail paths in user-facing replies.
+- **MCP connectivity**: `+add-mcp` 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.
+- **Attachments**: upload supports files up to 50MB each, with a 1GB user quota. Batch uploads support partial success — individual file failures don't affect others.
+- **Skill `--instructions @-`**: reads from stdin, useful for piping long instruction text.
+- **Market category keys**: `ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`. Sort options: `newest | calls | likes` (`calls` sorts MCP by call count, Skill by download count). Market scope: `all | system | company | custom` (`custom` = personal).
+- **Meta on create/copy**: `+add-mcp` / `+add-skill` / `+copy-skill` accept optional `--category / --icon-emoji / --icon-color`; these are applied via a follow-up meta PATCH after creation. MCP creation still does NOT validate server connectivity.
+- **Copy vs toggle**: `+copy-skill` copies a system/company Skill to an independent personal copy. MCP has no copy (use `+toggle-mcp` to enable a system/company MCP per-user).
+- **Approval & share are Skill-only**: MCP has no approval or share flow. `+approve-skill` / `+reject-skill` require root.
+- **`--id` semantics differ by command**: `+submit-skill` / `+share-skill` / `+copy-skill` take a Skill ID; `+cancel-skill-submission` / `+approve-skill` / `+reject-skill` take a submission ID; `+accept-skill-share` / `+reject-skill-share` take a share ID.
+
+## Typical Workflows
+
+### Create a scheduled automation
+
+```bash
+# 1. Discover available Agents
+ae-cli agent +list-agents
+
+# 2. Create an enabled daily automation
 ae-cli agent +create-automation \
   --name "Daily AI Brief" \
   --schedule-kind daily \
   --time 09:00 \
   --message "Summarize yesterday's AI news" \
-  --enabled false \
+  --agent-id <agent-id> \
   --yes
-```
-
-### Add a custom model
 
-```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
-```
-
-### Add an MCP server
-
-```bash
-ae-cli agent +add-mcp \
-  --name my-mcp \
-  --url "https://mcp.example.com/mcp" \
-  --transport http \
-  --headers '{"Authorization":"Bearer token"}'
+# 3. (Optional) Pause or edit later
+ae-cli agent +list-automations --status active
+ae-cli agent +update-automation --id <automation-id> --enabled false --yes
 ```
 
-### Add an MCP with a market category and icon
+### Add an MCP server with market meta
 
 ```bash
 ae-cli agent +add-mcp \
@@ -177,97 +208,35 @@ ae-cli agent +add-mcp \
   --transport http \
   --headers '{"Authorization":"Bearer token"}' \
   --category dev_tool \
-  --icon-emoji robot
-```
-
-### Create a Skill with inline instructions
-
-```bash
-ae-cli agent +add-skill \
-  --name code-reviewer \
-  --description "Reviews code for best practices" \
-  --instructions "You are a code reviewer. Analyze the code for..."
-```
-
-### Create a Skill with instructions from stdin
-
-```bash
-echo "You are a helpful assistant that..." | \
-  ae-cli agent +add-skill --name helper --description "Helper skill" --instructions @-
-```
-
-### Browse the market
-
-```bash
-ae-cli agent +list-mcp-market --scope company --category dev_tool --sort calls
-ae-cli agent +list-skill-market --search "code review" --sort newest --format table
-```
-
-### Set market category / icon
-
-```bash
-ae-cli agent +set-mcp-meta --id <mcp-cuid> --category dev_tool --icon-emoji robot
-ae-cli agent +set-skill-meta --id <skill-cuid> --category data_query
+  --icon-emoji robot \
+  --yes
 ```
 
-### Copy a system/company Skill to personal
+### Publish a personal Skill to the company (root review)
 
 ```bash
-ae-cli agent +copy-skill --id <skill-cuid>
-ae-cli agent +copy-skill --id <skill-cuid> --category dev_tool --icon-emoji robot
-```
+# 1. Create a Skill
+ae-cli agent +add-skill --name code-reviewer --description "Reviews code" --instructions "You are a code reviewer..."
 
-### Submit a Skill for company approval
-
-```bash
+# 2. Submit for company review
 ae-cli agent +submit-skill --id <skill-cuid> --description "Code reviewer for the team"
-```
-
-### Review approvals (root)
 
-```bash
+# 3. Root reviews and approves
 ae-cli agent +list-skill-submissions --status pending
-ae-cli agent +approve-skill --id <submission-cuid>
-ae-cli agent +reject-skill --id <submission-cuid> --reason "Needs more detail"
+ae-cli agent +approve-skill --id <submission-cuid> --yes
 ```
 
 ### Share a Skill peer-to-peer
 
 ```bash
-ae-cli agent +share-skill --id <skill-cuid> --to-user-id <user-id>
+ae-cli agent +share-skill --id <skill-cuid> --to-user-id <user-id> --yes
+# Recipient accepts:
 ae-cli agent +list-skill-shares --direction received --status pending
-ae-cli agent +accept-skill-share --id <share-cuid>
-```
-
-### Upload a single file to attachment library
-
-```bash
-ae-cli agent +add-attachment --file ./output/report.png
-```
-
-### Upload multiple files
-
-```bash
-ae-cli agent +add-attachment --files '["./report.png", "./data.csv", "./chart.pdf"]'
+ae-cli agent +accept-skill-share --id <share-cuid> --yes
 ```
 
-### Toggle a model on/off
+## Quick Verification
 
 ```bash
-ae-cli agent +toggle-model --id <model-cuid> --enabled true
-ae-cli agent +toggle-model --id <model-cuid> --enabled false
+ae-cli agent --help
 ```
-
-## Notes
-
-- Only `personal` scope resources can be created or deleted via CLI.
-- Automations are enabled by default; pass `--enabled false` only when the user explicitly asks to create or update the task without enabling it. Use `+list-automations` to find the target ID internally, but do not show automation IDs, raw JSON, or concrete detail paths in user-facing replies.
-- MCP creation does NOT validate server connectivity — an unreachable URL is accepted at create time and only fails when the agent actually calls the MCP at runtime. Double-check the URL.
-- Attachment upload supports files up to 50MB each, with a 1GB user quota.
-- Batch attachment uploads support partial success — individual file failures don't affect others.
-- Skill `--instructions @-` reads from stdin, useful for piping long instruction text.
-- Market category keys: `ae_preset | dev_tool | search_tool | data_query | content_gen | enterprise | life | automation | other`. Sort options: `newest | calls | likes` (`calls` sorts MCP by call count, Skill by download count). Market scope: `all | system | company | custom` (`custom` = personal).
-- `+add-mcp` / `+add-skill` accept optional `--category / --icon-emoji / --icon-color`; these are applied via a follow-up meta PATCH after creation. MCP creation still does NOT validate server connectivity.
-- `+copy-skill` copies a system/company Skill to an independent personal copy. Optional `--category / --icon-emoji / --icon-color` override the copy's market meta; omit them to inherit the source's. MCP has no copy (use `+toggle-mcp` to enable a system/company MCP per-user).
-- Approval and share flows are Skill-only; MCP has no approval or share. `+approve-skill` / `+reject-skill` require root.
-- `--id` semantics differ by command: `+submit-skill` / `+share-skill` / `+copy-skill` take a Skill ID; `+cancel-skill-submission` / `+approve-skill` / `+reject-skill` take a submission ID; `+accept-skill-share` / `+reject-skill-share` take a share ID.

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)