opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/frontend-ui-engineering/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: frontend-ui-engineering
+description: Builds production-quality UIs. Use when building or modifying user-facing interfaces. Use when creating components, implementing layouts, managing state, or when the output needs to look and feel production-quality rather than AI-generated.
+risk: unknown
+source: https://github.com/addyosmani/agent-skills/tree/main/skills/frontend-ui-engineering
+source_repo: addyosmani/agent-skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/addyosmani/agent-skills/blob/main/LICENSE
+---
+
+# Frontend UI Engineering
+
+## Overview
+
+Build production-quality user interfaces that are accessible, performant, and visually polished. The goal is UI that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI. This means real design system adherence, proper accessibility, thoughtful interaction patterns, and no generic "AI aesthetic."
+
+## When to Use
+
+- Building new UI components or pages
+- Modifying existing user-facing interfaces
+- Implementing responsive layouts
+- Adding interactivity or state management
+- Fixing visual or UX issues
+
+## Component Architecture
+
+### File Structure
+
+Colocate everything related to a component:
+
+```
+src/components/
+  TaskList/
+    TaskList.tsx          # Component implementation
+    TaskList.test.tsx     # Tests
+    TaskList.stories.tsx  # Storybook stories (if using)
+    use-task-list.ts      # Custom hook (if complex state)
+    types.ts              # Component-specific types (if needed)
+```
+
+### Component Patterns
+
+**Prefer composition over configuration:**
+
+```tsx
+// Good: Composable
+<Card>
+  <CardHeader>
+    <CardTitle>Tasks</CardTitle>
+  </CardHeader>
+  <CardBody>
+    <TaskList tasks={tasks} />
+  </CardBody>
+</Card>
+
+// Avoid: Over-configured
+<Card
+  title="Tasks"
+  headerVariant="large"
+  bodyPadding="md"
+  content={<TaskList tasks={tasks} />}
+/>
+```
+
+**Keep components focused:**
+
+```tsx
+// Good: Does one thing
+export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
+  return (
+    <li className="flex items-center gap-3 p-3">
+      <Checkbox checked={task.done} onChange={() => onToggle(task.id)} />
+      <span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span>
+      <Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}>
+        <TrashIcon />
+      </Button>
+    </li>
+  );
+}
+```
+
+**Separate data fetching from presentation:**
+
+```tsx
+// Container: handles data
+export function TaskListContainer() {
+  const { tasks, isLoading, error } = useTasks();
+
+  if (isLoading) return <TaskListSkeleton />;
+  if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;
+  if (tasks.length === 0) return <EmptyState message="No tasks yet" />;
+
+  return <TaskList tasks={tasks} />;
+}
+
+// Presentation: handles rendering
+export function TaskList({ tasks }: { tasks: Task[] }) {
+  return (
+    <ul role="list" className="divide-y">
+      {tasks.map(task => <TaskItem key={task.id} task={task} />)}
+    </ul>
+  );
+}
+```
+
+## State Management
+
+**Choose the simplest approach that works:**
+
+```
+Local state (useState)           → Component-specific UI state
+Lifted state                     → Shared between 2-3 sibling components
+Context                          → Theme, auth, locale (read-heavy, write-rare)
+URL state (searchParams)         → Filters, pagination, shareable UI state
+Server state (React Query, SWR)  → Remote data with caching
+Global store (Zustand, Redux)    → Complex client state shared app-wide
+```
+
+**Avoid prop drilling deeper than 3 levels.** If you're passing props through components that don't use them, introduce context or restructure the component tree.
+
+## Design System Adherence
+
+### Avoid the AI Aesthetic
+
+AI-generated UI has recognizable patterns. Avoid all of them:
+
+| AI Default | Why It Is a Problem | Production Quality |
+|---|---|---|
+| Purple/indigo everything | Models default to visually "safe" palettes, making every app look identical | Use the project's actual color palette |
+| Excessive gradients | Gradients add visual noise and clash with most design systems | Flat or subtle gradients matching the design system |
+| Rounded everything (rounded-2xl) | Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designs | Consistent border-radius from the design system |
+| Generic hero sections | Template-driven layout with no connection to the actual content or user need | Content-first layouts |
+| Lorem ipsum-style copy | Placeholder text hides layout problems that real content reveals (length, wrapping, overflow) | Realistic placeholder content |
+| Oversized padding everywhere | Equal generous padding destroys visual hierarchy and wastes screen space | Consistent spacing scale |
+| Stock card grids | Uniform grids are a layout shortcut that ignores information priority and scanning patterns | Purpose-driven layouts |
+| Shadow-heavy design | Layered shadows add depth that competes with content and slows rendering on low-end devices | Subtle or no shadows unless the design system specifies |
+
+### Spacing and Layout
+
+Use a consistent spacing scale. Don't invent values:
+
+```css
+/* Use the scale: 0.25rem increments (or whatever the project uses) */
+/* Good */  padding: 1rem;      /* 16px */
+/* Good */  gap: 0.75rem;       /* 12px */
+/* Bad */   padding: 13px;      /* Not on any scale */
+/* Bad */   margin-top: 2.3rem; /* Not on any scale */
+```
+
+### Typography
+
+Respect the type hierarchy:
+
+```
+h1 → Page title (one per page)
+h2 → Section title
+h3 → Subsection title
+body → Default text
+small → Secondary/helper text
+```
+
+Don't skip heading levels. Don't use heading styles for non-heading content.
+
+### Color
+
+- Use semantic color tokens: `text-primary`, `bg-surface`, `border-default` — not raw hex values
+- Ensure sufficient contrast (4.5:1 for normal text, 3:1 for large text)
+- Don't rely solely on color to convey information (use icons, text, or patterns too)
+
+## Accessibility (WCAG 2.1 AA)
+
+Every component must meet these standards:
+
+### Keyboard Navigation
+
+```tsx
+// Every interactive element must be keyboard accessible
+<button onClick={handleClick}>Click me</button>        // ✓ Focusable by default
+<div onClick={handleClick}>Click me</div>               // ✗ Not focusable
+<div role="button" tabIndex={0} onClick={handleClick}    // ✓ But prefer <button>
+     onKeyDown={e => {
+       if (e.key === 'Enter') handleClick();
+       if (e.key === ' ') e.preventDefault();
+     }}
+     onKeyUp={e => {
+       if (e.key === ' ') handleClick();
+     }}>
+  Click me
+</div>
+```
+
+### ARIA Labels
+
+```tsx
+// Label interactive elements that lack visible text
+<button aria-label="Close dialog"><XIcon /></button>
+
+// Label form inputs
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+// Or use aria-label when no visible label exists
+<input aria-label="Search tasks" type="search" />
+```
+
+### Focus Management
+
+```tsx
+// Move focus when content changes
+function Dialog({ isOpen, onClose }: DialogProps) {
+  const closeRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (isOpen) closeRef.current?.focus();
+  }, [isOpen]);
+
+  // Trap focus inside dialog when open
+  return (
+    <dialog open={isOpen}>
+      <button ref={closeRef} onClick={onClose}>Close</button>
+      {/* dialog content */}
+    </dialog>
+  );
+}
+```
+
+### Meaningful Empty and Error States
+
+```tsx
+// Don't show blank screens
+function TaskList({ tasks }: { tasks: Task[] }) {
+  if (tasks.length === 0) {
+    return (
+      <div role="status" className="text-center py-12">
+        <TasksEmptyIcon className="mx-auto h-12 w-12 text-muted" />
+        <h3 className="mt-2 text-sm font-medium">No tasks</h3>
+        <p className="mt-1 text-sm text-muted">Get started by creating a new task.</p>
+        <Button className="mt-4" onClick={onCreateTask}>Create Task</Button>
+      </div>
+    );
+  }
+
+  return <ul role="list">...</ul>;
+}
+```
+
+## Responsive Design
+
+Design for mobile first, then expand:
+
+```tsx
+// Tailwind: mobile-first responsive
+<div className="
+  grid grid-cols-1      /* Mobile: single column */
+  sm:grid-cols-2        /* Small: 2 columns */
+  lg:grid-cols-3        /* Large: 3 columns */
+  gap-4
+">
+```
+
+Test at these breakpoints: 320px, 768px, 1024px, 1440px.
+
+## Loading and Transitions
+
+```tsx
+// Skeleton loading (not spinners for content)
+function TaskListSkeleton() {
+  return (
+    <div className="space-y-3" aria-busy="true" aria-label="Loading tasks">
+      {Array.from({ length: 3 }).map((_, i) => (
+        <div key={i} className="h-12 bg-muted animate-pulse rounded" />
+      ))}
+    </div>
+  );
+}
+
+// Optimistic updates for perceived speed
+function useToggleTask() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: toggleTask,
+    onMutate: async (taskId) => {
+      await queryClient.cancelQueries({ queryKey: ['tasks'] });
+      const previous = queryClient.getQueryData(['tasks']);
+
+      queryClient.setQueryData(['tasks'], (old: Task[]) =>
+        old.map(t => t.id === taskId ? { ...t, done: !t.done } : t)
+      );
+
+      return { previous };
+    },
+    onError: (_err, _taskId, context) => {
+      queryClient.setQueryData(['tasks'], context?.previous);
+    },
+  });
+}
+```
+
+## See Also
+
+For detailed accessibility requirements and testing tools, see `references/accessibility-checklist.md`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
+| "We'll make it responsive later" | Retrofitting responsive design is 3x harder than building it from the start. |
+| "The design isn't final, so I'll skip styling" | Use the design system defaults. Unstyled UI creates a broken first impression for reviewers. |
+| "This is just a prototype" | Prototypes become production code. Build the foundation right. |
+| "The AI aesthetic is fine for now" | It signals low quality. Use the project's actual design system from the start. |
+
+## Red Flags
+
+- Components with more than 200 lines (split them)
+- Inline styles or arbitrary pixel values
+- Missing error states, loading states, or empty states
+- No keyboard navigation testing
+- Color as the sole indicator of state (red/green without text or icons)
+- Generic "AI look" (purple gradients, oversized cards, stock layouts)
+
+## Verification
+
+After building UI:
+
+- [ ] Component renders without console errors
+- [ ] All interactive elements are keyboard accessible (Tab through the page)
+- [ ] Screen reader can convey the page's content and structure
+- [ ] Responsive: works at 320px, 768px, 1024px, 1440px
+- [ ] Loading, error, and empty states all handled
+- [ ] Follows the project's design system (spacing, colors, typography)
+- [ ] No accessibility warnings in dev tools or axe-core
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/gemini-api-dev/SKILL.md

