Skip to content

KKenny0/card-skill / plugins/card-skill/skills/card-skill

card-skill

Unverified

Turn supplied text or evidence into PNG cards, article covers, and explanatory illustrations. Use for content-to-image requests, including card series and reading-note visuals.

FileKindSize
LICENSEother1.0 KB
README.mdmarkdown18.7 KB
README.zh-CN.mdmarkdown18.2 KB
SKILL.mdskill md13.7 KB
VERSIONother7 B
assets/big_template.htmlother2.0 KB
assets/capture4k.jsscript5.7 KB
assets/comic_template.htmlother1.8 KB
assets/cover-series/paper-wilderness/README.mdmarkdown1.5 KB
assets/cover-series/paper-wilderness/cooperation.pngbinary2.1 MB
assets/cover-series/paper-wilderness/layout.cssother523 B
assets/cover-series/paper-wilderness/master.pngbinary1.7 MB
assets/cover-series/paper-wilderness/rest.pngbinary2.3 MB
assets/cover-series/paper-wilderness/uncertainty.pngbinary2.0 MB
assets/fonts/DM-Sans-OFL.txtmarkdown4.3 KB
assets/fonts/DM-Serif-Display-OFL.txtmarkdown4.4 KB
assets/fonts/DMSans-Variable.ttfbinary234.5 KB
assets/fonts/DMSerifDisplay-Regular.ttfbinary74.8 KB
assets/fonts/FONT_SOURCES.mdmarkdown1.3 KB
assets/fonts/JetBrains-Mono-OFL.txtmarkdown4.3 KB
assets/fonts/JetBrainsMono-Variable.ttfbinary293.1 KB
assets/fonts/LICENSE-fonts.mdmarkdown1.7 KB
assets/fonts/NanxiChuxiasong.ttfbinary3.1 MB
assets/fonts/OFL-1.1.txtmarkdown4.0 KB
assets/fonts/XiangcuiDengcusong.ttfbinary22.3 MB
assets/fonts/local-fonts.cssother641 B
assets/fonts/香萃打字机体 W15.ttfbinary15.7 MB
assets/fonts/香萃打字机体 W40.ttfbinary15.5 MB
assets/gallery/article-boundary-legacy.pngbinary129.8 KB
assets/gallery/article-formula.pngbinary181.2 KB
assets/gallery/article-personal.pngbinary120.8 KB
assets/gallery/big.pngbinary157.0 KB
assets/gallery/comic.pngbinary3.4 MB
assets/gallery/editorial-wechat-cover.pngbinary760.3 KB
assets/gallery/infograph.pngbinary604.6 KB
assets/gallery/long.pngbinary960.7 KB
assets/gallery/manifest.jsonconfig6.2 KB
assets/gallery/poster.pngbinary335.6 KB
assets/gallery/reading-notes.pngbinary363.9 KB
assets/gallery/reading-report.pngbinary366.9 KB
assets/gallery/sketchnote.pngbinary603.9 KB
assets/gallery/whiteboard.pngbinary583.2 KB
assets/infograph-comparison-notes.cssother951 B
assets/infograph_template.htmlother2.6 KB
assets/logo.pngbinary1.0 MB
assets/long_template.htmlother3.1 KB
assets/open-source-tool/tool-cli-1.pngbinary419.5 KB
assets/open-source-tool/tool-cli-2.pngbinary427.9 KB
assets/open-source-tool/tool-cli-3.pngbinary467.6 KB
assets/open-source-tool/tool-launch-1.pngbinary483.1 KB
assets/open-source-tool/tool-launch-2.pngbinary408.5 KB
assets/open-source-tool/tool-launch-3.pngbinary547.6 KB
assets/open-source-tool/tool-launch-4.pngbinary449.0 KB
assets/poster_template.htmlother18.5 KB
assets/readme-showcase.pngbinary773.4 KB
assets/sketchnote-wandering-notes.cssother1.7 KB
assets/sketchnote_template.htmlother16.9 KB
assets/whiteboard-notes.cssother2.2 KB
docs/astra-migration.mdmarkdown4.4 KB
docs/current-architecture.mdmarkdown7.8 KB
evals/agent-cases.jsonconfig34.0 KB
evals/cardbench-results.jsonconfig19.5 KB
evals/check-assertions.mjsscript25.8 KB
evals/check-job-assertions.mjsscript25.3 KB
evals/cover-art-agent-cases.jsonconfig4.5 KB
evals/evals.jsonconfig51.3 KB
evals/fixtures/article-diagram-personal.jsonconfig11.4 KB
evals/fixtures/big-reading.jsonconfig3.7 KB
evals/fixtures/comic-moment-notes/interaction.pngbinary2.2 MB
evals/fixtures/comic-moment-notes/jobs.mjsscript2.9 KB
evals/fixtures/comic-moment-notes/rousseau.pngbinary2.1 MB
evals/fixtures/comic-moment-notes/uncertainty-art.pngbinary1.6 MB
evals/fixtures/font-load-failed.htmlother830 B
evals/fixtures/infograph-comparison-notes/a2a.jsonconfig5.3 KB
evals/fixtures/infograph-comparison-notes/cursor.jsonconfig4.4 KB
evals/fixtures/infograph-comparison-notes/dense.jsonconfig7.1 KB
evals/fixtures/infograph-comparison-notes/interaction.jsonconfig6.3 KB
evals/fixtures/infograph-comparison-notes/loading.jsonconfig5.4 KB
evals/fixtures/infograph-comparison-notes/metrics.jsonconfig4.4 KB
evals/fixtures/infograph-comparison-notes/overview.jsonconfig6.9 KB
evals/fixtures/infograph-comparison-notes/stability.jsonconfig4.6 KB
evals/fixtures/long-notes.jsonconfig9.5 KB
evals/fixtures/poster-field-notes.jsonconfig2.2 KB
evals/fixtures/retired-cover-pair.jsonconfig7.5 KB
evals/fixtures/sketchnote-wandering-notes/a2a.jsonconfig6.3 KB
evals/fixtures/sketchnote-wandering-notes/rousseau.jsonconfig5.1 KB
evals/fixtures/sketchnote-wandering-notes/uncertainty.jsonconfig5.1 KB
evals/fixtures/svg-text-outside-viewbox.htmlother1.3 KB
evals/fixtures/svg-text-overflow.htmlother1.0 KB
evals/fixtures/whiteboard-notes-series.job.jsonconfig10.3 KB
evals/fixtures/whiteboard-notes.jsonconfig15.2 KB
evals/fresh-context-long-results.jsonconfig1.3 KB
evals/fresh-context-results.jsonconfig10.6 KB
evals/gallery/creative/comic.jsonconfig2.4 KB
evals/gallery/creative/infograph.jsonconfig4.4 KB
evals/gallery/creative/sketchnote.jsonconfig5.1 KB
evals/gallery/jobs/article-boundary-legacy.jsonconfig1.7 KB
evals/gallery/jobs/article-formula.jsonconfig2.0 KB
evals/gallery/jobs/article-personal.jsonconfig1.8 KB
evals/gallery/jobs/big.jsonconfig1.2 KB
evals/gallery/jobs/editorial-wechat-cover.jsonconfig2.1 KB
evals/gallery/jobs/long.jsonconfig5.1 KB
evals/gallery/jobs/poster.jsonconfig1.1 KB
evals/gallery/jobs/reading-notes.jsonconfig1.7 KB
evals/gallery/jobs/reading-report.jsonconfig1.2 KB
evals/gallery/jobs/whiteboard.jsonconfig3.0 KB
evals/run-discovery.mjsscript10.1 KB
evals/run-fresh-context.mjsscript26.1 KB
evals/runtime-policy.mjsscript1.3 KB
package-lock.jsonmanifest1.7 KB
package.jsonmanifest1.0 KB
references/article-diagram-personal.mdmarkdown5.6 KB
references/codex-inline-preview.mdmarkdown8.4 KB
references/cover-paper-wilderness.mdmarkdown5.9 KB
references/design-index.mdmarkdown3.7 KB
references/design-memory.jsonconfig154 B
references/eval-protocol.mdmarkdown11.2 KB
references/mode-article-diagram.mdmarkdown594 B
references/mode-big.mdmarkdown3.6 KB
references/mode-comic.mdmarkdown4.3 KB
references/mode-editorial-image.mdmarkdown3.0 KB
references/mode-infograph.mdmarkdown5.3 KB
references/mode-long.mdmarkdown4.2 KB
references/mode-poster.mdmarkdown12.3 KB
references/mode-sketchnote.mdmarkdown2.0 KB
references/mode-whiteboard.mdmarkdown1.8 KB
references/personal-style-migration.mdmarkdown2.8 KB
references/poster-field-notes.mdmarkdown3.3 KB
references/runtime.mdmarkdown2.9 KB
references/sketchnote-wandering-notes.mdmarkdown5.6 KB
references/source-material.mdmarkdown4.0 KB
references/source-open-source-tool.mdmarkdown5.1 KB
references/source-weread.mdmarkdown8.0 KB
references/taste.mdmarkdown15.0 KB
references/visual-job.mdmarkdown10.7 KB
references/visual-review.mdmarkdown4.7 KB
references/visual-taxonomy.mdmarkdown2.1 KB
references/whiteboard-reasoning-notes.mdmarkdown4.9 KB
schemas/article-diagram.jsonconfig5.1 KB
schemas/big.jsonconfig3.8 KB
schemas/comic.jsonconfig2.0 KB
schemas/editorial-image.jsonconfig8.5 KB
schemas/infograph.jsonconfig1.5 KB
schemas/long.jsonconfig6.5 KB
schemas/poster.jsonconfig13.8 KB
schemas/sketchnote.jsonconfig1.4 KB
schemas/visual-job.jsonconfig11.4 KB
schemas/visual-review.jsonconfig2.5 KB
schemas/whiteboard.jsonconfig8.5 KB
scripts/batch_render_covers.jsscript15.0 KB
scripts/batch_render_covers_dark.jsscript11.6 KB
scripts/card.jsscript22.4 KB
scripts/check-output.mjsscript57.4 KB
scripts/check-update.mjsscript32.7 KB
scripts/gallery-jobs.mjsscript12.5 KB
scripts/hash-reviewed-candidate.mjsscript799 B
scripts/lib/big-reading.jsscript3.0 KB
scripts/lib/candidate-snapshot.jsscript3.9 KB
scripts/lib/comic-art.jsscript958 B
scripts/lib/designs.jsscript9.3 KB
scripts/lib/escape.jsscript919 B
scripts/lib/file-access.jsscript10.6 KB
scripts/lib/long-notes.jsscript1.6 KB
scripts/lib/mode-selector.jsscript1.7 KB
scripts/lib/output-checks.jsscript26.0 KB
scripts/lib/personal-diagram.jsscript4.2 KB
scripts/lib/publish-artifacts.jsscript4.0 KB
scripts/lib/schema.jsscript31.5 KB
scripts/lib/test-kit.jsscript3.1 KB
scripts/lib/update-launcher.jsscript1.9 KB
scripts/lib/update-state.jsscript4.8 KB
scripts/lib/visual-job.jsscript39.5 KB
scripts/lib/visual-review.jsscript5.8 KB
scripts/lib/whiteboard-notes.jsscript5.8 KB
scripts/package-skill.mjsscript1.4 KB
scripts/publish-reviewed-job.mjsscript25.4 KB
scripts/render-job.mjsscript15.4 KB
scripts/renderers/article-diagram-personal.jsscript10.4 KB
scripts/renderers/article-diagram.jsscript133 B
scripts/renderers/big.jsscript5.6 KB
scripts/renderers/editorial-image.jsscript9.4 KB
scripts/renderers/long.jsscript5.9 KB
scripts/renderers/poster.jsscript12.3 KB
scripts/renderers/studio-composition.jsscript6.7 KB
scripts/renderers/whiteboard-notes.jsscript3.0 KB
scripts/renderers/whiteboard.jsscript104 B
scripts/setup-runtime.mjsscript2.7 KB
scripts/smoke.mjsscript8.5 KB
scripts/validate-big-reading.mjsscript3.5 KB
scripts/validate-comic-notes.mjsscript7.1 KB
scripts/validate-editorial-cover.mjsscript14.0 KB
scripts/validate-infograph-notes.mjsscript5.1 KB
scripts/validate-long-notes.mjsscript3.4 KB
scripts/validate-personal-defaults.mjsscript3.1 KB
scripts/validate-personal-diagram.mjsscript5.7 KB
scripts/validate-sketchnote-notes.mjsscript5.4 KB
scripts/validate-visual-job.mjsscript89.5 KB
scripts/validate-whiteboard-notes.mjsscript4.9 KB
scripts/validate.mjsscript100.2 KB

