Skip to content
Back to search

fireworks-open-eli5

Create evidence-aware, interactive visual explainers as self-contained offline HTML. Use when a user asks to explain a concept, repository module, engineering tradeoff, or incident with a diagram, walkthrough, ELI5 treatment, data/request trace, failure view, or teach-back. Do not use for a plain short answer, ordinary prose rewrite, generic website implementation, or unsupported claims presented as facts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yizhiyanhua-ai--fireworks-open-eli5/badge.svg)](/listings/yizhiyanhua-ai--fireworks-open-eli5)

HTML

<a href="/listings/yizhiyanhua-ai--fireworks-open-eli5"><img src="/api/listings/yizhiyanhua-ai--fireworks-open-eli5/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Natural language (recommended)

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](https://github.com/vercel-labs/skills) 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 159 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: fireworks-open-eli5
  3. description: Create evidence-aware, interactive visual explainers as self-contained offline HTML. Use when a user asks to explain a concept, repository module, engineering tradeoff, or incident with a diagram, walkthrough, ELI5 treatment, data/request trace, failure view, or teach-back. Do not use for a plain short answer, ordinary prose rewrite, generic website implementation, or unsupported claims presented as facts.
  4. license: Apache-2.0
  5. compatibility: Codex, Claude Code, or another Agent Skills-compatible host with Node.js 18+ and local file access; no npm packages or network access required at render time. Native Pages export optionally requires macOS and Apple Pages.
  6. ---
  7. # Fireworks Open ELI5
  8. Turn a difficult system into a truthful visual story. Produce a portable JSON
  9. spec first, then a deterministic, self-contained HTML explainer.
  10. ## Non-negotiable boundary
  11. - Evidence comes before visual polish. Label every evidence item `verified`,
  12. `inferred`, or `analogy`.
  13. - Never make an analogy look like implementation truth.
  14. - A generated local HTML file is only `generated`. It is not `published`,
  15. uploaded, sent, or destination-verified.
  16. - Do not publish, upload, send, or change access without the user's explicit
  17. request and the destination workflow's own verification.
  18. - Rendering performs no network calls. A cited URL is a reader-facing link, not
  19. a runtime dependency. The optional native Pages action may call only the
  20. bundled same-origin helper on `127.0.0.1`; it must never contact a remote
  21. service.
  22. - Browser-local history, favorites, and annotations are disabled until the
  23. reader opts in. They are convenience state, not evidence and never modify the
  24. source spec or generated artifact.
  25. - Describe history precisely as same-origin explainers previously opened in
  26. that browser. Never claim that it enumerates every generated file.
  27. - PDF export invokes the browser print dialog. PNG exports one scene; PPTX and
  28. Pages-compatible DOCX export one scene per slide or page. Native `.pages`
  29. output is allowed only after the installed Pages app really saves it; never
  30. rename a DOCX to `.pages`. Generated downloads are local artifacts only.
  31. ## Workflow
  32. 1. Identify the audience, question, language, and one thing that should travel
  33. through the story: a request, packet, decision, event, or user action.
  34. 2. Choose exactly one story grammar:
  35. - `concept`: intuition → mechanism → boundary.
  36. - `module`: entry point → transformations → outputs/dependencies.
  37. - `tradeoff`: shared goal → competing options → consequences/decision rule.
  38. - `incident`: normal path → break and propagation → detection/recovery.
  39. 3. Gather evidence. For repository work, inspect actual files and use local
  40. paths. For external claims, use authoritative sources when available. Record
  41. uncertainty explicitly.
  42. 4. Create a version 1 JSON spec following
  43. [references/spec-contract.md](references/spec-contract.md). Use 3–7 scenes,
  44. 2–6 nodes per scene, a complete truth ladder, trace, glossary, teach-back,
  45. evidence map, and the required mode-specific `modeData`. Add failure
  46. information to consequential nodes.
  47. 5. Validate before rendering:
  48. ```bash
  49. node scripts/validate.mjs path/to/spec.json
  50. ```
  51. 6. Render to a new local file:
  52. ```bash
  53. node scripts/render.mjs path/to/spec.json path/to/explainer.html
  54. ```
  55. The renderer refuses an existing path. Only when the user explicitly wants
  56. to replace a known regular file, append `--force`. Forced rendering uses an
  57. atomic replacement and still refuses symbolic links and non-file paths.
  58. 7. Validate the spec and artifact together:
  59. ```bash
  60. node scripts/validate.mjs path/to/spec.json path/to/explainer.html
  61. ```
  62. 8. When browser access is available, inspect the local artifact at desktop
  63. width and 390px. Confirm one `h1`, readable labels, no horizontal overflow,
  64. keyboard focus, independent tablists, global and scene-local playback,
  65. viewport following, active real-edge and evidence-card synchronization,
  66. enter/hold/exit animation phases, failure lens, answer reveals, and zero
  67. remote resource requests. Every scene evidence card must expose its status,
  68. concise core basis, support scope, and a URL or explicit no-locator boundary.
  69. 9. Exercise the reader workspace: open and dismiss the modal drawer by mouse
  70. and keyboard; confirm focus return; enable the library intentionally; reload
  71. and verify favorites and a plain-text annotation; and confirm history
  72. contains only same-origin explainers that were actually opened. Use a
  73. markup-shaped annotation to verify it stays inert text.
  74. 10. Exercise export: confirm the print stylesheet, PNG signature and dimensions,
  75. PPTX and DOCX ZIP signatures and required OOXML parts, and the fallback
  76. download link when automatic downloads are suppressed. Visually confirm
  77. that scene artwork includes a bounded evidence footer with status, core
  78. basis, and source locator or boundary. When native Pages is in scope, run
  79. through `scripts/serve.mjs`, verify the `.pages` package contains
  80. `Index/Document.iwa`, then reopen it in Pages. Fix the spec or template and
  81. rerun both validators after any change.
  82. ## Report language
  83. - Write the final QA, status, handoff, and generated-artifact report in the
  84. language of the user's latest substantive request by default.
  85. - An explicit report-language request overrides that default.
  86. - `spec.language` controls the generated explainer interface only; it does not
  87. force the conversation report language.
  88. - In mixed-language conversations, ignore short acknowledgements when choosing
  89. the report language. Preserve code, commands, paths, identifiers, exact
  90. errors, and source titles when translation would reduce precision.
  91. Read [references/reporting.md](references/reporting.md) for the full language
  92. selection and delivery-report contract.
  93. ## Story construction rules
  94. - Write the title as a concrete promise, not a category label.
  95. - Keep the summary to one sentence and every node to one responsibility.
  96. - Prefer 3–5 scenes. Use 6–7 only when omitting a stage would distort causality.
  97. - Edges are relationships or actions. Use short verbs on labels.
  98. - The trace must visit real node IDs in a meaningful order.
  99. - Use failure data only when impact, visible symptom, and fallback are known.
  100. - Keep the simple layer accurate enough to survive the technical layer.
  101. - Put limitations in `truthLadder.caveat`, not in tiny disclaimers.
  102. - Use source IDs on the scenes or nodes they support.
  103. - Do not cite a source merely because it is adjacent to the claim.
  104. Read [references/story-grammars.md](references/story-grammars.md) for mode
  105. patterns, [references/evidence-rules.md](references/evidence-rules.md) for
  106. claim boundaries, and [references/visual-system.md](references/visual-system.md)
  107. before changing the renderer's visual language. Read
  108. [references/library-and-export.md](references/library-and-export.md) before
  109. changing persistence, navigation, playback, or export behavior.
  110. ## Quality gate
  111. The work is ready as a local artifact only when:
  112. - the validator returns `ok: true` for the spec and rendered HTML;
  113. - all IDs and references resolve;
  114. - every required interactive section has content;
  115. - the selected story mode passes its own semantic contract;
  116. - the HTML is deterministic and carries the spec SHA-256 meta tag;
  117. - the artifact byte-matches the supplied spec and uses trusted CSP hashes;
  118. - the artifact has no external resources, unsafe runtime APIs, or remote fonts;
  119. - persisted reader state is opt-in, namespaced, bounded, same-origin, and kept
  120. outside the deterministic spec hash;
  121. - annotations are rendered only as text and cannot create executable markup;
  122. - global and local playback share one state machine and never run together;
  123. - each trace step activates the real outgoing relationship path (or a sink's
  124. incoming path), keeps label and arrow state aligned, and highlights only the
  125. evidence that supports that step;
  126. - scene evidence cards preserve verified/inferred/analogy boundaries and expose
  127. core text plus an actionable locator without fetching remote previews;
  128. - scene PNG, PPTX, and DOCX packages have the expected signatures and
  129. structure and contain their evidence footer; a claimed native Pages export
  130. has also reopened in Pages;
  131. - mobile uses the stacked flow rather than shrinking the desktop SVG;
  132. - the final report follows the user's current interaction language, names the
  133. generated spec and HTML paths, and says whether desktop, mobile, persistence,
  134. playback, evidence, and export browser QA were run.
  135. If evidence is incomplete, generate only when the evidence map and caveat make
  136. the gap unmistakable. Otherwise stop and report the missing evidence.
README.md · README · 251 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/logo.png" alt="Fireworks Open ELI5 owl" width="168">
  3. </p>
  4. <h1 align="center">Fireworks Open ELI5</h1>
  5. [English](README.md) · [简体中文](README.zh.md)
  6. An open, portable Agent Skill for turning difficult systems into truthful,
  7. interactive visual stories. It compiles a versioned JSON story spec into one
  8. deterministic, self-contained HTML file that works offline.
  9. The project combines an ELI5 layer with inspectable technical truth: readers
  10. can follow a real request or event through the system, inspect the evidence
  11. behind each conclusion, explore failure behavior, annotate scenes, and export
  12. the result without sending source material to a remote runtime.
  13. ![Agent architecture explainer with a source-backed scene](assets/readme-agent-architecture-preview.png)
  14. _A generated Chinese scene showing the graph, local actions, and conclusion-level evidence together._
  15. ## Why it is different
  16. - **Truth Ladder** — separates analogy, technical mechanism, and caveats.
  17. - **Evidence at the claim** — each scene can show source status, core text,
  18. support scope, and a URL or explicit no-locator boundary.
  19. - **Four story grammars** — concept, repository module, engineering tradeoff,
  20. and incident, each with a dedicated summary view and semantic validator.
  21. - **Detailed playback** — global or scene-local traces animate real nodes,
  22. relationships, labels, arrow markers, evidence cards, and enter/hold/exit
  23. phases while keeping the active scene in view.
  24. - **Failure lens and teach-back** — impact, symptom, fallback, questions, and
  25. answer reveals are part of the explainer rather than an appendix.
  26. - **Reader workspace** — opt-in same-origin history, favorites, plain-text
  27. annotations, and keyboard-accessible scene navigation.
  28. - **Local export** — PDF, scene PNG, all-scene PPTX, Pages-compatible DOCX, and
  29. optional verified native `.pages` conversion.
  30. - **Portable by construction** — no runtime packages, remote fonts, remote
  31. resources, or network access during render.
  32. ## Requirements
  33. - **Skill runtime:** Node.js 18 or newer and local file access.
  34. - **Package dependencies:** none. There is no `npm install`, Python runtime,
  35. remote font, or remote rendering service.
  36. - **Rendering:** no browser or network connection is required.
  37. - **Reading and export:** use a modern browser for the interactive HTML and
  38. local PDF, PNG, PPTX, or DOCX export.
  39. - **Optional native `.pages` export:** macOS, Apple Pages, and the bundled
  40. loopback helper.
  41. The installer and the installed Skill have separate requirements. The
  42. `skills@1.5.23` CLI used by the release canary requires Node.js 22.20 or newer;
  43. the installed Skill still runs on Node.js 18 or newer. Installation needs
  44. one-time access to the public GitHub repository; the `npx` route also needs the
  45. npm registry. A public install needs no GitHub account or token.
  46. ## Install
  47. ### Natural language (recommended)
  48. Paste one of these requests into your agent. It should inspect `SKILL.md`,
  49. refuse to overwrite an existing installation without permission, and report
  50. the final location.
  51. **Codex**
  52. > Install the `fireworks-open-eli5` Agent Skill globally from
  53. > `https://github.com/yizhiyanhua-ai/fireworks-open-eli5` using Codex's Skill
  54. > installer. The repository root (`.`) is the Skill directory and its installed
  55. > name must be `fireworks-open-eli5`. Review `SKILL.md` first, do not replace an
  56. > existing copy without asking, verify the installed path, and tell me whether
  57. > I need a new Codex task before using it.
  58. **Claude Code**
  59. > Install the `fireworks-open-eli5` Agent Skill globally for Claude Code from
  60. > `https://github.com/yizhiyanhua-ai/fireworks-open-eli5`. Review `SKILL.md`
  61. > first, use the Agent Skills CLI when available, and do not replace an existing
  62. > copy without asking. If the installer requirement is not met, report it
  63. > without changing my Node.js installation. Verify that Claude Code can
  64. > discover the Skill and report the installed path.
  65. ### Install with `npx`
  66. The open [Agent Skills CLI](https://github.com/vercel-labs/skills) supports both
  67. Codex and Claude Code:
  68. ```bash
  69. # Codex
  70. npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -y
  71. # Claude Code
  72. npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a claude-code -y
  73. # Both agents
  74. npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -a claude-code -y
  75. ```
  76. `-g` installs at user scope. Remove it for a project-local installation. Check
  77. the result with `npx skills@latest list -g --json`, then start a fresh agent
  78. task so the Skill is rediscovered. Review Skills before using them: they run
  79. with the permissions of the host agent.
  80. ## Quick start
  81. ```bash
  82. node scripts/validate.mjs assets/example-spec.json
  83. node scripts/render.mjs assets/example-spec.json example.html
  84. node scripts/validate.mjs assets/example-spec.json example.html
  85. ```
  86. The commands print compact JSON and exit nonzero on failure. Rendering is
  87. create-only by default. Use `--force` only to intentionally replace a known
  88. regular file; symbolic links are always rejected.
  89. Run the complete contributor and distribution gate:
  90. ```bash
  91. npm run check
  92. ```
  93. This checks JavaScript syntax, focused tests, the canonical example, release
  94. package contents, and a render/validate canary from an unpacked archive.
  95. On Node.js 22.20 or newer, also exercise an isolated Codex and Claude Code
  96. installation through the pinned Agent Skills CLI release:
  97. ```bash
  98. npm run check:agent-install
  99. ```
  100. ## Use as an Agent Skill
  101. After installation, ask for an evidence-aware visual explanation, for example:
  102. > Explain how one queued job moves through this repository. Cite real files,
  103. > let me play the request path, and show what breaks when the lease expires.
  104. Read [SKILL.md](SKILL.md) for the agent workflow and
  105. [references/spec-contract.md](references/spec-contract.md) for the version 1
  106. story spec.
  107. ## Story pipeline
  108. ```text
  109. question + audience + evidence
  110. │
  111. ▼
  112. versioned JSON story spec
  113. │ validate
  114. ▼
  115. deterministic HTML renderer
  116. │
  117. ├── offline interactive explainer
  118. ├── print / PDF
  119. ├── current-scene PNG
  120. ├── all-scene PPTX
  121. ├── Pages-compatible DOCX
  122. └── optional native Pages conversion
  123. ```
  124. The JSON spec is the portable source of truth. The HTML contains its canonical
  125. SHA-256, and the validator can byte-compare a supplied spec against a fresh
  126. deterministic render.
  127. ## Reader workspace
  128. Every explainer has a directory drawer. Favorites appear first, followed by
  129. independent tabs for the current outline, previously opened explainers, and
  130. annotation browsing. A reader can play, favorite, annotate, or export one scene
  131. without starting the global trace.
  132. The local library is disabled until the reader selects **Enable local
  133. library**. It records only explainers actually opened at the same scheme, host,
  134. and port; it never scans the filesystem. Favorites and annotations are
  135. browser-local, unencrypted, and removed when that origin's browser data is
  136. cleared. They never modify the source JSON or generated HTML. `file://` and
  137. unavailable storage degrade to an in-memory session.
  138. See [references/library-and-export.md](references/library-and-export.md) for
  139. the persistence, privacy, accessibility, playback, and export contract.
  140. ## Export
  141. | Action | Result | Verification boundary |
  142. |---|---|---|
  143. | Print / PDF | Browser print dialog | The reader chooses Save as PDF when available |
  144. | PNG | 1600×900 image of the selected scene | PNG signature, dimensions, and scene evidence footer |
  145. | PPTX | One 16:9 slide per scene | ZIP signature and required OOXML parts |
  146. | DOCX | One 16:9 page per scene | ZIP signature and required OOXML parts |
  147. | Native Pages | A real `.pages` package saved by Apple Pages | Must contain `Index/Document.iwa` and reopen in Pages |
  148. PNG, PPTX, and DOCX are built locally in the browser without third-party
  149. libraries. Native Pages conversion is never faked by renaming a DOCX. Serve a
  150. trusted explainer directory with:
  151. ```bash
  152. node scripts/serve.mjs --root /absolute/path/to/explainers --port 8772
  153. ```
  154. The helper binds only to `127.0.0.1`, verifies exact origin and a rotating
  155. process token, bounds and validates the generated DOCX/PNG structure, serializes
  156. conversion, and cleans task-specific temporary files. These controls protect
  157. the browser action from cross-site requests; they are not authentication
  158. against other local processes.
  159. ## Security and privacy
  160. The renderer reads local files and writes one local file. Generated HTML uses a
  161. hash-whitelisted Content Security Policy, embeds no remote resources, and
  162. contains no XHR, WebSocket, `eval`, or HTML-string DOM insertion. Its only
  163. connection is a user-initiated same-origin request to the optional loopback
  164. Pages helper. Cited HTTP(S) URLs are ordinary reader-facing links, never runtime
  165. dependencies.
  166. Annotations are capped and inserted as text. The validator rejects unsafe
  167. source URLs, external resources, runtime tampering, spec-hash drift, and
  168. unexpected CSP hashes. See [SECURITY.md](SECURITY.md) to report a vulnerability.
  169. ## Project map
  170. - [SKILL.md](SKILL.md) — agent workflow and delivery boundary
  171. - `assets/example-spec.json` — complete Chinese DNS example
  172. - `assets/explainer-shell.html` — offline visual and interaction shell
  173. - `scripts/render.mjs` — deterministic renderer
  174. - `scripts/validate.mjs` — spec and output validator
  175. - `scripts/serve.mjs` — loopback-only native Pages helper
  176. - `references/` — evidence, grammar, visual, reporting, workspace, and export
  177. contracts
  178. - `evals/` — task-quality and trigger evaluation prompts
  179. - `tests/` — Node built-in tests and adversarial fixtures
  180. ## Contributing
  181. Read [CONTRIBUTING.md](CONTRIBUTING.md), then run:
  182. ```bash
  183. npm run check
  184. ```
  185. The release package uses an explicit allowlist and keeps `private: true` to
  186. prevent accidental npm publication. This repository is intended to distribute
  187. an Agent Skill, not an npm runtime library.
  188. ## License and attribution
  189. Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
  190. Fireworks Open ELI5 is an independent implementation inspired by the Anthropic
  191. community `eli5` skill and is not endorsed by Anthropic.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.