@@ -1,42 +1,53 @@
 ---
 name: gemini-api-dev
-description: "The Gemini API provides access to Google's most advanced AI models. Key capabilities include:"
+description: Use this skill when building applications with Gemini API hosted models, including Gemini and Gemma 4, working with multimodal content (text, images, audio, video), implementing function calling, using structured outputs, or needing current model specifications. Covers SDK usage...
 risk: unknown
-source: community
-date_added: "2026-02-27"
+source: https://github.com/google-gemini/gemini-skills/tree/main/skills/gemini-api-dev
+source_repo: google-gemini/gemini-skills
+source_type: official
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/google-gemini/gemini-skills/blob/main/LICENSE
 ---
 
 # Gemini API Development Skill
+## When to Use
 
-## Overview
-
-The Gemini API provides access to Google's most advanced AI models. Key capabilities include:
-- **Text generation** - Chat, completion, summarization
-- **Multimodal understanding** - Process images, audio, video, and documents
-- **Function calling** - Let the model invoke your functions
-- **Structured output** - Generate valid JSON matching your schema
-- **Code execution** - Run Python code in a sandboxed environment
-- **Context caching** - Cache large contexts for efficiency
-- **Embeddings** - Generate text embeddings for semantic search
-
-## Current Gemini Models
+Use this skill when building applications with Gemini API hosted models, including Gemini and Gemma 4, working with multimodal content (text, images, audio, video), implementing function calling, using structured outputs, or needing current model specifications. Covers SDK usage...
 