docs/current-architecture.md

View on GitHub
# Current architecture

card-skill is a local, source-aware visual production pipeline for AI agents. The agent owns evidence and semantic judgment; the Node.js runtime owns contracts, deterministic rendering, checks, hashes, and publication.

```text
content / normalized adapter
        |
        v
SourceBrief (host-only)
  evidence inventory + freshness + rights
        |
        v
Visual Job v3
  source_units[].evidence
  decision
  outputs[].artifacts[].visual_plan
  outputs[].render_contract
        |
        v
runtime validation + visual taxonomy
        |
        v
render-job --candidate
        |
        v
card.js -> mode renderer -> temporary HTML -> Playwright PNG -> check-output
        |
        v
candidate PNG + receipt + checked HTML + closed-set manifest
        |
        v
host Agent inspects every real PNG -> Visual Review
        | pass                         | revise once
        v                              +----> new plan + contract -> full render/check/review
publish-reviewed-job
        |
        v
PNG + receipt + review
```

## Inputs and core objects

| Concept | Runtime representation | Owner |
|---|---|---|
| Source brief | host-only evidence inventory, freshness, rights, archetype | source adapter / host Agent |
| Evidence | `source_units[].evidence` in Visual Job v3 | host Agent, runtime-validated |
| Artifact plan | `outputs[].artifacts[]` in Visual Job v3 | host Agent, constrained by evidence and taxonomy |
| CardSpec | `outputs[].render_contract` | mode schema and renderer |
| Color layer | `decision.tone`, contract `tone` / `editorial_tone`, optional exact `design`; colors only | Kenny Style palette resolver |
| Layout | artifact `visual_plan.layout_strategy`, then selected renderer | Agent intent + renderer implementation |
| Renderer | `scripts/renderers/*` selected by `card.js` | deterministic Node runtime |
| Validator | `scripts/lib/schema.js`, `scripts/lib/visual-job.js`, `scripts/lib/visual-review.js` | runtime contract boundary |
| EvalCase | `evals/agent-cases.json` plus assertion and isolated render runners | CardBench |

