Adaptive Cards Authoring
Designadaptive-cards-authoringAdaptive Cards Authoring is an Agent Skill for design published in the rcarmo/piclaw repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Author Adaptive Cards for the current PiClaw web environment. Use when you need a prompt pattern, supported payload shape, or reusable card templates for structured web interactions.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/rcarmo/piclaw/blob/HEAD/skel/.pi/skills/adaptive-cards-authoring/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/adaptive-cards-authoring, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Adaptive Cards Authoring
Use this skill when a web-only, structured interaction is materially better as a card than as plain markdown.
Good fits
- approval / reject / revise flows
- choosing one of a few next actions
- short structured data capture
- persistent status or completion receipts
- link collections where explicit buttons are clearer than inline links
Avoid cards when markdown is clearer, the interaction is long-form, or the action semantics are not supported.
PiClaw payload shape
Emit a normal message with a concise fallback plus one adaptive_card content block:
{
"type": "adaptive_card",
"card_id": "approval-123",
"schema_version": "1.5",
"state": "active",
"fallback_text": "Approval requested.",
"payload": {
"type": "AdaptiveCard",
"version": "1.5",
"body": [
{ "type": "TextBlock", "text": "Approval requested", "weight": "Bolder", "size": "Medium" }
],
"actions": [
{ "type": "Action.Submit", "title": "Approve", "data": { "decision": "approve" } }
]
}
}
Supported today in the PiClaw web runtime:
- timeline rendering via
content_blocks - actions:
Action.Submit,Action.OpenUrl - states:
active,completed,cancelled,failed - agent-owned posting via
send_adaptive_card
Do not rely on Action.ShowCard, Action.ToggleVisibility, complex refresh/auth flows, or non-web card delivery unless you are explicitly extending core support.
Authoring rules
- Keep
schema_version/payload.versionat1.5unless there is a specific reason otherwise. - Keep
contentandfallback_textshort and human-readable. - Prefer simple primitives:
TextBlock,FactSet,Input.*,ChoiceSet,Toggle. - Keep button labels short and explicit.
- Use
Action.Submitfor structured decisions andAction.OpenUrlfor external links. - Keep submission payloads small, flat, and readable.
- Assume cards are web-only unless you also provide a graceful markdown fallback.
- Prefer one clear card over a dense wall of controls.
- Keep critical meaning visible in the fallback message too.
Prompt pattern
Use an Adaptive Card for this response because the interaction is structured and web-only.
Constraints:
- Target the current PiClaw web runtime
- Emit a concise fallback message plus one adaptive_card content block
- Use schema version 1.5
- Only use supported actions: Action.Submit and/or Action.OpenUrl
- Keep the card compact and readable in a narrow pane
- Keep submission payloads small and explicit
- If a card would be worse than markdown, say so and return markdown instead
Task:
<describe the approval / choice / form interaction>
If you need more determinism, ask for:
- a fallback message string
- exactly one
adaptive_cardcontent block JSON object
Templates and implementation notes
- Reuse
templates.mdfor concrete card patterns rather than inventing new classes ad hoc. - If you are implementing card emission in PiClaw itself, prefer
send_adaptive_card. - If you need low-level posting, use message
content_blocksormessageswithaction: "post".