Idmp Panel

panel

Read [../idmp-shared/SKILL.md](../idmp-shared/SKILL.md) first.

Before any write: Follow the [🛑 Destructive op confirmation protocol](../idmp-shared/SKILL.md#-destructive-op-confirmation-mandatory). Read-only commands stay read-only here, but delete / write / patch flows still require the shared yes-gate.

Recommended shortcuts

| Shortcut | Purpose | |----------|---------| | +list | List panels under one element. | | +search | Search panels globally. | | +templates | List panel templates available to one element. |

Recommended references

• [panel read flows](references/panel-read-flows.md)
• [../idmp-workflow-panel-build/SKILL.md](../idmp-workflow-panel-build/SKILL.md)

Missing context to resolve first

| Context | Why it must be resolved before create or verify | | --- | --- | | Owner element | You need the final elementId for list, get, naming, create, and every verification call. | | Candidate panel name | panel.panels.new-name requires both elementId and a proposed name. | | Verification mode | Decide whether this panel should generate SQL at all, and whether you need plain query and sqls checks or advanced-query verification. | | Dashboard placement target | Decide whether the panel remains standalone or must be inserted into a dashboard before the workflow counts as complete. | | Refresh owner | Decide whether refresh belongs on the panel shell or the dashboard shell so refreshInterval lands in the right params block. |

Constrained live behaviors

• Prefer POST /api/v1/ai/panels/create for natural-language panel requests, then persist the returned draft through panel.panels.create. Use the structured panel DTO workflow only as fallback when the draft is unsuitable or persistence fails.
• panel.panels.new-name requires a candidate name; do not call it with only the owner scope.
• Text and manual panels can legitimately return generated SQL is empty, so query is inapplicable for those panel types.
• panel verify create validates only the time-range payload with from and to; use plain --data, not --params, and do not send elementId.
• panel.panels.query and panel.panels.create use the panel DTO shape. panel.panels.sqls uses the same DTO together with owner --params.
• panel verify create-post is only for advanced-query payloads. Keep uuid, advancedQueryType, querySqls, and the advanced query fields inside that single DTO.
• If a child-scope no-code DTO collapses to self scope on reread or returns empty-body 400, capture the working SQL and switch to the advanced fallback instead of treating the first attempt as a total panel failure.
• If the backend returns HTTP 400 with an empty body on panel query, verify, or create, assume a DTO-shape mismatch first and recheck the typed schema output before retrying.
• refreshInterval belongs in params on the object that owns refresh behavior, not in an arbitrary top-level field.
• Creating a panel does not place it into a dashboard automatically; a separate dashboard update is still required.

Evidence of completion

• A panel create is only complete when panel panels get rereads the persisted object with the intended owner, name, and params.
• A query-backed panel is only complete when the same DTO succeeds through panel.panels.query or panel.panels.sqls.
• An advanced fallback is only complete when reread shows enableAdvanced=true and the advanced DTO still validates. For child-scope workflows, this advanced fallback still counts as first-attempt success when the no-code payload collapsed but the verified SQL stayed correct.
• Dashboard placement is separate proof; do not treat a panel create as dashboard membership.

Product behavior to preserve

• Read list first, then get, before changing a panel.
• For natural-language creation asks, prefer the AI draft endpoint first and keep structured DTO creation as the fallback.
• Use new-name with a candidate name before creating a panel.
• Run query and sqls only for panels that should generate SQL, and use verify only for the single advanced-query DTO rather than the full panel DTO.
• When advancedQueries is present, keep checked boolean and dimensions as an array of strings.
• refreshInterval belongs in params on the object that owns refresh behavior, not in an arbitrary top-level field.
• Creating a panel does not place it into a dashboard automatically.

Key commands

idmp-cli schema panel.panels.list
idmp-cli panel panels list --params '{"elementId":123}'

idmp-cli schema panel.panels.get
idmp-cli panel panels get --params '{"elementId":123,"panelId":456}'

idmp-cli schema panel.verify.create
idmp-cli panel verify create --ack-risk --data '{"from":"now-12h","to":"now"}'

idmp-cli schema panel.verify.create-post
idmp-cli panel panels new-name --params '{"elementId":123,"name":"demo-panel"}'
idmp-cli panel panels create --dry-run --ack-risk --params '{"elementId":123}' --data '{...}'

# In the current generated schema, `panel.panels.query` is readonly and `--ack-risk` is optional,
# but `panel.panels.sqls`, `panel.verify.create`, and `panel.verify.create-post` are still generated
# as write-risk commands and must keep `--ack-risk`.
idmp-cli panel panels query --ack-risk --params '{"elementId":123}' --data '{...}'
idmp-cli panel panels sqls --ack-risk --params '{"elementId":123}' --data '{...}'
idmp-cli panel verify create-post --ack-risk --params '{"elementId":123}' --data '{...}'

idmp-cli panel panel-templates list --params '{"elementId":123}'

Exception and failure handling

• If a panel is created successfully but no dashboard is updated, the panel remains standalone by design.
• If refreshInterval is set outside params, treat the payload as incomplete and fix it before retrying.
• If a text or manual panel returns empty SQL, skip query and treat SQL-based validation as inapplicable for that panel type.
• If panel verify create fails, send only the time-range payload with from and to; it is not the advanced-query validator.
• If panel verify create-post fails with missing uuid or advancedQueryType, you passed a plain panel DTO instead of an advanced-query DTO.
• If panel query, verify, or create returns HTTP 400 with an empty body, compare the typed schema output against your payload before changing the SQL itself.
• If child-scope no-code rereads collapse to self scope but panel.panels.sqls already proved the intended grouped SQL, persist the advanced fallback instead of restarting from an unrelated self-scope DTO.
• If the panel was copied from a template, create a new panel instead of assuming the copied identifier is updatable.
• If a time range returns empty data, adjust the query window before changing metrics or dimensions.

Validation scenarios

1. Read the panel list with idmp-cli schema panel.panels.list and idmp-cli panel panels list --params '{"elementId":123}'.
2. Reserve a create-safe name with idmp-cli panel panels new-name --params '{"elementId":123,"name":"demo-panel"}'.
3. Preview panel creation with idmp-cli panel panels create --dry-run --ack-risk --params '{"elementId":123}' --data '{...}'.
4. Run SQL-based checks only when the panel should generate SQL: use idmp-cli panel panels query --ack-risk --params '{"elementId":123}' --data '{...}' and idmp-cli panel panels sqls --ack-risk --params '{"elementId":123}' --data '{...}' for query-backed panels, use idmp-cli panel verify create --ack-risk --data '{"from":"now-12h","to":"now"}' only for time-range validation, and use idmp-cli panel verify create-post --ack-risk --params '{"elementId":123}' --data '{...}' only for advanced-query DTOs that include fields such as uuid and advancedQueryType. If the child-scope no-code branch collapses, switch to the advanced fallback and keep that as the success path.
5. Confirm template reuse or separate dashboard work with idmp-cli panel panel-templates list --params '{"elementId":123}' and idmp-cli dashboard dashboards get --params '{"elementId":123,"dashboardId":789}'.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: taosdata
• Source: taosdata/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.