ae-capability

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

Use a domain skill and its curated command when it directly covers the task.
Otherwise search the capability catalog.
Inspect the selected capability before constructing input.
Optionally pre-check — pick at most one path from the table below (do not stack validate + dry-run by default).
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
npm i -g
/
npx skills add
(or update-cluster) lines verbatim, then present the business result. Soft tip;

ok: true

can still carry the notice.

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.

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.

```
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).
Stop in the same turn. Do not call
```
capability run
```
in the same turn as dry-run.
Summarize in chat: capability ID,
```
project_id
```
, key input fields, and
```
risk=high-risk-write
```
.
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.
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

```
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

ae-capability

NPX Install

Tags

SKILL.md Content

ae-capability

Decision Order

On-demand pre-check (pick one)

Skill references

Commands

validate vs dry-run

Risk Levels (aligned with lark-cli)

Safety

High-Risk Confirmation Workflow (Agent)

Output

Examples