# Agent Skills

Curated agent skill fleet for Mosaic Stack. Covers coding, business development, design, marketing, orchestration, and more. Platform-aware — works with both GitHub (`gh`) and Gitea (`tea`) via our abstraction scripts.

## Skills (23)

### Code Quality & Review

| Skill | Purpose | Origin |
|-------|---------|--------|
| `pr-reviewer` | Structured PR code review workflow (Gitea/GitHub) | Adapted from [SpillwaveSolutions](https://github.com/SpillwaveSolutions/pr-reviewer-skill) |
| `code-review-excellence` | Code review methodology and checklists | Adapted from [awesome-skills](https://github.com/awesome-skills/code-review-skill) |
| `verification-before-completion` | Evidence-based completion claims — no success without verification | [obra/superpowers](https://github.com/obra/superpowers) |

### Frontend & UI

| Skill | Purpose | Origin |
|-------|---------|--------|
| `next-best-practices` | Next.js 15+ — RSC, async patterns, self-hosting, data patterns | [vercel-labs/next-skills](https://github.com/vercel-labs/next-skills) |
| `vercel-react-best-practices` | React/Next.js performance optimization (57 rules) | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) |
| `shadcn-ui` | Component patterns — forms, dialogs, tables, charts | [developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit) |
| `tailwind-design-system` | Tailwind CSS v4 design system patterns | Adapted from [wshobson/agents](https://github.com/wshobson/agents) |
| `ui-animation` | Motion design — performance, accessibility, easing curves | [mblode/agent-skills](https://github.com/mblode/agent-skills) |

### Backend & API

| Skill | Purpose | Origin |
|-------|---------|--------|
| `nestjs-best-practices` | NestJS — 40 rules across 10 categories, priority-ranked | [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) |
| `fastapi` | FastAPI with Pydantic v2, async SQLAlchemy 2.0, JWT auth | [jezweb/claude-skills](https://github.com/jezweb/claude-skills) |
| `architecture-patterns` | Clean Architecture, Hexagonal, DDD patterns | [wshobson/agents](https://github.com/wshobson/agents) |
| `python-performance-optimization` | Profiling, memory optimization, parallelization | [wshobson/agents](https://github.com/wshobson/agents) |

### Authentication

| Skill | Purpose | Origin |
|-------|---------|--------|
| `better-auth-best-practices` | Better-Auth — Drizzle adapter, sessions, plugins, security | [better-auth/skills](https://github.com/better-auth/skills) |

### AI & Agent Building

| Skill | Purpose | Origin |
|-------|---------|--------|
| `ai-sdk` | Vercel AI SDK — streaming, multi-provider, agent patterns | [vercel/ai](https://github.com/vercel/ai) |
| `create-agent` | Modular agent architecture with OpenRouter multi-model access | [openrouterteam/agent-skills](https://github.com/openrouterteam/agent-skills) |
| `proactive-agent` | Proactive agent architecture — WAL Protocol, compaction recovery, self-improvement | [halthelobster/proactive-agent](https://github.com/halthelobster/proactive-agent) |

### Marketing & Business Development

| Skill | Purpose | Origin |
|-------|---------|--------|
| `marketing-ideas` | 139 proven marketing ideas across 14 categories | [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) |
| `pricing-strategy` | SaaS pricing — value metrics, tier design, research methods | [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) |
| `programmatic-seo` | SEO at scale — templates, playbooks, internal linking | [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) |
| `competitor-alternatives` | Competitor comparison pages — content architecture, templates | [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) |
| `referral-program` | Referral & affiliate programs — incentives, metrics, launch | [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) |

### Design & Brand

| Skill | Purpose | Origin |
|-------|---------|--------|
| `brand-guidelines` | Brand identity enforcement — fonts, colors, styling | [anthropics/skills](https://github.com/anthropics/skills) |

### Meta / Skill Authoring

| Skill | Purpose | Origin |
|-------|---------|--------|
| `writing-skills` | TDD-based methodology for creating and testing agent skills | [obra/superpowers](https://github.com/obra/superpowers) |

## Mosaic Stack Alignment

These skills are curated for the Mosaic Stack platform, which serves coding, business development, design, marketing, writing, logistics, analysis, and more. The Orchestrator and subagents can load any combination of skills based on the task at hand.

**Core tech stack:**
- **Backend:** NestJS + TypeScript
- **Frontend:** Next.js 15 + React 19 (App Router)
- **Styling:** Tailwind CSS v4 + shadcn/ui
- **Auth:** Better-Auth with Drizzle adapter
- **Database:** PostgreSQL + Drizzle ORM
- **CI/CD:** Woodpecker CI / Gitea
- **Deployment:** Docker Swarm

Skills are either used as-is (when framework-agnostic or matching our stack) or adapted with Mosaic Stack-specific notes where upstream assumptions differ.

## Installation

### Via npx (recommended)

```bash
# Install a single skill
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --skill nestjs-best-practices --agent claude-code

# Install all skills
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --agent claude-code

# Non-interactive (CI/scripting)
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --skill pr-reviewer --yes --agent claude-code
```

**Note:** The `.git` suffix on the URL is required for Gitea-hosted repos (forces git clone instead of well-known endpoint discovery).

### Manual (symlink from local clone)

```bash
# Clone the repo
git clone https://git.mosaicstack.dev/mosaic/agent-skills.git ~/src/agent-skills

# Symlink all skills
for skill in ~/src/agent-skills/skills/*/; do
  ln -sf "$skill" ~/.claude/skills/$(basename "$skill")
done
```

### Per-Project

Symlink into a project's `.claude/skills/` directory for project-specific availability.

## Dependencies

- `~/.claude/scripts/git/` — Platform-aware git scripts (pr-reviewer only)
- `python3` — For review file generation (pr-reviewer only)

## Adapting Skills

When adding skills from the community:

1. Replace raw `gh`/`tea` calls with our `~/.claude/scripts/git/` scripts
2. Test on both GitHub and Gitea repos
3. Remove features that don't work cross-platform
4. Add Mosaic Stack context notes where upstream assumptions differ
5. Document any platform-specific limitations

## License

Individual skills retain their original licenses. Adaptations are MIT.