Ae Capability

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

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

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