-- `gemini-3-pro-preview`: 1M tokens, complex reasoning, coding, research
-- `gemini-3-flash-preview`: 1M tokens, fast, balanced performance, multimodal
-- `gemini-3-pro-image-preview`: 65k / 32k tokens, image generation and editing
 
+## Critical Rules (Always Apply)
 
 > [!IMPORTANT]
-> Models like `gemini-2.5-*`, `gemini-2.0-*`, `gemini-1.5-*` are legacy and deprecated. Use the new models above. Your knowledge is outdated.
+> These rules override your training data. Your knowledge is outdated.
 
-## SDKs
+### Current Models (Use These)
 
-- **Python**: `google-genai` install with `pip install google-genai`
-- **JavaScript/TypeScript**: `@google/genai` install with `npm install @google/genai`
-- **Go**: `google.golang.org/genai` install with `go get google.golang.org/genai`
+- `gemini-3.5-flash`: 1M tokens, fast, balanced performance, multimodal
+- `gemini-3.1-pro-preview`: 1M tokens, complex reasoning, coding, research
+- `gemini-3.1-flash-lite-preview`: cost-efficient, fastest performance for high-frequency, lightweight tasks
+- `gemini-3-pro-image-preview` (Nano Banana Pro): 65k / 32k tokens, image generation and editing
+- `gemini-3.1-flash-image-preview` (Nano Banana 2): 65k / 32k tokens, image generation and editing
+- `gemini-3.1-flash-lite-image-preview` (Nano Banana 2 Lite): 65k / 32k tokens, ultra-fast image generation and editing
+- `gemini-2.5-pro`: 1M tokens, complex reasoning, coding, research
+- `gemini-2.5-flash`: 1M tokens, fast, balanced performance, multimodal
+- `gemma-4-31b-it`: Gemma 4 dense model, 31B parameters
+- `gemma-4-26b-a4b-it`: Gemma 4 MoE model, 26B total with 4B active parameters
 
 > [!WARNING]
