add visual-explainer skill#1386
Conversation
Captures the presentation rules for diagram-first, skimmable explainer pages (standalone HTML or a SvelteKit/playbook entry): lead with a question, every section carries a graphic with a one-line setup, prefer diagrams over pasted source, render real data byte-exact, motion only when meaningful, colored brand icons. Passes skill-lint (0/0). (authored by Claude, Opus via Claude Code)
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
AI review found issues in this pull request.
Verdict: patch is incorrect
Confidence: 0.84
The added skill is mostly self-contained, but it introduces instructions that can trigger unwanted PR creation, references an unavailable companion skill, and gives a Svelte import path that is not valid for this repo's site unless additional tooling exists.
- P2
skills/visual-explainer/SKILL.md:99Do not make PR creation part of this explainer skill - P3
skills/visual-explainer/SKILL.md:13Reference points to a skill that is not published here - P3
skills/visual-explainer/SKILL.md:56Iconify import path is not safe for generic SvelteKit targets
…conditional Don't mandate PR/worktree for one-off local outputs (delegate to the workflow skill); gate Iconify on the host already using it; phrase the page-skill reference as optional target-repo guidance. (authored by Claude, Opus via Claude Code)
There was a problem hiding this comment.
AI review found issues in this pull request.
Verdict: patch is incorrect
Confidence: 0.80
The skill is valid Markdown/YAML, but its trigger is broad enough to alter normal explanation workflows, and its interaction guidance would produce inaccessible hover-only pages.
- P2
skills/visual-explainer/SKILL.md:3Overbroad trigger will hijack plain explanation requests - P3
skills/visual-explainer/SKILL.md:51Hover-only interactions exclude touch and keyboard users
| @@ -0,0 +1,103 @@ | |||
| --- | |||
| name: visual-explainer | |||
| description: "Build a visual, skimmable explainer for a piece of code, a feature, or a system: a standalone HTML page or a SvelteKit/playbook entry. Lead with a question, keep prose tight, and make every section carry a graphic (a diagram, an interactive scene, an annotated visual) instead of walls of text or pasted source. Use when the user wants to explain, document, teach, or show off how something works as a page or interactive demo, asks for a diagram-first or ADHD-friendly writeup, or wants to turn a module / PR / feature into a visual explainer. Prefers diagrams over inline code, sets up every visual with one line of context, renders any real data (polars frames, tables) byte-exact, and adds motion only when it carries meaning." | |||
There was a problem hiding this comment.
The frontmatter trigger includes ordinary "explain, document, teach" requests even though the skill body says the output is always a standalone HTML page or SvelteKit/playbook entry. Since this description drives progressive skill invocation, routine requests like "explain this function" can load this skill and push the agent toward creating a page instead of answering in chat. Narrow the trigger to visual/page/demo requests.
| description: "Build a visual, skimmable explainer for a piece of code, a feature, or a system: a standalone HTML page or a SvelteKit/playbook entry. Lead with a question, keep prose tight, and make every section carry a graphic (a diagram, an interactive scene, an annotated visual) instead of walls of text or pasted source. Use when the user wants to explain, document, teach, or show off how something works as a page or interactive demo, asks for a diagram-first or ADHD-friendly writeup, or wants to turn a module / PR / feature into a visual explainer. Prefers diagrams over inline code, sets up every visual with one line of context, renders any real data (polars frames, tables) byte-exact, and adds motion only when it carries meaning." | |
| description: "Build a visual, skimmable explainer as a standalone HTML page or SvelteKit/playbook entry. Use only when the user asks for a visual explainer, diagram-first writeup, ADHD-friendly page, interactive demo, or to turn a module / PR / feature into a page. Prefer diagrams over inline code, set up every visual with one line of context, render real data byte-exact, and add motion only when it carries meaning." |
| 8. **Motion only when it means something.** No autoplaying or looping animation. | ||
| Interactivity is welcome when it teaches: hover a token to light the thing it | ||
| refers to, hover a control to preview its effect (a close that shrinks the | ||
| window). Trigger on hover, keep it still otherwise. |
There was a problem hiding this comment.
This rule makes hover the required trigger for meaningful interactivity. The generated artifacts are standalone HTML or SvelteKit pages, so hover-only visuals do not work on touch devices and are not keyboard accessible. Require focus/tap/click equivalents so the visual remains usable across the target surfaces.
| 8. **Motion only when it means something.** No autoplaying or looping animation. | |
| Interactivity is welcome when it teaches: hover a token to light the thing it | |
| refers to, hover a control to preview its effect (a close that shrinks the | |
| window). Trigger on hover, keep it still otherwise. | |
| 8. **Motion only when it means something.** No autoplaying or looping animation. | |
| Interactivity is welcome when it teaches: hover, focus, or tap a token to light | |
| the thing it refers to, or activate a control to preview its effect (a close | |
| that shrinks the window). Support keyboard focus and touch/click equivalents; | |
| keep it still otherwise. |
1 participant
Adds a global
visual-explainerskill: the presentation rules for diagram-first, skimmable explainer pages (standalone HTML or a SvelteKit/playbook entry).Auto-discovered via
lib/skills.nix(lands incommonSkills);skill-lintclean (0 errors, 0 warnings).Distinct from ix's
playbook-page(top-down + heavy citation); the two compose.(authored by Claude, Opus via Claude Code)
Note
Add visual-explainer skill specification
Adds SKILL.md, a new skill definition for building visual, skimmable explainers. The spec covers medium selection (standalone HTML or SvelteKit), theming, diagram construction, and a verification checklist, with non-negotiable rules such as mandatory graphics per section, preferring diagrams over code, and meaningful motion.
Macroscope summarized df6f130.