---
name: ae-capability
version: 1.3.15
description: "AE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, optionally validate complex input or dry-run before execute, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields. Prefer on-demand validate OR dry-run — do not stack both by default."
---

# ae-capability

## Cross-skill collaboration

When remaining work is outside this skill's scope, or a necessary prerequisite needs another capability, follow [the collaboration protocol](references/collaboration.md). Choose from the skills available in this run by capability, preserve verified context, and continue the remaining task. Reuse this protocol if already loaded.

Use this skill for progressive capability discovery and generic gateway invocation. Prefer a domain-specific curated command when one exists; use `ae-cli capability ...` for discovery and long-tail capabilities.

## Decision Order

1. Use a domain skill and its curated command when it directly covers the task.
2. Otherwise search the capability catalog.
3. Inspect the selected capability before constructing input.
4. **Optionally** pre-check — pick **at most one** path from the table below (do not stack validate + dry-run by default).
5. Execute (`capability run` / curated command). Chat confirmation only for delete (`high-risk-write`).

Never guess a capability ID, input field, enum value, resource ID, or project ID.

**CRITICAL — Host compat (do this first):** After each `ae-cli` run, check stderr and `_notice.host_compat`. If either is present, open the user reply with a short ⚠️ version warning and quote the recommended `ae-cli update` (or update-cluster) guidance, then present the business result. For new local installations use `npx @thinkingai/ae-cli@latest install`. Soft tip; `ok: true` can still carry the notice.

## Agent Context Telemetry

Hard rule: before running gateway-backed `ae-cli` commands, maintain the current Agent context in `.ae/cli-agent-context.json` at the working directory root, unless the user explicitly asks not to send intent telemetry. Keep the business command clean; do not append `--agent-context <base64url-json>` by default.

Create or update the context file when starting a CLI-backed task and whenever the user's CLI purpose changes. Reuse it while the purpose and model remain unchanged. Use the user's original language for `session_initial_intent`, `user_intent`, and `session_goal`; for example, use Chinese text for a Chinese user request. At minimum, include:

- `agent_client`
- `agent_model` whenever the current model can be confirmed
- stable `agent_session_id`
- `agent_turn_id` when available
- `intent_source: "agent_context_file"`
- concise `user_intent` for the current CLI-triggering purpose
- current `session_goal`

The Agent must actively obtain the current model identifier and write it explicitly as `agent_model` in the context file. Use trusted runtime context or bounded metadata for the exact current session and turn; for example, Codex's current-session `turn_context.model`. Do not rely solely on a model environment variable being present. Never infer the model from the Agent/product name, a configured default, or another session. This requirement applies to every Agent client. Update the file when the model changes, even if the CLI purpose stays the same.

If the model cannot be confirmed, omit `agent_model`, set `context_capture_status: "partial"`, and continue; do not block or delay the business command or ask the user to identify the model just for telemetry. Once confirmed, write the model and remove the stale partial marker so the CLI can compute capture status from the remaining fields.

Write this JSON object to `.ae/cli-agent-context.json`:

```json
{
  "agent_client": "codex",
  "agent_model": "<confirmed-current-model-id>",
  "agent_session_id": "<stable conversation id>",
  "agent_turn_id": "<current turn id>",
  "parent_turn_id": "<previous turn id>",
  "intent_relation": "initial|follow_up|correction|verification",
  "intent_revision": "1",
  "intent_source": "agent_context_file",
  "session_initial_intent": "<first user request for this conversation>",
  "user_intent": "<current CLI-triggering user intent>",
  "session_goal": "<current summarized session goal>"
}
```

Use this local template when updating the file. Replace every placeholder with verified context before running it; write the confirmed model explicitly rather than reading an optional environment variable. For an unknown model, omit that field and add the partial status described above.

```bash
mkdir -p .ae
node -e 'const fs = require("fs"); const payload = {
  agent_client: "codex",
  agent_model: "<confirmed-current-model-id>",
  agent_session_id: process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID,
  agent_turn_id: "<current-turn-id>",
  parent_turn_id: "<previous-turn-id>",
  intent_relation: "initial",
  intent_revision: "1",
  intent_source: "agent_context_file",
  session_initial_intent: "<first user request for this conversation>",
  user_intent: "<current CLI-triggering user intent>",
  session_goal: "<current summarized session goal>"
}; Object.keys(payload).forEach((key) => payload[key] == null || payload[key] === "" ? delete payload[key] : undefined); fs.writeFileSync(".ae/cli-agent-context.json", JSON.stringify(payload, null, 2));'
ae-cli ...
```

