| name | ae-capability |
| version | 1.3.1 |
| description | AE/TE 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
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
ae-cli capability list --domain <domain> [--project-id <id>]
ae-cli capability search "<terms>" --domain <domain> [--project-id <id>]
ae-cli capability inspect <capability-id> [--project-id <id>]
ae-cli capability validate <capability-id> --input '<json-object>'
ae-cli metadata data-table sql-write --project-id 1 ... --validate
ae-cli capability dry-run <capability-id> --input '<json-object>'
ae-cli metadata data-table sql-write --project-id 1 ... --dry-run
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):
ae-cli metadata data-table sql-write ... --validate
ae-cli metadata data-table sql-write ...
Example (delete gate — dry-run only on final input):
ae-cli capability dry-run analysis.folder.delete --input '...'
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
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
