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

> Easily browse and search the Antigravity Awesome Skills catalog with our React UI. Filter by category, sort by stars or recency, and use debounced text search to find skills fast.

- Repository: [sickn33/antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)
- Tags: how-to-guide
- Published: 2026-03-18

---

**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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/apps/web-app/src/context/SkillContext.tsx), fetches the master skill index from [`/skills.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main//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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/apps/web-app/refresh-skills-plugin.js) handles data serving without requiring a separate backend. The plugin injects three middleware routes:

- [`/skills.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main//skills.json) serves the [`skills_index.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/SkillContext.tsx) to access the loaded catalog within any component:

```tsx
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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/refresh-skills-plugin.js):

```ts
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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/Home.tsx). For example, to filter by programming language:

```tsx
<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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/Home.tsx) to optimize performance
- The **`useSkills`** hook from [`SkillContext.tsx`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/refresh-skills-plugin.js) serves catalog data at [`/skills.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main//skills.json), individual skills at `/skills/*`, and handles on-demand synchronization via `/api/refresh-skills`
- **Key files**: Entry at [`main.tsx`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/main.tsx), UI logic in [`pages/Home.tsx`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/pages/Home.tsx), state in [`context/SkillContext.tsx`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/context/SkillContext.tsx), and build configuration in [`vite.config.ts`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/skills_index.json) from the relative path [`/skills.json`](https://github.com/sickn33/antigravity-awesome-skills/blob/main//skills.json) on startup via the `SkillProvider` in [`context/SkillContext.tsx`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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`](https://github.com/sickn33/antigravity-awesome-skills/blob/main/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.