waapi — Claude Code skill: what it does, how to install
waapi instructs agents to write deterministic Web Animations API code for HyperFrames without relying on heavy external animation engines.
Apache-2.0 211 installs ★ 484 updated 2026-08-15
npx skills add boraoztunc/skills --skill waapi -a claude-codeWhat waapi does
This skill guides coding assistants through the contract of the HyperFrames waapi runtime adapter. It applies when writing element.animate() calls, seeking via currentTime, and reading animations with document.getAnimations().
The adapter requires synchronous animation setup during composition initialization. Every animation must define a finite duration, set fill: "both" to retain seeked positions, and be paused right after creation.
Without fill: "both", seeked frames drop their visual state. The adapter relies on document time in milliseconds, so asynchronous hooks like animation.finished or internal timers break frame determinism. Code checks run via npx hyperframes lint and npx hyperframes validate.
What it helps with
- build native browser animations via
element.animate()for HyperFrames - generate staggered element transitions with keyframes and offsets
- prevent frame desynchronization during timeline seeking
- validate animation scripts against the HyperFrames adapter rules
Example prompts for the agent
- Create a staggered entrance animation for token elements using the waapi adapter rules
- Animate an orb element using element.animate and prepare it for HyperFrames seeking
- Review this WAAPI script to confirm it complies with HyperFrames validation checks
How to install waapi
1Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill waapi -a claude-code2Manually: put the files in place
~/.claude/skills/waapi/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/waapi/
1Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill waapi -a codex2Manually: put the files in place
.agents/skills/waapi/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill waapi -a cursor2Manually: put the files in place
.cursor/skills/waapi/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install boraoztunc/skills waapi2Manually: put the files in place
.github/skills/waapi/SKILL.md1Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill waapi -a gemini-cli2Platform CLI
gemini skills install https://github.com/boraoztunc/skills --path waapiManually: put the files in place
.devin/skills/waapi/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add boraoztunc/skills --skill waapi -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about waapi
How to install waapi in Claude Code?
Run npx skills add boraoztunc/skills --skill waapi -a claude-code. Alternatively, place the file directly at ~/.claude/skills/waapi/SKILL.md.
What does the waapi skill do?
It provides instructions and patterns for authoring Web Animations API motions that can be deterministically seeked by HyperFrames.
Why must animations use fill: "both"?
HyperFrames seeks document-level time directly. Without fill: "both", elements drop their transformed state before and after playback boundaries.
Source text
SKILL.md · Apache-2.0
---
name: waapi
description: Web Animations API adapter patterns for HyperFrames. Use when authoring element.animate() motion, Animation currentTime seeking, document.getAnimations(), KeyframeEffect timing, fill modes, or native browser animations that must render deterministically in HyperFrames.
---
# Web Animations API for HyperFrames
HyperFrames can seek Web Animations API animations through its `waapi` runtime adapter. WAAPI is useful when you want native browser keyframes with JavaScript-created timing and no GSAP dependency.
## Contract
- Create animations synchronously during composition initialization.
- Use `element.animate(...)` with finite `duration` and `iterations`.
- Use `fill: "both"` so seeked states persist.
- Pause animations after creation or let the adapter pause them on first seek.
- Avoid callbacks and promises for render-critical state.
The adapter calls `document.getAnimations()`, sets each animation's `currentTime` to HyperFrames time in milliseconds, then pauses it.
## Basic Pattern
```html
<div id="orb" class="clip orb" data-start="2" data-duration="3" data-track-index="2"></div>
<script>
const orb = document.getElementById("orb");
const animation = orb.animate(
[
{ transform: "translate3d(-160px, 0, 0) scale(0.8)", opacity: 0 },
{ transform: "translate3d(0, 0, 0) scale(1)", opacity: 1, offset: 0.35 },
{ transform: "translate3d(120px, 0, 0) scale(1.08)", opacity: 1 },
],
{
duration: 3000,
delay: 2000,
easing: "cubic-bezier(0.2, 0, 0, 1)",
fill: "both",
iterations: 1,
},
);
animation.pause();
</script>
```
## Stagger Pattern
```js
document.querySelectorAll(".token").forEach((token, index) => {
const animation = token.animate(
[
{ transform: "translateY(24px)", opacity: 0 },
{ transform: "translateY(0)", opacity: 1 },
],
{
duration: 620,
delay: index * 80,
easing: "cubic-bezier(0.2, 0, 0, 1)",
fill: "both",
iterations: 1,
},
);
animation.pause();
});
```
## Good Uses
- Lightweight DOM motion where CSS keyframes are too rigid and GSAP is unnecessary.
- Generated animations from structured data.
- Simple timelines that can be represented as keyframes, delays, and offsets.
## Avoid
- Infinite `iterations`.
- Depending on `animation.finished` to mutate render-critical DOM.
- Running separate clocks with `requestAnimationFrame`, timers, or `performance.now()`.
- Animating layout properties when transforms and opacity can express the motion.
- Assuming clip-local start time is automatic. WAAPI adapter seeks document-level animation time; model clip offsets with `delay` or create the animation on an element whose visibility is controlled by HyperFrames timing.
## Validation
After editing a WAAPI composition:
```bash
npx hyperframes lint
npx hyperframes validate
```
## Credits And References
- HyperFrames adapter source: `packages/core/src/runtime/adapters/waapi.ts`.
- MDN Web Animations API guide: https://developer.mozilla.org/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API
- MDN `Animation.currentTime`: https://developer.mozilla.org/en-US/docs/Web/API/Animation/currentTime
© boraoztunc · Apache-2.0 · boraoztunc/skills