# Agent Skills

Custom agent skills for Mosaic Stack and USC projects. Platform-aware — works with both GitHub (`gh`) and Gitea (`tea`) via our abstraction scripts.

## Skills

### Code Quality & Review

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

### Frontend & UI

| Skill | Purpose | Origin |
|-------|---------|--------|
| `next-best-practices` | Next.js 15+ best practices — RSC, async patterns, self-hosting, data patterns | From [vercel-labs/next-skills](https://github.com/vercel-labs/next-skills) |
| `vercel-react-best-practices` | React/Next.js performance optimization (57 rules) | From [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) |
| `shadcn-ui` | shadcn/ui component patterns — forms, dialogs, tables, charts | From [giuseppe-trisciuoglio/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) |

### Authentication

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

### Meta / Skill Authoring

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

## Mosaic Stack Alignment

These skills are curated for the Mosaic Stack 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 (e.g., shadcn-ui references Tailwind v3 config patterns).

## Installation

### Via npx (recommended)

Install individual skills into any agent:

```bash
# Install a single skill
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --skill pr-reviewer --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

# Or symlink individually
ln -sf ~/src/agent-skills/skills/pr-reviewer ~/.claude/skills/pr-reviewer
ln -sf ~/src/agent-skills/skills/next-best-practices ~/.claude/skills/next-best-practices
ln -sf ~/src/agent-skills/skills/better-auth-best-practices ~/.claude/skills/better-auth-best-practices
# ... etc
```

### Per-Project

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

## Dependencies

- `~/.claude/scripts/git/` — Platform-aware git scripts (detect-platform, pr-view, pr-diff, pr-metadata, pr-review, etc.)
- `python3` — For review file generation (pr-reviewer)

## 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 (e.g., GitHub-specific inline comments)
4. Add Mosaic Stack context notes where upstream assumptions differ from our stack
5. Document any platform-specific limitations

## License

Individual skills retain their original licenses. Adaptations are MIT.