V3 separates a renderer output from its produced artifacts. One poster output can own three cards, while each PNG has its own evidence references, role, filename, transformation, and Visual Plan. The runtime requires one current primary evidence unit per artifact and exact artifact-count parity with the render contract. V1/V2 remain accepted for compatibility.

## Routing and modes

`SKILL.md` is the production entry and a conditional reference router. Source adapters, mode documents, runtime recovery, and evaluation instructions are loaded for their specific task. An explicit candidate-selection request is the only default direction checkpoint; an image-capable host Agent otherwise completes local delivery through review and publication.

Source routing precedes mode selection. A source adapter such as `source-open-source-tool.md` chooses evidence responsibilities and an adaptive artifact count; it never adds a renderer or bypasses taxonomy. `scripts/lib/mode-selector.js` then maps publish target, content type, and argument structure to one of the existing nine modes. A user may explicitly override a mode; an Agent may not silently do so.

Stable modes are `big`, `long`, `whiteboard`, `poster`, `article-diagram`, and cover-form `editorial-image`. Studio modes are `infograph`, `comic`, `sketchnote`, and composition-required `editorial-image`. Studio contracts still use the same schema, capture, checker, receipt, review, and publication chain.

## Rendering, validation, and publication

`scripts/card.js` remains the low-level renderer and accepts an existing mode contract. `scripts/render-job.mjs` validates a Visual Job, renders every output in an OS temporary directory, and produces one receipt per PNG. Visual Job v2 and v3 candidates preserve the sealed Visual Job, exact checked HTML, per-artifact contract hashes, and a manifest that closes the expected output/artifact set. Both must use `--candidate`; once the candidate-directory digest has been approved outside that directory, their artifacts cannot be mistaken for reviewed final output or downgraded to a legacy partial candidate without invalidating that approval. Legacy v1 candidates remain an explicit compatibility path, but publication additionally requires `--allow-legacy-v1` so a stripped v2/v3 candidate cannot silently enter that path before approval.