If a field is unknown, omit that field rather than guessing; do not omit the whole context file. Keep `agent_session_id` stable across the conversation; increment or update `intent_revision` when user corrections change the CLI purpose. Prefer a short task-level `user_intent` summary over a long raw transcript. If privacy is a concern, send `user_intent_hash` and a coarse intent summary instead of verbatim user text.

After running a gateway command, if you are asked whether intent telemetry was sent, verify that `.ae/cli-agent-context.json` existed before the command and contained `user_intent` or `user_intent_hash`. Runtime-only context is only a partial fallback and does not satisfy this hard rule.

Fallbacks, in priority order: `.ta/cli-agent-context.json` / `.ae/cli-agent-context.json` > `--agent-context` for isolated no-write environments or local debugging > legacy `TA_CLI_*` variables > runtime environment auto-detection.

### Analysis outcome assessment and supplementary feedback

Scenario collection is project opt-in. Before preparing or uploading a scenario sample, read `ae-cli project info get --project-id <source_project_id>` for the current host, authenticated account, and source analysis project. Only `data.analysis_scenario_collection_enabled === true` permits collection. Recheck for each new scenario and before appending feedback or a revision; do not reuse a previous grant or the company configuration's 24-hour cache. A missing field (including older services), false, unreadable configuration, or unknown project means skip collection and answer normally. Never enable the project switch, choose a different project, or invent a project ID to make collection succeed. The curated collect/append commands also check immediately before submission, and the service is authoritative if the switch changes. This controls only scenario samples; existing invocation and intent logs stay unchanged. `accepted=false, skipped=true` is a normal skip, not a failed analysis or successful upload. Do not retry, backfill, or fall back to `analysis feedback submit` to bypass this switch.

Collect one sample for the whole user scenario, not one per CLI call. After forming the final answer, use `ae-cli analysis scenario collect` as specified in the `ae-cli analysis scenario collect --help` and `append --help` contracts, then deliver that exact answer text. Capture the original question/confirmed clarifications, actual final answer and the ordered query path (existing capability/call IDs and optional short purpose; prefer only meta.invocation_id, never confuse a business request_id with gateway client_request_id), never query result rows or error payloads; do not score correctness or generate a separate self-evaluation. The question_id is the original scenario's first user turn ID, stable across clarification, retries, multiple queries and corrections. Store/reuse the IDs returned by collection in conversation context. On later user objections, scope corrections or reported omissions targeting that answer, append the user's original text with `ae-cli analysis scenario append --entry-type user_feedback` and the original question_id/target_answer_id; do not decide whether the user is right. An ambiguous request for an explanation may be preserved as user text when clearly linked; do not invent a link. A normal follow-up or changed requirement is not automatically negative feedback. After a substantive follow-up answer to the same scenario (recheck, explanation, correction or scope clarification), append answer_revision with that exact answer/query path and a new answer_id, even when the conclusion stays the same; keep earlier answers. If the triggering user request was not already captured as user_feedback, include its exact text using --user-message on answer_revision so later scope changes are not lost. Do not duplicate feedback text in user_message. Acknowledgments such as thanks alone need no entry. A genuinely separate question gets a new question_id. Do not create another initial sample for an existing scenario. A separate evaluation task reads these samples later and can join existing call telemetry for parameters/status/timing. Path-only evidence cannot prove numeric answer correctness; unresolved correctness stays unknown. Only attempted analysis data queries qualify; metadata, discovery, help and asset writes alone do not. No routine satisfaction question. Collection failure must not block the answer or subsequent business work, trigger login or automatic retries, or be claimed as successful ingestion. For external Agents this is a Skill collection step, not a guaranteed post-answer hook; it has one collection tool call but no additional evaluation task on the answering path.

