agent-skills/README.md

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
code-review-excellence	Code review methodology and checklists	Adapted from awesome-skills/code-review-skill
verification-before-completion	Evidence-based completion claims — no success without verification	From 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
vercel-react-best-practices	React/Next.js performance optimization (57 rules)	From vercel-labs/agent-skills
shadcn-ui	shadcn/ui component patterns — forms, dialogs, tables, charts	From giuseppe-trisciuoglio/developer-kit
tailwind-design-system	Tailwind CSS v4 design system patterns	Adapted from wshobson/agents

Authentication

Skill	Purpose	Origin
better-auth-best-practices	Better-Auth integration — Drizzle adapter, sessions, plugins, security	From better-auth/skills

Meta / Skill Authoring

Skill	Purpose	Origin
writing-skills	TDD-based methodology for creating and testing agent skills	From 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:

# 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)

# 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.