fireworks-open-eli5 README

The project's README from github.com/yizhiyanhua-ai/fireworks-open-eli5. As one markdown file: README.md.

Fireworks Open ELI5 owl

Fireworks Open ELI5

English · 简体中文

An open, portable Agent Skill for turning difficult systems into truthful, interactive visual stories. It compiles a versioned JSON story spec into one deterministic, self-contained HTML file that works offline.

The project combines an ELI5 layer with inspectable technical truth: readers can follow a real request or event through the system, inspect the evidence behind each conclusion, explore failure behavior, annotate scenes, and export the result without sending source material to a remote runtime.

Agent architecture explainer with a source-backed scene

A generated Chinese scene showing the graph, local actions, and conclusion-level evidence together.

Why it is different

Requirements

The installer and the installed Skill have separate requirements. The [email protected] CLI used by the release canary requires Node.js 22.20 or newer; the installed Skill still runs on Node.js 18 or newer. Installation needs one-time access to the public GitHub repository; the npx route also needs the npm registry. A public install needs no GitHub account or token.

Install

Paste one of these requests into your agent. It should inspect SKILL.md, refuse to overwrite an existing installation without permission, and report the final location.

Codex

Install the fireworks-open-eli5 Agent Skill globally from https://github.com/yizhiyanhua-ai/fireworks-open-eli5 using Codex's Skill installer. The repository root (.) is the Skill directory and its installed name must be fireworks-open-eli5. Review SKILL.md first, do not replace an existing copy without asking, verify the installed path, and tell me whether I need a new Codex task before using it.

Claude Code

Install the fireworks-open-eli5 Agent Skill globally for Claude Code from https://github.com/yizhiyanhua-ai/fireworks-open-eli5. Review SKILL.md first, use the Agent Skills CLI when available, and do not replace an existing copy without asking. If the installer requirement is not met, report it without changing my Node.js installation. Verify that Claude Code can discover the Skill and report the installed path.

Install with npx

The open Agent Skills CLI supports both Codex and Claude Code:

# Codex
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -y

# Claude Code
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a claude-code -y

# Both agents
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -a claude-code -y

-g installs at user scope. Remove it for a project-local installation. Check the result with npx skills@latest list -g --json, then start a fresh agent task so the Skill is rediscovered. Review Skills before using them: they run with the permissions of the host agent.

Quick start

node scripts/validate.mjs assets/example-spec.json
node scripts/render.mjs assets/example-spec.json example.html
node scripts/validate.mjs assets/example-spec.json example.html

The commands print compact JSON and exit nonzero on failure. Rendering is create-only by default. Use --force only to intentionally replace a known regular file; symbolic links are always rejected.

Run the complete contributor and distribution gate:

npm run check

This checks JavaScript syntax, focused tests, the canonical example, release package contents, and a render/validate canary from an unpacked archive.

On Node.js 22.20 or newer, also exercise an isolated Codex and Claude Code installation through the pinned Agent Skills CLI release:

npm run check:agent-install

Use as an Agent Skill

After installation, ask for an evidence-aware visual explanation, for example:

Explain how one queued job moves through this repository. Cite real files, let me play the request path, and show what breaks when the lease expires.

Read SKILL.md for the agent workflow and references/spec-contract.md for the version 1 story spec.

Story pipeline

question + audience + evidence
            │
            ▼
  versioned JSON story spec
            │ validate
            ▼
 deterministic HTML renderer
            │
            ├── offline interactive explainer
            ├── print / PDF
            ├── current-scene PNG
            ├── all-scene PPTX
            ├── Pages-compatible DOCX
            └── optional native Pages conversion

The JSON spec is the portable source of truth. The HTML contains its canonical SHA-256, and the validator can byte-compare a supplied spec against a fresh deterministic render.

Reader workspace

Every explainer has a directory drawer. Favorites appear first, followed by independent tabs for the current outline, previously opened explainers, and annotation browsing. A reader can play, favorite, annotate, or export one scene without starting the global trace.

The local library is disabled until the reader selects Enable local library. It records only explainers actually opened at the same scheme, host, and port; it never scans the filesystem. Favorites and annotations are browser-local, unencrypted, and removed when that origin's browser data is cleared. They never modify the source JSON or generated HTML. file:// and unavailable storage degrade to an in-memory session.

See references/library-and-export.md for the persistence, privacy, accessibility, playback, and export contract.

Export