User feedback is evidence, not a correctness label. Preserve exact user words and their target answer even if you disagree. Do not routinely ask for a satisfaction rating. The existing `analysis feedback submit` contract remains available for explicit standalone user ratings without a collected scenario; when a scenario exists, use its append command instead of submitting duplicate feedback. No explicit feedback means no submission or new feedback event for `cli_analysis_feedback`. Do not upload the analysis answer through that legacy feedback command. All collection excludes credentials, full transcripts and private reasoning.

### On-demand pre-check (pick one)

Motto: **validate = fix params; dry-run = confirm ready to run.**
Hard rule: **for the same final input, do not run both validate and dry-run by default.** `dry-run` already includes parameter validation.

| Situation | What to call | Then |
| --- | --- | --- |
| Simple / familiar input (typical `read`, few scalar fields) | **Neither** — skip pre-check | `run` directly |
| Complex `qp` / nested `payload` / share maps; still iterating shape | **`--validate` / `capability validate` only** (may repeat while fixing) | After `valid=true`, **`run` directly** — skip dry-run unless below applies |
| Need risk / `output_mode` / `supports_cancel`, or `high-risk-write` delete gate | **`--dry-run` / `capability dry-run` only** (once on final input) | Then confirm (delete) / `run`. Do **not** validate first on the same final payload |
| Rare exception: many validate iterations, then still need delete confirmation | validate while drafting → **one** dry-run on the **final** input | Then chat confirm → `run --yes` |

Do **not** treat `validate → dry-run → run` as the normal path. That stack is the rare exception in the last row only.

## Skill references

Default: **do not** create a standalone skill reference for every new capability. Use `search` → `inspect` → (**optional** validate *or* dry-run) → `run`; catalog `description`, `risk`, and `inspect` `input_schema` are the contract.

Create or keep a standalone reference only when at least one applies: L2 hard bar, easily confused with neighbors, `high-risk-write` delete workflow, or multi-step orchestration. Domain skills may inline one-line summaries in overview matrices (e.g. `analysis_gateway_assets.md`). See [`capability-command-admission` §10](../../docs/capability-command-admission.md).

## Commands

```bash
# List company-level summaries, or the capabilities available in one project.
ae-cli capability list --domain <domain> [--project-id <id>]

# Search capability IDs and descriptions. All terms must match.
ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]

# Read input_schema, risk, auth, output, and dry-run support.
ae-cli capability inspect <capability-id> [--project-id <id>]

# Optional — fix params only (gateway /validate). Curated: global --validate.
ae-cli capability validate <capability-id> --input '<json-object>'
ae-cli metadata data-table sql-write --project-id 1 ... --validate

# Optional — confirm ready to run (gateway /dry-run). Curated: global --dry-run.
ae-cli capability dry-run <capability-id> --input '<json-object>'
ae-cli metadata data-table sql-write --project-id 1 ... --dry-run

# Execute (after inspect; add at most one pre-check when needed).
ae-cli capability run <capability-id> --input '<json-object>'
```

`--input` accepts:

- An inline JSON object.
- A JSON file path.
- `@<path>`.
- `-` to read JSON from stdin.

The capability namespace is inferred from `<capability-id>` for `inspect`, `validate`, `dry-run`, and `run`. Use `--domain <domain>` only to override routing. For `list`, `search`, and `inspect`, omit `--project-id` for company License/Feature visibility; pass it to include project membership, project Feature, and user permission filtering.

## validate vs dry-run

| | `validate` / `--validate` | `dry-run` / `--dry-run` |
| --- | --- | --- |
| Purpose | Check **input shape** while composing complex payloads | **Pre-execution confirmation** (params + risk/output/cancel) |
| Does it mutate business data? | No | No |
| Primary success fields | `valid`, `capability_id`, `normalized_input` | `dry_run`, `capability_id`, `risk`, `output_mode`, `supports_cancel`, `normalized_input` |
| When to prefer | Iterating nested `payload` / `qp` / multi-field JSON | Final input; need risk/output contract or delete gate |
| Typical failure focus | Missing/invalid fields, type mismatches, bad `qp` structure | Same param errors, plus readiness signals for actual run |
| Curated commands | Global `--validate` on gateway-backed curated commands | Global `--dry-run` |