`scripts/check-output.mjs` rejects machine-detectable defects such as overflow, clipping, missing images, unsafe resources, unresolved placeholders, and undersized text. It does not score composition. The host Agent inspects each checked PNG, writes a hash-bound Visual Review, and records the reviewed candidate-directory digest outside that directory. `scripts/publish-reviewed-job.mjs` requires that external approval digest, copies the bounded regular-file candidate set into a private stable snapshot, then re-runs `check-output` and a trusted screenshot under a response-header CSP that blocks scripts and frames before candidate markup is parsed, with hard timeouts and capture/PNG byte and pixel budgets. Publication requires the recaptured PNG to match the reviewed candidate bytes, then publishes only passing PNG/receipt/review triples as one transaction. Checked HTML and the candidate manifest remain internal and are not final artifacts.

Poster evidence media remains offline and bounded. Its structured contract names an explicit local PNG/JPEG/WebP source; before Chromium starts, `card.js` copies the bytes through a private snapshot capped both per file and across the poster, validates the container, dimensions, decoded-pixel budget, and SHA-256, then embeds that sealed snapshot in the checked HTML. Optional logos use the same private-snapshot pattern with a smaller budget. Original media and logo paths are never browser allow-list entries. Short process evidence is renderer-owned structured HTML with two to five steps, not caller-supplied markup or a diagram screenshot embedded inside another card.