Action Result Verification boundary
Print / PDF Browser print dialog The reader chooses Save as PDF when available
PNG 1600×900 image of the selected scene PNG signature, dimensions, and scene evidence footer
PPTX One 16:9 slide per scene ZIP signature and required OOXML parts
DOCX One 16:9 page per scene ZIP signature and required OOXML parts
Native Pages A real .pages package saved by Apple Pages Must contain Index/Document.iwa and reopen in Pages

PNG, PPTX, and DOCX are built locally in the browser without third-party libraries. Native Pages conversion is never faked by renaming a DOCX. Serve a trusted explainer directory with:

node scripts/serve.mjs --root /absolute/path/to/explainers --port 8772

The helper binds only to 127.0.0.1, verifies exact origin and a rotating process token, bounds and validates the generated DOCX/PNG structure, serializes conversion, and cleans task-specific temporary files. These controls protect the browser action from cross-site requests; they are not authentication against other local processes.

Security and privacy

The renderer reads local files and writes one local file. Generated HTML uses a hash-whitelisted Content Security Policy, embeds no remote resources, and contains no XHR, WebSocket, eval, or HTML-string DOM insertion. Its only connection is a user-initiated same-origin request to the optional loopback Pages helper. Cited HTTP(S) URLs are ordinary reader-facing links, never runtime dependencies.

Annotations are capped and inserted as text. The validator rejects unsafe source URLs, external resources, runtime tampering, spec-hash drift, and unexpected CSP hashes. See SECURITY.md to report a vulnerability.

Project map

Contributing

Read CONTRIBUTING.md, then run:

npm run check

The release package uses an explicit allowlist and keeps private: true to prevent accidental npm publication. This repository is intended to distribute an Agent Skill, not an npm runtime library.

License and attribution

Apache-2.0. See LICENSE and NOTICE.

Fireworks Open ELI5 is an independent implementation inspired by the Anthropic community eli5 skill and is not endorsed by Anthropic.

fireworks-open-eli5 (yizhiyanhua-ai/fireworks-open-eli5)

Searching Database…

189 ·GitHub
Fireworks-open-eli5
What is this?Fireworks Open ELI5 is an Agent Skill for Codex and Claude Code that turns complex systems into evidence-aware, interactive visual explainers. It compiles a versioned JSON story spec into one deterministic, self-contained HTML file that works offline.
Is this a standalone app or something I plug into my AI agent?It is an Agent Skill meant to be installed into Codex or Claude Code, not a standalone application or an npm runtime library.
How do I install it into Codex or Claude Code?The recommended way is to paste a natural-language install request into your agent asking it to install the fireworks-open-eli5 Agent Skill; it will inspect SKILL.md and report the installed path. Alternatively, install with the open Agent Skills CLI via npx, using -g for a global install.
Do I need anything besides Node.js to use it?Just Node.js 18 or newer and local file access; there are no npm package dependencies, Python runtime, remote fonts, or network access needed to render.
Does the native .pages export work on any OS?No, the verified native .pages conversion needs macOS, Apple Pages, and the bundled loopback helper. PDF, PNG, PPTX, and DOCX exports work everywhere in the browser.
Can the generated explainer be viewed without an internet connection?Yes, the output is a single self-contained HTML file with no remote resources, designed to render and be read fully offline.
Does any of my data or source material leave my machine?No. The generated HTML embeds no remote resources and has no XHR, WebSocket, eval, or network calls; its only connection is an optional, user-initiated same-origin request to the local Pages helper.
What is the Truth Ladder?It is the project's structure for separating analogy, technical mechanism, and caveats within each scene, so readers get a simple explanation alongside the rigorous technical truth.
What story types can it produce?Four story grammars are supported: concept, repository module, engineering tradeoff, and incident, each with its own summary view and semantic validator.
What export formats are available?Explainers can be exported as PDF (browser print), scene PNG, an all-scene PPTX, a Pages-compatible DOCX, and an optionally verified native .pages file on macOS.
Does it remember what I've already read?There is an opt-in local library that only records explainers you actually opened in the browser at that origin; it is unencrypted and cleared when browser data for that site is cleared.
What are similar projects?dashi-ppt-skill, easyread, software-certificate-skill, SenseNova-Skills, OfficeCLI, Kami, jinba-consulting-pptx-skill, agentplay
Which topics is it in?docx, pptx, skill-md, interactive, offline-first, agent-skill, visualization, json, pdf, offline, agent-skills, codex
Creator
yizhiyanhua-ai
Size
0.6 MB
Stars
189
Updated
CommitAug 24
Age
1mo
Commits · 90 Days