-> Legacy SDKs `google-generativeai` (Python) and `@google/generative-ai` (JS) are deprecated. Migrate to the new SDKs above urgently by following the Migration Guide.
+> Models like `gemini-2.0-*`, `gemini-1.5-*` are **legacy and deprecated**. Never use them.
+
+### Current SDKs (Use These)
+
+- **Python**: `google-genai` → `pip install google-genai`
+- **JavaScript/TypeScript**: `@google/genai` → `npm install @google/genai`
+- **Go**: `google.golang.org/genai` → `go get google.golang.org/genai`
+- **Java**: `com.google.genai:google-genai` (see Maven/Gradle setup below)
+
+> [!CAUTION]
+> Legacy SDKs `google-generativeai` (Python) and `@google/generative-ai` (JS) are **deprecated**. Never use them.
+
+---
 
 ## Quick Start
 
@@ -46,7 +57,7 @@ from google import genai
 
 client = genai.Client()
 response = client.models.generate_content(
-    model="gemini-3-flash-preview",
+    model="gemini-3.5-flash",
     contents="Explain quantum computing"
 )
 print(response.text)
@@ -58,7 +69,7 @@ import { GoogleGenAI } from "@google/genai";
 
 const ai = new GoogleGenAI({});
 const response = await ai.models.generateContent({
-  model: "gemini-3-flash-preview",
+  model: "gemini-3.5-flash",
   contents: "Explain quantum computing"
 });
 console.log(response.text);
@@ -82,7 +93,7 @@ func main() {
 		log.Fatal(err)
 	}
 
-	resp, err := client.Models.GenerateContent(ctx, "gemini-3-flash-preview", genai.Text("Explain quantum computing"), nil)
+	resp, err := client.Models.GenerateContent(ctx, "gemini-3.5-flash", genai.Text("Explain quantum computing"), nil)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -91,48 +102,80 @@ func main() {
 }
 ```
 
-## API spec (source of truth)
+### Java
 
-**Always use the latest REST API discovery spec as the source of truth for API definitions** (request/response schemas, parameters, methods). Fetch the spec when implementing or debugging API integration:
+```java
+import com.google.genai.Client;
+import com.google.genai.types.GenerateContentResponse;
 
