uberSKILLS

Design, test, and deploy Agent Skills through a visual, AI-assisted workflow.

uberSKILLS replaces manual SKILL.md authoring with a structured editor, multi-model testing sandbox, and one-click deployment to your agent's skills directory.

What is uberSKILLS?

Creating Agent Skills today is entirely manual -- authors hand-write YAML frontmatter and markdown instructions, with no built-in way to preview, validate, or test a skill before deploying it.

uberSKILLS is an open-source web application that provides an integrated authoring environment purpose-built for the SKILL.md format, with deploy support for Antigravity, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and Windsurf:

• Skills Library -- Browse, search, filter, and manage all your skills in one place
• AI-Assisted Creation -- Describe what you want in natural language; get a complete SKILL.md draft
• Structured Editor -- Edit metadata, instructions, and files with real-time validation and auto-save
• Multi-Model Testing -- Test skills against any model on OpenRouter with streaming responses and metrics
• Export & Deploy -- One-click deploy to 8 agent tools including Claude Code, GitHub Copilot, Cursor, and Windsurf, or export as zip
• Import -- Bulk-import existing skills from directories or zip archives
• Version History -- Every change is versioned; browse and compare past versions

Tech Stack

Layer	Technology
Monorepo	Turborepo + pnpm
Framework	Next.js 15 (App Router)
UI	shadcn/ui + Tailwind CSS v4
Database	SQLite + Drizzle ORM
AI SDK	Vercel AI SDK + OpenRouter provider
AI Provider	OpenRouter (Claude, GPT, Gemini, Llama, etc.)
Logging	Pino (JSON in production, pino-pretty in development)
Language	TypeScript (strict)
Testing	Vitest + Playwright
Linting	Biome

Quickstart

Run uberSKILLS with a single command — no cloning, no setup:

npx @uberskillsdev/uberskills

That's it. On first run it will automatically set up everything (~2 minutes), then start the server at http://localhost:3000.

Your data is stored at ~/.uberskills/data/ and persists across runs.

Options

--port <number>    Port to run on (default: 3000)
--host <string>    Host to bind to (default: localhost)
--data-dir <path>  Custom data directory (default: ~/.uberskills/data/)
--reset            Delete cached install and re-setup
-d, --debug        Enable debug log level

Prerequisites

• Node.js >= 20
• git — available in PATH

Development Setup

If you want to contribute or run from source:

# Clone the repository
git clone https://github.com/uberskillsdev/uberskills.git
cd uberskills

# Install dependencies (pnpm is enabled via corepack)
corepack enable
pnpm install

# Start the development server
pnpm dev

Open http://localhost:3000. On first launch the app will automatically:

1. Create the data/ directory and SQLite database
2. Run Drizzle migrations to initialize the schema
3. Generate an encryption secret at data/.secret
4. Open the Settings page prompting for an OpenRouter API key

No Docker, no Postgres, no signup required.

Project Structure

uberskills/
├── apps/
│   ├── web/                 # Next.js 15 — Skills editor app (port 3000)
│   └── landing/             # Next.js 15 — Static landing page (port 3001)
├── packages/
│   ├── types/               # Shared TypeScript interfaces
│   ├── db/                  # Database schema, client, queries (Drizzle + SQLite)
│   ├── skill-engine/        # SKILL.md parser, validator, generator, importer, exporter
│   └── ui/                  # Shared UI components, ThemeProvider, design tokens (shadcn/ui)
├── docs/                    # Project documentation
├── turbo.json               # Turborepo pipeline configuration
├── biome.json               # Linter and formatter configuration
└── tsconfig.json            # Base TypeScript configuration

Available Scripts

Command	Description
pnpm dev	Start all dev servers (web :3000, landing :3001)
pnpm dev:web	Start only the editor app on port 3000
pnpm dev:landing	Start only the landing page on port 3001
pnpm build	Build all packages and apps for production
pnpm lint	Run Biome linting across the entire monorepo
pnpm lint:fix	Auto-fix lintable issues
pnpm format	Format all files with Biome
pnpm test	Run unit tests with Vitest across all packages
pnpm typecheck	Run TypeScript type checking across all packages
pnpm db:migrate	Run database migrations

Environment Variables

Variable	Required	Default	Description
DATABASE_URL	No	file:data/uberskills.db	SQLite database file path
ENCRYPTION_SECRET	No	Auto-generated	AES-256 key for encrypting the API key. Generated on first run at data/.secret if not set
PORT	No	3000	Development server port
LOG_LEVEL	No	info	Pino log level (debug, info, warn, error, fatal, silent)
NODE_ENV	No	development	Environment mode

Set these in apps/web/.env.local or apps/landing/.env.local (not committed to version control).

Detailed Documentation

Full project documentation is available in the docs/ directory:

• Getting Started -- Installation, setup, and first steps
• Features Guide -- How to use the skills library, editor, testing, import/export
• Architecture -- Monorepo structure, package responsibilities, data flow
• API Reference -- REST API endpoints and response formats
• Database -- Schema, Drizzle ORM patterns, queries
• AI Integration -- OpenRouter, Vercel AI SDK, streaming
• Skill Engine -- Parser, validator, generator, importer, exporter
• Security -- Encryption, input validation, filesystem safety
• Deployment -- Docker, Vercel, self-hosting options

Docker

Build and run via Docker:

docker compose up -d

The app will be available at http://localhost:3000. The data/ directory is mounted as a volume for persistence.

See Dockerfile and docker-compose.yml for details.

Contributing

Contributions are welcome! Please read the Contributing Guide for details on our development workflow, coding standards, and how to submit pull requests.

License

MIT