thinkingaiagenticengine 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
# 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):
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)
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, anddry-runnever 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 runinspects metadata before execution when--yesis absent.- Only
high-risk-writerequires chat confirmation beforecapability run ... --yes. readand ordinarywritemay run after inspect; add validate or dry-run only when the on-demand table says so.- Use
--yeson delete runs only after the user explicitly authorizes execution in chat. - Global
--dry-runoncapability run/ curated commands calls the gateway dry-run endpoint instead of execute. - Global
--validateoncapability 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 withvalidatewhile drafting; for the final payload usedry-runonce (skip a redundant validate on that same final JSON — dry-run already validates params).- Stop in the same turn. Do not call
capability runin the same turn as dry-run. - Summarize in chat: capability ID,
project_id, key input fields, andrisk=high-risk-write. - Ask the user to confirm execution. Prefer
AskUserQuestionwhen 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, oryes) runcapability run ... --yeswith 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
listreturns{ domain, count, capabilities }.searchreturns{ domain, query, count, capabilities }.inspect,validate,dry-run, andrunreturn 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