Technical Explainer Illustrator

简体中文

An evidence-first Agent Skill for turning repositories, technical reports, papers, READMEs, and long-form technical articles into high-density explainer images.

It separates trustworthy source material from visual interpretation, then routes each frame through the safest production method:

• reuse: preserve an authoritative source figure.
• deterministic: draw exact charts, tables, labels, or topology with code.
• generate: create an editorial 2.5D mechanism metaphor.
• hybrid: combine a generated scene with deterministic overlays.

Why This Skill Exists

Most image workflows optimize the prompt before they verify the source. That is backwards for technical explanation. This Skill starts with a source manifest and claim ledger, binds exact values to locators, and refuses to send unverified data to an image model.

The result is a reusable production system rather than a one-off style prompt:

• Evidence-grounded claims and source revisions.
• Four rendering routes chosen frame by frame.
• Nine reusable composition patterns.
• Structured prompt packs with exact-data constraints.
• Standard-library Python validation and a no-network self-test.
• QA records for factual, text, composition, style, and crop failures.

Install

Install only this Skill with the open-source skills CLI:

npx skills add lhylvsea/technical-explainer-illustrator \
  --skill technical-explainer-illustrator \
  --global \
  --yes

Install into a specific supported agent:

npx skills add lhylvsea/technical-explainer-illustrator \
  --skill technical-explainer-illustrator \
  --agent codex \
  --global \
  --yes

You can also copy skills/technical-explainer-illustrator into the Skill directory used by your agent. The directory must remain intact because SKILL.md loads the reference and script files by relative path.

Quick Start

Give the agent a GitHub URL, local repository, PDF, README, article URL, or pasted source text:

Use $technical-explainer-illustrator to study this GitHub repository and create
six 16:9 Chinese technical explainer images. Preserve authoritative figures and
bind every number to a source locator.

The Skill normally produces:

<project>/
├── SOURCE-MANIFEST.json
├── CLAIM-LEDGER.json
├── VISUAL-PLAN.json
├── sources/
├── prompts/
├── images/
└── review/
    └── QA.md

Image generation is optional. Without an image tool, the Skill still produces the evidence pack, visual plan, deterministic assets, and reproducible prompt pack.

Example

examples/kimi-k3 is a source-grounded smoke project based on the official MoonshotAI/Kimi-K3 repository. It demonstrates all four routes and includes one rendered deterministic frame. It does not bundle the reference article's images.

Validate

No third-party Python package is required:

python scripts/validate_repo.py

The validator checks the Skill entrypoint, frontmatter, required references, example prompt pack, and the full no-network self-test. GitHub Actions runs the same checks on Windows and Linux.

Design And Trust Boundaries

• Exact charts and architecture diagrams should be reused or rendered deterministically, not hallucinated by an image model.
• Generated images explain mechanisms; they are not implementation traces.
• Private repositories require authorized local or connected access.
• Reference images are not redistributed. This project extracts abstract design rules rather than copying watermarks, brand marks, or protected layout assets.
• The agent still needs an available image-generation or rendering tool to produce generated and hybrid final images.

Project Layout

skills/technical-explainer-illustrator/  # Installable Skill
examples/kimi-k3/                         # Auditable sample project
scripts/validate_repo.py                  # Repository-level validation
.github/workflows/validate.yml            # Windows and Linux CI

License

The original code and Skill instructions in this repository are released under the MIT License. See NOTICE.md for research sources and third-party attribution.