skillhub: Instructions file for Claude Code

CLAUDE.md

Project Overview

SkillHub is an open-source marketplace for Agent Skills — folders containing a SKILL.md file with instructions that AI agents can load dynamically.

Live Site: https://skills.palebluedot.live | Status: Production (GET /api/stats)

Components:

• Web App (apps/web): Next.js 15 marketplace
• CLI (apps/cli): Skill installer (npm install -g skillhub)
• Indexer (services/indexer): GitHub crawler
• Packages (packages/*): Core logic, DB, UI components

Common Commands

pnpm install                              # Install dependencies
pnpm dev                                  # Start all apps
pnpm --filter @skillhub/web dev           # Start only web app
pnpm build                                # Build all packages
pnpm test                                 # Run all tests (248 total)
pnpm --filter @skillhub/web test:e2e      # E2E tests (requires running app)
pnpm db:push                              # Push schema changes
docker compose up -d                      # Start all services

Architecture

skillhub/
├── apps/
│   ├── web/           # Next.js 15 + App Router + next-intl (i18n)
│   └── cli/           # Commander.js CLI, builds with tsup
├── packages/
│   ├── core/          # SKILL.md parser, validator, security scanner
│   ├── db/            # Drizzle ORM schema and queries
│   └── ui/            # Shared shadcn/ui components
├── services/
│   └── indexer/       # BullMQ worker for GitHub crawling
└── scripts/           # Database initialization scripts

Database

Schema files (keep in sync):

• scripts/init-db.sql — SQL schema
• packages/db/src/schema.ts — Drizzle ORM schema
• scripts/categories.sql — Production categories
• scripts/seed-data.sql — Dev sample data

Caching: Skill files cached in cached_files JSONB column, invalidated when commitSha changes.

Important Patterns

Next.js 15 Async Params

params and searchParams are Promises:

export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
  const { locale } = await params;
}