Server may still authenticate the caller for both endpoints. Neither executes the capability business handler. Do not combine `--validate` and `--dry-run` on one invocation.

**Complex input:** prefer **`--validate` only** while assembling `qp` / nested payload; after `valid=true`, go to `run`. Use dry-run instead of validate when you need the risk/output preview or a delete confirmation gate — not both.

Example (param risk only — no stacked dry-run):

```bash
ae-cli metadata data-table sql-write ... --validate   # iterate until valid
ae-cli metadata data-table sql-write ...              # execute ordinary write
```

Example (delete gate — dry-run only on final input):

```bash
ae-cli capability dry-run analysis.folder.delete --input '...'
# stop, ask user, then:
ae-cli capability run analysis.folder.delete --input '...' --yes
```

## Risk Levels (aligned with lark-cli)

| `risk` | Meaning | Chat confirmation before `run`? | CLI `[y/N]` without `--yes`? |
| --- | --- | --- | --- |
| `read` | Query / list / inspect | No | No |
| `write` | Create, update, share, and other ordinary writes | No | No |
| `high-risk-write` | Delete or remove resources | **Yes** | **Yes** |

Legacy values such as `create`, `update`, or `delete` are normalized to this three-tier model (`delete` → `high-risk-write`; `create`/`update` → `write`).

## Safety

- `list`, `search`, `inspect`, `validate`, and `dry-run` never execute business mutations.
- Curated gateway commands: `--validate` → `/validate`; `--dry-run` → `/dry-run`; do not combine them.
- Do not stack validate + dry-run on the same final input by default (efficiency).
- `capability run` inspects metadata before execution when `--yes` is absent.
- Only `high-risk-write` requires chat confirmation before `capability run ... --yes`.
- `read` and ordinary `write` may run after inspect; add validate **or** dry-run only when the on-demand table says so.
- Use `--yes` on delete runs only after the user explicitly authorizes execution in chat.
- Global `--dry-run` on `capability run` / curated commands calls the gateway dry-run endpoint instead of execute.
- Global `--validate` on `capability run` / curated commands calls the gateway validate endpoint instead of execute.

## High-Risk Confirmation Workflow (Agent)

Applies only when `inspect` shows `risk=high-risk-write`.

User intent (for example "delete this space") is **not** execution authorization. Do not pass `--yes` just because the user stated the desired action.

1. `capability inspect`. For complex delete input only, you may iterate with `validate` while drafting; for the **final** payload use **`dry-run` once** (skip a redundant validate on that same final JSON — dry-run already validates params).
2. **Stop in the same turn.** Do not call `capability run` in the same turn as dry-run.
3. Summarize in chat: capability ID, `project_id`, key input fields, and `risk=high-risk-write`.
4. Ask the user to confirm execution. Prefer `AskUserQuestion` when that tool is available; otherwise ask in plain text and wait for the user's **next message**.
5. Only after the user replies with explicit authorization (for example `confirm`, `execute`, or `yes`) run `capability run ... --yes` with the same input as dry-run.

For `risk=write`: no chat confirmation gate. Prefer direct `run` after inspect; use `--validate` alone when the payload is complex and you are fixing shape; use `--dry-run` alone only if you need the risk/output preview — **not** validate then dry-run as a habit.

Never pass `--yes` on the first delete attempt. CLI terminal `[y/N]` prompts do not work in Agent Bash; chat confirmation is the real gate for `high-risk-write`.

## Output

- `CREDENTIAL_STORE_UNREADABLE` with `error.type: config` is a local credential read/decryption failure, not a server authentication rejection. Preserve the credential files and retry in the original OS user/runtime with machine-identifier access. Do not automatically log in, import a replacement token, or log out; report the local error if that runtime is unavailable.
- `list` returns `{ domain, count, capabilities }`.
- `search` returns `{ domain, query, count, capabilities }`.
- `inspect`, `validate`, `dry-run`, and `run` return gateway data in the standard ae-cli envelope.

## Examples

```bash
ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list
ae-cli capability validate metadata.data_table.sql_write --input input.json
ae-cli capability dry-run analysis.folder.delete --input '{"project_id":1,"folder_ids":[1001]}'
ae-cli capability run analysis.dashboard.list --input input.json
```