Turn a short brief into a polished, valid, delivery-ready Feishu/Lark card.
The skill chooses the right delivery surface, composes only supported interactions, and validates the final payload.

简体中文 · Official component docs

Card JSON is easy to produce and surprisingly easy to get wrong. A visually plausible payload can still use a legacy field, attach a callback to a surface that cannot receive it, collapse badly on mobile, or fail strict JSON 2.0 validation.

This skill provides one opinionated path from request to production payload:

• Delivery-aware — distinguishes custom-bot webhooks, application bots, callback responses, and CardKit templates before choosing interactions.
• Composition-aware — applies compact hierarchy, semantic header themes, responsive columns, dark-mode colors, and one clear primary action.
• Component-aware — covers containers, display components, interactive controls, Markdown, tables, charts, images, audio, localization, and streaming.
• Validation-aware — checks the 2.0 schema, envelope shape, nesting, IDs, forms, component limits, and common unsupported combinations.
• Secret-safe — never requires a webhook URL or signing secret inside a card or source file.

Install the skill:

npx skills add lageev/feishu_msg_card_skill

Then invoke it explicitly in your prompt:

Use $feishu-card-json-v2 to create a deployment-failure notification
for a custom bot webhook. Include the service, environment, error summary,
owner, failure time, and one button that opens the deployment details.

The result is a complete JSON 2.0 payload for the selected surface, followed only by the integration notes that matter.

The repository includes five strict JSON templates. Values that require your data are explicit ${PLACEHOLDERS}—no invented user IDs, resource keys, metrics, secrets, or webhook URLs.

{
  "msg_type": "interactive",
  "card": {
    "schema": "2.0",
    "config": {
      "update_multi": true
    },
    "header": {
      "template": "green",
      "title": {
        "tag": "plain_text",
        "content": "Deployment complete"
      }
    },
    "body": {
      "padding": "12px",
      "vertical_spacing": "12px",
      "elements": [
        {
          "tag": "markdown",
          "content": "**Checkout API** is live in production."
        },
        {
          "tag": "button",
          "text": {
            "tag": "plain_text",
            "content": "Open deployment"
          },
          "type": "primary_filled",
          "width": "fill",
          "behaviors": [
            {
              "type": "open_url",
              "default_url": "${DETAIL_URL}"
            }
          ]
        }
      ]
    }
  }
}

Every raw card follows the same top-level structure. Components live in body.elements and declare their type with tag.

{
  "schema": "2.0",
  "config": {},
  "card_link": {},
  "header": {},
  "body": {
    "direction": "vertical",
    "padding": "12px",
    "vertical_spacing": "8px",
    "elements": []
  }
}

The recycling container belongs to the visual CardKit builder and cannot be authored as a raw Card JSON component.

The same-looking card can require a different payload and support a different interaction model depending on how it is sent.

A custom bot is a one-way sender. Use an application bot when the card must collect input, submit a form, receive a callback, update after interaction, or stream content.

Interactive install:

npx skills add lageev/feishu_msg_card_skill

Global install, then choose an agent interactively:

npx skills add lageev/feishu_msg_card_skill -g

Global install for Codex without confirmation prompts:

npx skills add lageev/feishu_msg_card_skill -g -a codex -y

Manual Codex install:

git clone https://github.com/lageev/feishu_msg_card_skill.git \
  ~/.codex/skills/feishu-card-json-v2

Restart Codex if the skill is not discovered immediately.

Validate a raw card, custom-bot envelope, or callback response:

python3 scripts/validate_card.py path/to/payload.json

Select a mode when automatic envelope detection is ambiguous:

python3 scripts/validate_card.py --mode custom-bot path/to/payload.json
python3 scripts/validate_card.py --mode raw path/to/payload.json
python3 scripts/validate_card.py --mode callback-response path/to/payload.json

Wrap a raw card for a custom-bot webhook without sending it:

python3 scripts/wrap_webhook.py path/to/card.json

If signing is enabled, keep the secret in an environment variable:

python3 scripts/wrap_webhook.py path/to/card.json \
  --secret-env FEISHU_BOT_SECRET

The helper prints JSON only. It never sends a request or exposes the secret.

• JSON 2.0 requires Feishu client 7.20 or later; older clients show the header and an upgrade fallback for the body.
• A card supports at most 200 tagged elements/components and should keep container nesting within five levels.
• JSON 2.0 currently supports shared cards only; config.update_multi must be omitted or true.
• Card interaction and update lifetime is 14 days.
• JSON 2.0 rejects unsupported properties instead of silently ignoring them.
• Root i18n_elements, the legacy action module, and update_multi: false are not valid JSON 2.0 patterns.
• Keep webhook URLs, bot/app secrets, callback tokens, private logs, and authorization decisions out of card bodies and source control.

The bundled validator catches common construction errors; it does not replace Feishu server-side validation or client preview.

SKILL.md                    Core decision and construction instructions
agents/openai.yaml          Skill display metadata
assets/readme/              README card previews
assets/templates/           Reusable JSON 2.0 payloads
references/                 Schema, components, recipes, and official sources
scripts/validate_card.py    Focused JSON 2.0 validator
scripts/wrap_webhook.py     Custom-bot envelope/signature helper

• Official JSON 2.0 component overview
• Official JSON 2.0 card structure
• Official JSON 2.0 breaking changes
• Component catalog
• Core schema and style
• Delivery and interaction
• Design recipes

MIT