How to Browse and Search the Skill Catalog in Antigravity Awesome Skills

The Antigravity Awesome Skills web app provides a searchable, filterable interface to the skill catalog through a React-based UI that supports debounced text search, category filtering, and multiple sort options including star count and recency.

The sickn33/antigravity-awesome-skills repository includes a lightweight Vite-powered React single-page application located in apps/web-app that exposes the skill catalog via a responsive web interface. This application consumes the skills_index.json catalog and individual skill files from the repository's skills/ directory, offering real-time search capabilities and on-demand synchronization with the upstream GitHub repository.

Web App Architecture Overview

The web app follows a layered architecture that separates data fetching, state management, and presentation concerns across distinct modules in the apps/web-app directory.

Entry Point and Global State

The application bootstrap occurs in apps/web-app/src/main.tsx, which mounts the React tree and wraps the entire application with SkillProvider. This provider, defined in apps/web-app/src/context/SkillContext.tsx, fetches the master skill index from /skills.json on startup using the base URL from import.meta.env.BASE_URL (injected by Vite), and optionally loads star counts from Supabase. It exposes the useSkills hook, which returns skills, stars, loading, and refreshSkills to consuming components.

UI Components and Real-Time Filtering

The main catalog interface lives in apps/web-app/src/pages/Home.tsx. This component consumes the useSkills hook and implements:

• Debounced search: User input is processed through lodash.debounce with a 300ms delay to prevent excessive recomputation during typing
• Category filtering: Dropdown selection to narrow results by skill category
• Sort selector: Options include default, ⭐ Most Stars, 🆕 Newest, and 🔤 A → Z
• Sync button: Triggers a POST request to /api/refresh-skills to pull latest data from GitHub

The component renders individual entries using the SkillCard component and maintains a memoized filteredSkills array that recomputes only when search terms, category selections, or sort options change.

Data Serving and On-Demand Sync

A custom Vite plugin in apps/web-app/refresh-skills-plugin.js handles data serving without requiring a separate backend. The plugin injects three middleware routes:

• /skills.json serves the skills_index.json catalog file from the repository root
• /skills/* serves individual skill definition files from the repository's skills/ folder with safe symlink resolution
• /api/refresh-skills accepts POST requests to synchronize the local catalog with the upstream repository via git fetch-merge or archive download fallback

The Vite configuration in apps/web-app/vite.config.ts injects this plugin and defines the development server base URL used throughout the application.

How to Search and Filter the Skill Catalog

To browse the catalog locally:

1. Navigate to apps/web-app and run npm install followed by npm run dev
2. Open http://localhost:5173 in your browser
3. Use the search bar at the top to filter skills by name or description (input is debounced automatically)
4. Select a category from the dropdown to filter by skill type
5. Choose a sort order from the selector to arrange results by popularity (stars), recency, or alphabetically
6. Click Sync Skills to refresh the catalog with the latest upstream changes

Programmatic Access to Skill Data

Developers can interact with the catalog data directly using the exposed React context or API endpoints.

Accessing Skills via the useSkills Hook

Import the useSkills hook from SkillContext.tsx to access the loaded catalog within any component:

import { useSkills } from '@/context/SkillContext';

export function SkillStats() {
  const { skills, stars, loading } = useSkills();

  if (loading) return <p>Loading…</p>;

  const total = skills.length;
  const starred = Object.values(stars).reduce((a, b) => a + b, 0);

  return (
    <div>
      <p>Total skills: {total}</p>
      <p>Total stars: {starred}</p>
    </div>
  );
}

Triggering Catalog Synchronization

To manually refresh the skill catalog from code, POST to the refresh endpoint implemented in refresh-skills-plugin.js:

async function manualRefresh() {
  const response = await fetch('/api/refresh-skills', { method: 'POST' });
  const data = await response.json();

  if (data.success) {
    console.log(`Synced ${data.count} skills`);
  } else {
    console.error('Refresh failed:', data.error);
  }
}

The endpoint returns a JSON payload containing success, upToDate, and count properties indicating the synchronization status.

Extending the Filter Interface

You can add custom filters by extending the state management in Home.tsx. For example, to filter by programming language:

<select
  aria-label="Filter by language"
  value={languageFilter}
  onChange={e => setLanguageFilter(e.target.value)}
>
  <option value="all">All Languages</option>
  <option value="javascript">JavaScript</option>
  <option value="python">Python</option>
  {/* …more options … */}
</select>

Integrate this into the existing filteredSkills memoization logic alongside the existing search and category filters.

Summary

• The Antigravity Awesome Skills web app in apps/web-app provides a complete React-based interface for browsing the skill catalog
• Search functionality uses a 300ms debounced input handled by lodash.debounce in Home.tsx to optimize performance
• The useSkills hook from SkillContext.tsx provides global access to catalog data, loading states, star counts, and the refreshSkills method
• Sorting options include Most Stars, Newest, and A→Z alongside the default ordering
• The custom Vite plugin in refresh-skills-plugin.js serves catalog data at /skills.json, individual skills at /skills/*, and handles on-demand synchronization via /api/refresh-skills
• Key files: Entry at main.tsx, UI logic in pages/Home.tsx, state in context/SkillContext.tsx, and build configuration in vite.config.ts

Frequently Asked Questions

How do I start the web app locally?

Navigate to the apps/web-app directory, install dependencies with npm install, and run npm run dev. According to the vite.config.ts configuration, Vite will start the development server at http://localhost:5173, where you can immediately begin browsing and searching the skill catalog.

Where does the search data come from?

The application fetches skills_index.json from the relative path /skills.json on startup via the SkillProvider in context/SkillContext.tsx. The base URL is resolved from import.meta.env.BASE_URL. This JSON file serves as the master catalog, with individual skill details loaded from the skills/ directory through the custom Vite plugin's /skills/* route with safe symlink resolution.

Can I add custom filters beyond category and search?

Yes. The Home.tsx component manages filter state using React hooks and computes filtered results through a memoized filteredSkills array. You can extend the existing logic by adding new state variables (such as languageFilter) and incorporating them into the memoization dependencies, following the pattern established for the category dropdown and debounced search input.

How does the sync button work?

Clicking Sync Skills triggers a POST request to /api/refresh-skills, implemented by the refresh-skills-plugin.js middleware. This endpoint pulls the latest skill definitions from the upstream GitHub repository using either a fast git fetch-merge or an archive download fallback. It updates the local skills/ folder and returns a JSON response ({success, upToDate, count}) that the UI displays as a transient toast notification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}