OpenParable
Skip to content
← Back to skills

Adaptive Cards Authoring

Design
adaptive-cards-authoring

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

  1. Keep schema_version / payload.version at 1.5 unless there is a specific reason otherwise.
  2. Keep content and fallback_text short and human-readable.
  3. Prefer simple primitives: TextBlock, FactSet, Input.*, ChoiceSet, Toggle.
  4. Keep button labels short and explicit.
  5. Use Action.Submit for structured decisions and Action.OpenUrl for external links.
  6. Keep submission payloads small, flat, and readable.
  7. Assume cards are web-only unless you also provide a graceful markdown fallback.
  8. Prefer one clear card over a dense wall of controls.
  9. 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:

  1. a fallback message string
  2. exactly one adaptive_card content block JSON object

Templates and implementation notes

  • Reuse templates.md for 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_blocks or messages with action: "post".