-- **v1beta** (default): `https://generativelanguage.googleapis.com/$discovery/rest?version=v1beta`  
-  Use this unless the integration is explicitly pinned to v1. The official SDKs (google-genai, @google/genai, google.golang.org/genai) target v1beta.
-- **v1**: `https://generativelanguage.googleapis.com/$discovery/rest?version=v1`  
-  Use only when the integration is specifically set to v1.
+public class GenerateTextFromTextInput {
+  public static void main(String[] args) {
+    Client client = new Client();
+    GenerateContentResponse response =
+        client.models.generateContent(
+            "gemini-3.5-flash",
+            "Explain quantum computing",
+            null);
 
-When in doubt, use v1beta. Refer to the spec for exact field names, types, and supported operations.
+    System.out.println(response.text());
+  }
+}
+```
 
-## How to use the Gemini API
+**Java Installation:**
+- Latest version: https://central.sonatype.com/artifact/com.google.genai/google-genai/versions
+- Gradle: `implementation("com.google.genai:google-genai:${LAST_VERSION}")`
+- Maven:
+  ```xml
+  <dependency>
+      <groupId>com.google.genai</groupId>
+      <artifactId>google-genai</artifactId>
+      <version>${LAST_VERSION}</version>
+  </dependency>
+  ```
 
-For detailed API documentation, fetch from the official docs index:
+---
 
-**llms.txt URL**: `https://ai.google.dev/gemini-api/docs/llms.txt`
+## Documentation Lookup
 
-This index contains links to all documentation pages in `.md.txt` format. Use web fetch tools to:
+### When MCP is Installed (Preferred)
 
-1. Fetch `llms.txt` to discover available documentation pages
-2. Fetch specific pages (e.g., `https://ai.google.dev/gemini-api/docs/function-calling.md.txt`)
+If the **`search_docs`** tool (from the Google MCP server) is available, use it as your **only** documentation source:
 
-### Key Documentation Pages 
+1. Call `search_docs` with your query
+2. Read the returned documentation
+2. **Trust MCP results** as source of truth for API details — they are always up-to-date.
 
 > [!IMPORTANT]
-> Those are not all the documentation pages. Use the `llms.txt` index to discover available documentation pages
+> When MCP tools are present, **never** fetch URLs manually. MCP provides up-to-date, indexed documentation that is more accurate and token-efficient than URL fetching.
 
-- [Models](https://ai.google.dev/gemini-api/docs/models.md.txt)
-- [Google AI Studio quickstart](https://ai.google.dev/gemini-api/docs/ai-studio-quickstart.md.txt)
-- [Nano Banana image generation](https://ai.google.dev/gemini-api/docs/image-generation.md.txt)
-- [Function calling with the Gemini API](https://ai.google.dev/gemini-api/docs/function-calling.md.txt)
-- [Structured outputs](https://ai.google.dev/gemini-api/docs/structured-output.md.txt)
+### When MCP is NOT Installed (Fallback Only)
+
+If no MCP documentation tools are available, fetch from the official docs:
+
+**Index URL**: `https://ai.google.dev/gemini-api/docs/llms.txt`
+
+This index contains links to all documentation pages in .md.txt format. Use web fetch tools to:
+1. Fetch `llms.txt` to discover available pages
+2. Fetch specific pages (e.g., `https://ai.google.dev/gemini-api/docs/function-calling.md.txt`)
+
+Key pages:
 - [Text generation](https://ai.google.dev/gemini-api/docs/text-generation.md.txt)
+- [Function calling](https://ai.google.dev/gemini-api/docs/function-calling.md.txt)
+- [Structured outputs](https://ai.google.dev/gemini-api/docs/structured-output.md.txt)
+- [Image generation](https://ai.google.dev/gemini-api/docs/image-generation.md.txt)
 - [Image understanding](https://ai.google.dev/gemini-api/docs/image-understanding.md.txt)
 - [Embeddings](https://ai.google.dev/gemini-api/docs/embeddings.md.txt)
-- [Interactions API](https://ai.google.dev/gemini-api/docs/interactions.md.txt)
 - [SDK migration guide](https://ai.google.dev/gemini-api/docs/migrate.md.txt)
 
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.
+---
+
+## Gemini Live API
+
+For real-time, bidirectional audio/video/text streaming with the Gemini Live API, install the **`google-gemini/gemini-live-api-dev`** skill. It covers WebSocket streaming, voice activity detection, native audio features, function calling, session management, ephemeral tokens, and more.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.