Renderers never fetch repository pages or provider content. Source adapters normalize upstream material before the Visual Job, and unclear rights or freshness keep media out of public outputs.

## Update wiring

Direct renders and job renders intentionally keep different update wirings. `card.js` is the skill entry: it holds a render lease, nudges the update check on every run so direct CLI use stays covered even when the calling agent skips the skill preflight, verifies the runtime, and launches one auto-update after a successful render. `render-job.mjs` is the orchestrator: its child renders run with both update checks disabled (no per-child nudge or self-update), and the job launches a single post-job update. Both share `scripts/lib/update-launcher.js` — one spawn shape, one gate on `CARD_SKILL_DISABLE_AUTO_UPDATE` applied before spawning. A shared render-prelude module has been considered and rejected: the entry and orchestrator need different subsets by design, so a prelude interface would not absorb the difference.

## Evaluation

`npm test` runs deterministic L0 contract and regression checks without a model. `npm run eval:fresh` evaluates fresh planning cases, including evidence-first open-source routing. `npm run eval:cardbench` adds forced-revision cases, real PNG Critic calls, one-revision enforcement, and Content/Visual/Agent scores. Reports keep unmeasured levels as `null`; Agent critique is not presented as maintainer or real-user evidence.

`npm run eval:discovery` separately probes catalog selection, conditional reference routing, and requested versus unrequested user checkpoints. It records model-reported decisions and observed commands; it does not render or establish end-to-end visual quality. Fresh planning reports identify their prompt profile so results from the former coached prompt are not silently compared with skill-routed runs.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall