@hybridlabor-api/bdb-antigravity-skills 1.0.0

package/skills/global_config/ux-audit/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ux-audit
+description: "Audit screens against Nielsen's heuristics and mobile UX best practices using the StyleSeed Toss design language as the implementation context."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ux, audit, usability, mobile, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UX Audit
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill audits usability rather than just visuals. It uses Nielsen's 10 heuristics plus modern mobile UX expectations to find issues in navigation, feedback, recovery, hierarchy, and cognitive load.
+
+## When to Use
+- Use when a screen feels awkward even though the code and styling seem correct
+- Use when evaluating a flow before or after implementation
+- Use when reviewing a mobile-first product for usability regressions
+- Use when you want findings framed as user experience problems with remediation
+
+## Audit Framework
+
+Review the target against:
+- visibility of system status
+- match between system and real-world language
+- user control and freedom
+- consistency and standards
+- error prevention
+- recognition rather than recall
+- flexibility and efficiency
+- aesthetic and minimalist design
+- recovery from errors
+- help, onboarding, and empty-state guidance
+
+Add mobile-specific checks for reachability, touch ergonomics, input burden, and thumb-friendly action placement.
+
+## Output
+
+Return:
+1. A prioritized issue list
+2. The heuristic violated by each issue
+3. Why the issue matters to real users
+4. Specific remediation suggestions for the page, component, or flow
+
+## Best Practices
+
+- Judge the experience from the user's point of view, not the implementer's
+- Separate high-severity flow blockers from minor polish issues
+- Include recovery and state-management guidance, not only layout comments
+- Tie recommendations back to concrete UI changes
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ux-audit/SKILL.md)
+
+## 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.

package/skills/global_config/ux-feedback/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ux-feedback
+description: "Add loading, empty, error, and success feedback states to StyleSeed components and pages with practical mobile-first rules."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ux, states, loading, error-handling, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UX Feedback
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill ensures data-dependent UI does not stop at the happy path. It adds the four core feedback states every serious product needs: loading, empty, error, and success.
+
+## When to Use
+- Use when a component or page fetches, mutates, or depends on async data
+- Use when a flow currently renders only the success path
+- Use when a card, list, or page needs better state communication
+- Use when the product needs clear recovery and confirmation behavior
+
+## The Four Required States
+
+### Loading
+
+Use skeletons that match the final layout. Avoid spinners inside cards unless the pattern genuinely requires them. Delay skeletons slightly to avoid flashes on fast responses.
+
+### Empty
+
+Provide a friendly explanation and a next action. Zero values should still render meaningfully instead of disappearing.
+
+### Error
+
+Use plain-language failure messages and always offer recovery where possible. Localize failures to the affected card or section if the rest of the page can still work.
+
+### Success
+
+Use toasts or equivalent lightweight confirmation for completed actions. Add undo for reversible destructive changes.
+
+## Output
+
+Return:
+1. The data-dependent areas identified
+2. The loading, empty, error, and success states added for each one
+3. Any reusable empty-state or toast patterns created
+4. Follow-up work needed for analytics, retries, or accessibility
+
+## Best Practices
+
+- Match loading placeholders to the real layout
+- Keep partial failure isolated whenever possible
+- Make recovery obvious, not hidden in logs or developer tools
+- Use success feedback sparingly but clearly
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ux-feedback/SKILL.md)
+
+## 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.

package/skills/global_config/ux-flow/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: ux-flow
+description: "Design user flows and screen structure using StyleSeed UX patterns such as progressive disclosure, hub-and-spoke navigation, and information pyramids."
+category: design
+risk: safe
+source: community
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: "2026-04-08"
+author: bitjaru
+tags: [ux, flows, navigation, product-design, styleseed]
+tools: [claude, cursor, codex, gemini]
+---
+
+# UX Flow
+
+## Overview
+
+Part of [StyleSeed](https://github.com/bitjaru/styleseed), this skill designs flows before screens. It uses proven UX patterns to define entry points, exits, screen inventory, and navigation structure so the implementation has a coherent user journey instead of a pile of disconnected pages.
+
+## When to Use
+- Use when planning onboarding, checkout, account management, dashboards, or drill-down flows
+- Use when a new feature spans multiple screens or modal states
+- Use when users need a clear path through a task instead of a single isolated page
+- Use when the UI needs navigation logic before components are built
+
+## How It Works
+
+### Information Architecture Principles
+
+- progressive disclosure: reveal complexity only when needed
+- Miller's Law: chunk content into manageable groups
+- Hick's Law: minimize decision overload on each screen
+
+### Common Navigation Models
+
+- hub and spoke for dashboards and detail views
+- linear flow for onboarding, forms, and checkout
+- tab navigation for 3 to 5 top-level areas
+
+### Flow Rules
+
+- every flow has a clear entry point
+- every flow has a clear exit or success condition
+- key features should usually be reachable within three taps from home
+- non-root screens need back navigation
+- loading, empty, and error states need explicit recovery paths
+
+## Output
+
+Provide:
+1. An ASCII flow diagram
+2. A screen inventory with each screen's purpose
+3. Edge cases for loading, empty, and error states
+4. Recommended page scaffolds and reusable patterns to implement next
+
+## Best Practices
+
+- Optimize for clarity before density
+- Let one screen answer one primary question
+- Keep escape hatches visible for risky or destructive steps
+- Define state transitions before drawing detailed layouts
+
+## Additional Resources
+
+- [StyleSeed repository](https://github.com/bitjaru/styleseed)
+- [Source skill](https://github.com/bitjaru/styleseed/blob/main/seeds/toss/.claude/skills/ux-flow/SKILL.md)
+
+## 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.

package/skills/global_config/ux-persuasion-engineer/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ux-persuasion-engineer
+description: "One sentence - what this skill does and when to invoke it"
+risk: safe
+source: community
+date_added: "2026-04-04"
+---
+You are a **Behavioral UX Researcher and Choice Architecture Specialist**. Your task is to apply behavioral psychology and persuasive design principles to UX flows. You reduce friction, increase commitment, and guide users toward the intended behavior without coercion.
+
+## When to Use
+- Use when a product or page UX should guide decisions more clearly through layout, sequencing, and cues.
+- Use when conversion friction comes from interaction design rather than copy alone.
+
+## CONTEXT GATHERING
+
+Before redesigning a flow, establish:
+
+1. **The Target Human** - psychographic profile, JTBD, and awareness stage.
+2. **The Objective** - the exact behavior the flow should enable.
+3. **The Output** - annotated UX flow or redesign brief.
+4. **Constraints** - platform, accessibility, conversion goals, and ethical limits.
+
+If the workflow or user goal is unclear, ask before proceeding.
+
+## PSYCHOLOGICAL FRAMEWORK: CHOICE ARCHITECTURE FLOW
+
+### Mechanism
+Behavior follows motivation, ability, and prompts, but most UX failures happen because the flow adds unnecessary cognitive load or hides the next step. Good UX persuasion reduces effort, makes defaults intelligent, and places commitment points where momentum can grow (Fogg behavior model; Thaler & Sunstein; Hick's Law; Fitts' Law; Stawarz et al., 2015; Karppinen, 2016).
+
+### Execution Steps
+
+**Step 1 - Define the target behavior**
+Name the one behavior the flow must produce.
+*Research basis: behavior change works best when the desired action is explicit and singular (Fogg; Volpp & Loewenstein, 2020).*
+
+**Step 2 - Audit friction**
+List every unnecessary decision, field, screen, and hesitation point.
+*Research basis: cognitive load and choice overload reduce follow-through (Hick's Law; Stawarz et al., 2015).*
+
+**Step 3 - Design the default path**
+Make the most helpful path the easiest path.
+*Research basis: defaults, simplification, and commitment devices shape behavior without force (Thaler & Sunstein; Karppinen, 2016).*
+
+**Step 4 - Insert commitment points**
+Add small yes-steps that build momentum before the big ask.
+*Research basis: commitment and consistency increase follow-through when effort is staged (Cialdini; Fogg).*
+
+**Step 5 - Check for ethical pressure**
+Ensure the design guides, does not trap.
+*Research basis: persuasive systems can become dark patterns if autonomy is weakened (Karppinen, 2016; design ethics literature).*
+
+## DECISION MATRIX
+
+### Variable: task complexity
+- If complex -> break into smaller steps and reduce working memory load.
+- If simple -> compress the path and minimize interruption.
+- If high stakes -> add reassurance, proof, and review steps.
+
+### Variable: user readiness
+- If low readiness -> use education, previews, and soft prompts.
+- If medium readiness -> use defaults and progress indicators.
+- If high readiness -> reduce to a direct action path.
+
+### Variable: friction type
+- If cognitive -> simplify decisions and language.
+- If emotional -> add reassurance and social proof.
+- If physical -> improve layout, spacing, and affordance.
+
+## FAILURE MODES - DO NOT DO THESE
+
+**Failure Mode 1**
+- Agents typically: add more persuasion instead of removing friction.
+- Why it fails psychologically: more pressure does not fix a confusing flow.
+- Instead: make the path clearer and shorter.
+
+**Failure Mode 2**
+- Agents typically: overload the user with choices and options.
+- Why it fails psychologically: too many decisions increase abandonment.
+- Instead: use one primary path and secondary escape hatches.
+
+**Failure Mode 3**
+- Agents typically: use persuasive UI patterns that feel like traps.
+- Why it fails psychologically: autonomy loss creates distrust and churn.
+- Instead: guide with clarity and easy exits.
+
+## ETHICAL GUARDRAILS
+
+This skill must:
+- Preserve informed choice.
+- Avoid dark patterns, sneaky defaults, or hidden opt-outs.
+- Support accessibility and clarity.
+
+The line between persuasion and manipulation is guiding behavior by making the intended path clearer versus narrowing choice through deception or coercion. Never cross it.
+
+## SKILL CHAINING
+
+Before invoking this skill, the agent should have completed:
+- [ ] `@customer-psychographic-profiler`
+- [ ] `@jobs-to-be-done-analyst`
+- [ ] `@awareness-stage-mapper`
+
+This skill's output feeds into:
+- [ ] `@onboarding-psychologist`
+- [ ] `@copywriting-psychologist`
+- [ ] `@brand-perception-psychologist`
+
+## OUTPUT QUALITY CHECK
+
+Before finalizing output, the agent asks:
+- [ ] Did I define one target behavior clearly?
+- [ ] Did I remove avoidable friction?
+- [ ] Did I choose sensible defaults and commitment points?
+- [ ] Did I preserve autonomy and accessibility?
+- [ ] Would the flow feel easier, not pushier?
+
+## 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.

package/skills/global_config/vector-database-engineer/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: vector-database-engineer
+description: "Expert in vector databases, embedding strategies, and semantic search implementation. Masters Pinecone, Weaviate, Qdrant, Milvus, and pgvector for RAG applications, recommendation systems, and similar"
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Vector Database Engineer
+
+Expert in vector databases, embedding strategies, and semantic search implementation. Masters Pinecone, Weaviate, Qdrant, Milvus, and pgvector for RAG applications, recommendation systems, and similarity search. Use PROACTIVELY for vector search implementation, embedding optimization, or semantic retrieval systems.
+
+## Do not use this skill when
+
+- The task is unrelated to vector database engineer
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Capabilities
+
+- Vector database selection and architecture
+- Embedding model selection and optimization
+- Index configuration (HNSW, IVF, PQ)
+- Hybrid search (vector + keyword) implementation
+- Chunking strategies for documents
+- Metadata filtering and pre/post-filtering
+- Performance tuning and scaling
+
+## Use this skill when
+
+- Building RAG (Retrieval Augmented Generation) systems
+- Implementing semantic search over documents
+- Creating recommendation engines
+- Building image/audio similarity search
+- Optimizing vector search latency and recall
+- Scaling vector operations to millions of vectors
+
+## Workflow
+
+1. Analyze data characteristics and query patterns
+2. Select appropriate embedding model
+3. Design chunking and preprocessing pipeline
+4. Choose vector database and index type
+5. Configure metadata schema for filtering
+6. Implement hybrid search if needed
+7. Optimize for latency/recall tradeoffs
+8. Set up monitoring and reindexing strategies
+
+## Best Practices
+
+- Choose embedding dimensions based on use case (384-1536)
+- Implement proper chunking with overlap
+- Use metadata filtering to reduce search space
+- Monitor embedding drift over time
+- Plan for index rebuilding
+- Cache frequent queries
+- Test recall vs latency tradeoffs
+
+## 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.

package/skills/global_config/vercel-ai-sdk-expert/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: vercel-ai-sdk-expert
+description: "Expert in the Vercel AI SDK. Covers Core API (generateText, streamText), UI hooks (useChat, useCompletion), tool calling, and streaming UI components with React and Next.js."
+risk: safe
+source: community
+date_added: "2026-03-06"
+---
+
+# Vercel AI SDK Expert
+
+You are a production-grade Vercel AI SDK expert. You help developers build AI-powered applications, chatbots, and generative UI experiences primarily using Next.js and React. You are an expert in both the `ai` (AI SDK Core) and `@ai-sdk/react` (AI SDK UI) packages. You understand streaming, language model integration, system prompts, tool calling (function calling), and structured data generation.
+
+## When to Use This Skill
+
+- Use when adding AI chat or text generation features to a React or Next.js app
+- Use when streaming LLM responses to a frontend UI
+- Use when implementing tool calling / function calling with an LLM
+- Use when returning structured data (JSON) from an LLM using `generateObject`
+- Use when building AI-powered generative UIs (streaming React components)
+- Use when migrating from direct OpenAI/Anthropic API calls to the unified AI SDK
+- Use when troubleshooting streaming issues with `useChat` or `streamText`
+
+## Core Concepts
+
+### Why Vercel AI SDK?
+
+The Vercel AI SDK is a unified framework that abstracts away provider-specific APIs (OpenAI, Anthropic, Google Gemini, Mistral). It provides two main layers:
+1. **AI SDK Core (`ai`)**: Server-side functions to interact with LLMs (`generateText`, `streamText`, `generateObject`).
+2. **AI SDK UI (`@ai-sdk/react`)**: Frontend hooks to manage chat state and streaming (`useChat`, `useCompletion`).
+
+## Server-Side Generation (Core API)
+
+### Basic Text Generation
+
+```typescript
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+// Returns the full string once completion is done (no streaming)
+const { text, usage } = await generateText({
+  model: openai("gpt-4o"),
+  system: "You are a helpful assistant evaluating code.",
+  prompt: "Review the following python code...",
+});
+
+console.log(text);
+console.log(`Tokens used: ${usage.totalTokens}`);
+```
+
+### Streaming Text
+
+```typescript
+// app/api/chat/route.ts (Next.js App Router API Route)
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    system: 'You are a friendly customer support bot.',
+    messages,
+  });
+
+  // Automatically converts the stream to a readable web stream
+  return result.toDataStreamResponse();
+}
+```
+
+### Structured Data (JSON) Generation
+
+```typescript
+import { generateObject } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const { object } = await generateObject({
+  model: openai('gpt-4o-2024-08-06'), // Use models good at structured output
+  system: 'Extract information from the receipt text.',
+  prompt: receiptText,
+  // Pass a Zod schema to enforce output structure
+  schema: z.object({
+    storeName: z.string(),
+    totalAmount: z.number(),
+    items: z.array(z.object({
+      name: z.string(),
+      price: z.number(),
+    })),
+    date: z.string().describe("ISO 8601 date format"),
+  }),
+});
+
+// `object` is automatically fully typed according to the Zod schema!
+console.log(object.totalAmount); 
+```
+
+## Frontend UI Hooks
+
+### `useChat` (Conversational UI)
+
+```tsx
+// app/page.tsx (Next.js Client Component)
+"use client";
+
+import { useChat } from "ai/react";
+
+export default function Chat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    api: "/api/chat", // Points to the streamText route created above
+    // Optional callbacks
+    onFinish: (message) => console.log("Done streaming:", message),
+    onError: (error) => console.error(error)
+  });
+
+  return (
+    <div className="flex flex-col h-screen max-w-md mx-auto p-4">
+      <div className="flex-1 overflow-y-auto mb-4">
+        {messages.map((m) => (
+          <div key={m.id} className={`mb-4 ${m.role === 'user' ? 'text-right' : 'text-left'}`}>
+            <span className={`p-2 rounded-lg inline-block ${m.role === 'user' ? 'bg-blue-500 text-white' : 'bg-gray-200'}`}>
+              {m.target || m.content}
+            </span>
+          </div>
+        ))}
+      </div>
+      
+      <form onSubmit={handleSubmit} className="flex gap-2">
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Say something..."
+          className="flex-1 p-2 border rounded"
+          disabled={isLoading}
+        />
+        <button type="submit" disabled={isLoading} className="bg-black text-white p-2 rounded">
+          Send
+        </button>
+      </form>
+    </div>
+  );
+}
+```
+
+## Tool Calling (Function Calling)
+
+Tools allow the LLM to interact with your code, fetching external data or performing actions before responding to the user.
+
+### Server-Side Tool Definition
+
+```typescript
+// app/api/chat/route.ts
+import { streamText, tool } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    messages,
+    tools: {
+      getWeather: tool({
+        description: 'Get the current weather in a given location',
+        parameters: z.object({
+          location: z.string().describe('The city and state, e.g. San Francisco, CA'),
+          unit: z.enum(['celsius', 'fahrenheit']).optional(),
+        }),
+        // Execute runs when the LLM decides to call this tool
+        execute: async ({ location, unit = 'celsius' }) => {
+          // Fetch from your actual weather API or database
+          const temp = location.includes("San Francisco") ? 15 : 22;
+          return `The weather in ${location} is ${temp}° ${unit}.`;
+        },
+      }),
+    },
+    // Allows the LLM to call tools automatically in a loop until it has the answer
+    maxSteps: 5, 
+  });
+
+  return result.toDataStreamResponse();
+}
+```
+
+### UI for Multi-Step Tool Calls
+
+When using `maxSteps`, the `useChat` hook will display intermediate tool calls if you handle them in the UI.
+
+```tsx
+// Inside the `useChat` messages.map loop
+{m.role === 'assistant' && m.toolInvocations?.map((toolInvocation) => (
+  <div key={toolInvocation.toolCallId} className="text-sm text-gray-500">
+    {toolInvocation.state === 'result' ? (
+      <p>✅ Fetched weather for {toolInvocation.args.location}</p>
+    ) : (
+      <p>⏳ Fetching weather for {toolInvocation.args.location}...</p>
+    )}
+  </div>
+))}
+```
+
+## Best Practices
+
+- ✅ **Do:** Use `openai('gpt-4o')` or `anthropic('claude-3-5-sonnet-20240620')` format (from specific provider packages like `@ai-sdk/openai`) instead of the older edge runtime wrappers.
+- ✅ **Do:** Provide a strict Zod `schema` and a clear `system` prompt when using `generateObject()`.
+- ✅ **Do:** Set `maxDuration = 30` (or higher if on Pro) in Next.js API routes that use `streamText`, as LLMs take time to stream responses and Vercel's default is 10-15s.
+- ✅ **Do:** Use `tool()` with comprehensive `description` tags on Zod parameters, as the LLM relies entirely on those strings to understand when and how to call the tool.
+- ✅ **Do:** Enable `maxSteps: 5` (or similar) when providing tools, otherwise the LLM won't be able to reply to the user *after* seeing the tool result!
+- ❌ **Don't:** Forget to return `result.toDataStreamResponse()` in Next.js App Router API routes when using `streamText`; standard JSON responses will break chunking.
+- ❌ **Don't:** Blindly trust the output of `generateObject` without validation, even though Zod forces the shape — always handle failure states using `try/catch`.
+
+## Troubleshooting
+
+**Problem:** The streaming chat cuts off abruptly after 10-15 seconds.
+**Solution:** The serverless function timed out. Add `export const maxDuration = 30;` (or whatever your plan limit is) to the Next.js API route file.
+
+**Problem:** "Tool execution failed" or the LLM didn't return an answer after using a tool.
+**Solution:** `streamText` stops immediately after a tool call completes unless you provide `maxSteps`. Set `maxSteps: 2` (or higher) to let the LLM see the tool result and construct a final text response.
+
+## 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.