dotfiles/pi/files/agent/skills/ripple/SKILL.md

name, description

name	description
ripple	Work with Ripple TS framework projects. Use when working with .ripple files or projects using the ripple or @ripple-ts/* packages.

Ripple TS Framework Skill

Use this skill when working on Ripple TS projects. Ripple is a TypeScript UI framework combining the best parts of React, Solid, and Svelte.

Activation

This skill activates when:

• Working with .ripple files
• User mentions "Ripple" in the context of a UI framework
• Project uses ripple or @ripple-ts/* packages

Documentation Reference

Always fetch the latest documentation before providing Ripple-specific guidance:

https://www.ripple-ts.com/llms.txt

Use the fetch_content tool to retrieve this URL. The documentation is optimized for AI/LLM understanding and may be updated with new features and syntax changes.

Quick Reference

Key Syntax Patterns

• Components: Use component keyword (not functions returning JSX)
• Text content: Must be wrapped in expressions {"text"} - no raw text in templates
• Reactivity: Use track() to create reactive values, @ to read/write them
• Templates: Only valid inside component function bodies
• Early returns: Use return; (no value) for guard clauses only

Common Imports

import { mount, track, effect, Context, untrack, flushSync, tick } from 'ripple';
import { TrackedArray, TrackedObject, TrackedSet, TrackedMap, TrackedDate } from 'ripple';
import type { Component, PropsWithChildren, Tracked } from 'ripple';

Critical Mistakes to Avoid

1. Raw text in templates - Always use {"text"} not text
2. Return statements with values - Use return; only, no return <JSX/>
3. Templates outside components - JSX only valid inside component {} bodies
4. Destructuring props without trackSplit - Loses reactivity for non-tracked props

When to Fetch Full Docs

Fetch the full documentation when:

• Implementing complex reactive patterns
• Using Context API
• Setting up SSR/hydration
• Integrating with React (compat layer)
• Working with reactive collections (TrackedArray, TrackedMap, etc.)
• Using control flow (switch statements, for loops with keys)
• Implementing portals or refs