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

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.hostcompat. 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.

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. analysisgatewayassets.md). See [capability-command-admission §10](../../docs/capability-command-admission.md).

Commands

# 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

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):

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):

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)

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

• 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

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