ai-card-generator

# AI Card Generator

Automatically generate and update HTML visual cards via scheduled tasks. Cards can be single-file or folder-based multi-file, and are generated from user prompts + templates with fresh data.

## Output Language Contract

The skill documentation, built-in templates, and prompt snippets are written in English. Generated card content must adapt to the user's language.

1. Infer the user's preferred output language from the current request first, then from existing card content, template language, project context, and explicit user instructions. Ask one concise clarification only when language choice materially changes the final card.
2. Write all user-facing generated text in the inferred language: card titles, descriptions, summaries, labels, badges, source notes, chart labels, AI follow-up prompts, status messages, placeholders, and schedule-created card metadata.
3. Keep machine contracts stable: `magic.project.js` keys, enum-like status values, paths, filenames, CSS class names, DOM ids, JS function names, Magic API calls, and template marker comments stay in their documented form.
4. Set HTML `lang` attributes to the inferred language for generated cards. Built-in English templates may use `lang="en"`, but cards generated for users should update it.
5. Do not translate brand names, product names, code identifiers, URLs, source quotes, or fixed schema values. Translate surrounding explanation and presentation text.

## Core Capabilities

- Create AI visual cards with scheduled updates
- Support user-customizable HTML templates (users can edit templates anytime)
- Each execution generates updated content based on template structure + latest data
- Automatic history version snapshot management
- Support multiple card types (hotspot tracker, daily digest, analytics panel, etc.)
- Design scenario-specific interactive templates instead of only filling the preset skeletons
- Preserve source links from fetched data and expose them through source lists, new-tab links, or safe iframe previews

## Related Skill Usage

When a card needs interactivity, web-page previews, file I/O, agent/model selectors, or AI deep-analysis actions, read and apply these skills first:

- `micro-app-architect`: decompose the user's request, decide interaction/data/Agent boundaries, and choose Simple/Medium/Complex architecture.
- `html-api-sdk`: verify exact `window.Magic.*` API signatures, message formats, error handling, and fallback behavior.

Do not treat an AI Card as a static screenshot. It is an updateable HTML micro-page: the template owns the interaction and visual structure, while the scheduled Agent workflow owns data fetching, source tracking, and content replacement.

## Directory Structure Convention

Card directory name is user-defined, no fixed path required. The core requirement is the directory must contain `magic.project.js` with type set to `ai-card`.

Preferred mode is folder-based multi-file for maintainability. Single-file mode is still supported for backward compatibility.

```
{card-directory}/
├── magic.project.js                  # REQUIRED — type="ai-card"
├── template/                         # Preferred template folder
│   ├── index.html
│   ├── styles.css                    # Optional
│   ├── scripts.js                    # Optional
│   ├── data/                         # Optional seed schemas
│   │   ├── card-data.json
│   │   └── sources.json
│   └── prompts/                      # Optional analysis prompt snippets
│       └── deep-analysis.txt
├── latest/                           # Preferred output folder
│   ├── index.html
│   ├── styles.css                    # Optional
│   ├── scripts.js                    # Optional
│   └── data/                         # Optional generated structured data
│       ├── card-data.json
│       └── sources.json
└── history/
  ├── 2026-05-23_09-00/
  │   ├── index.html
  │   ├── styles.css                # Optional
  │   ├── scripts.js               # Optional
  │   └── data/                    # Optional snapshot data
  │       ├── card-data.json
  │       └── sources.json
  └── 2026-05-22_09-00/
    ├── index.html
    ├── styles.css                  # Optional
    └── scripts.js                  # Optional

Backward compatible (legacy):

{card-directory}/
├── magic.project.js
├── template.html
├── latest.html
└── history/
  └── YYYY-MM-DD_HH-mm.html
```

## Creation Workflow

### Step 0: Requirement Decomposition and Template Design

Before creating or modifying a card, decompose the user's request into: information type, data sources, update cadence, expected interactions, source-link display mode, and whether Agent deep analysis is needed.

Design the template for the scenario instead of mechanically applying the three presets:

- Hotspot / public-opinion cards: ranking, trend lines, platform distribution, sentiment/risk, lifecycle, source preview.
- Daily / weekly digest cards: executive summary, metric groups, event timeline, action list, citations, expandable source text.
- Analytics dashboards: KPIs, funnels, cohorts, anomaly alerts, range switching, follow-up insight prompts.
- Research / intelligence cards: claim cards, evidence matrix, source reliability, iframe source preview, comparison view.
- Decision / planning cards: option comparison, risk/reward, milestones, owners, next actions.

Prefer interactions that help judgment and action: filters, tabs, sorting, expand/collapse, chart hover, time-range switches, source drawers, iframe previews, and AI follow-up buttons. Avoid decorative-only interactions.

### Self-Media Operations Boundary

When the prompt is for a self-media article/post review, post-publication retrospective, published-data import, operations review dashboard, article operations dashboard, or localized equivalent, do not generate or update `ops/*` files in this skill. Route the work to `self-media-composer` or the self-media/IP-operations data-sync workflow, which owns `ops/source.json`, `ops/metric