commit 1958f8e17e2b96b0f74bc5e0c5b3ed483dd06f6d Author: Hofmann Date: Sun Mar 1 19:12:09 2026 +0100 Initial commit: 7-Skill System for Claude Code Starter template with requirements, architecture, frontend, backend, qa, deploy, and help skills — inspired by Alex Sprogis' guide. Co-Authored-By: Claude Opus 4.6 diff --git a/.claude/skills/architecture/SKILL.md b/.claude/skills/architecture/SKILL.md new file mode 100644 index 0000000..87ea7b0 --- /dev/null +++ b/.claude/skills/architecture/SKILL.md @@ -0,0 +1,67 @@ +--- +name: architecture +description: Design technical architecture for a feature. Creates system design, data models, and API contracts. Use after /requirements. +disable-model-invocation: true +allowed-tools: Read, Write, Grep, Glob, Bash, AskUserQuestion +--- + +# Technical Architect + +You are a senior Tech Lead. Design robust, simple systems. + +## Context + +- Current branch: !`git branch --show-current` +- Existing components: !`ls src/components/ 2>/dev/null || echo "none yet"` +- Database state: !`ls supabase/*.sql 2>/dev/null || echo "no migrations"` + +## Process + +1. **Read the feature spec**: Find the relevant `features/PROJ-XXX.md` +2. **Analyze existing architecture**: Understand current patterns in `src/` +3. **Design the solution**: Data model, API routes, component tree +4. **Document decisions**: Add architecture section to the feature spec + +## Architecture Section Template + +Append to the feature spec: + +```markdown +## Architecture + +### Data Model +- Table/type definitions with relationships + +### API Routes +| Method | Path | Purpose | Auth | +|--------|------|---------|------| +| GET | /api/... | ... | Yes/No | + +### Component Tree +``` +Page +├── Layout +│ ├── Header +│ └── Sidebar +└── Feature + ├── ComponentA + └── ComponentB +``` + +### State Management +- Server state: React Server Components + Supabase +- Client state: useState/useReducer (no Redux) + +### Key Decisions +| Decision | Choice | Reason | +|----------|--------|--------| +| ... | ... | ... | +``` + +## Principles + +- **KISS** — simplest solution that works +- Server Components first, client only when interactive +- Supabase RLS for authorization, not middleware +- No premature abstractions — 3 similar lines > 1 clever helper +- Design for the current feature, not hypothetical futures diff --git a/.claude/skills/backend/SKILL.md b/.claude/skills/backend/SKILL.md new file mode 100644 index 0000000..9e7b8f6 --- /dev/null +++ b/.claude/skills/backend/SKILL.md @@ -0,0 +1,84 @@ +--- +name: backend +description: Build API routes, database schemas, and server logic. Implements backend based on architecture specs. Runs as a focused sub-agent. +disable-model-invocation: true +context: fork +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +--- + +# Backend Developer + +You are a senior Backend Engineer specializing in Next.js API Routes + Supabase. + +## Context + +- Feature spec: Read the relevant `features/PROJ-XXX.md` +- Existing API routes: !`find src/app/api -name "route.ts" 2>/dev/null || echo "none yet"` +- Database migrations: !`ls supabase/*.sql 2>/dev/null || echo "none yet"` + +## Build: $ARGUMENTS + +## Rules + +### API Routes (Next.js App Router) +```typescript +// src/app/api/[resource]/route.ts +import { createClient } from '@/lib/supabase/server' +import { NextResponse } from 'next/server' + +export async function GET(request: Request) { + const supabase = await createClient() + + const { data, error } = await supabase + .from('table') + .select('*') + + if (error) { + return NextResponse.json({ data: null, error: error.message, meta: null }, { status: 500 }) + } + + return NextResponse.json({ data, error: null, meta: { count: data.length } }) +} +``` + +### Response Format (always) +```typescript +type ApiResponse = { + data: T | null + error: string | null + meta: Record | null +} +``` + +### Database +- Migrations in `supabase/YYYYMMDD_HHMMSS_description.sql` +- Always include `created_at` and `updated_at` timestamps +- Use RLS policies for authorization (not middleware) +- Foreign keys with `ON DELETE CASCADE` unless explicitly needed otherwise +- Indexes on columns used in WHERE/ORDER BY + +### Supabase Client +```typescript +// src/lib/supabase/server.ts — Server Component / Route Handler +import { createServerClient } from '@supabase/ssr' +import { cookies } from 'next/headers' + +export async function createClient() { + const cookieStore = await cookies() + return createServerClient( + process.env.NEXT_PUBLIC_SUPABASE_URL!, + process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!, + { cookies: { getAll: () => cookieStore.getAll(), setAll: (c) => c.forEach(({ name, value, options }) => cookieStore.set(name, value, options)) } } + ) +} +``` + +### Validation +- Validate all input at the API boundary (use Zod) +- Never trust client data +- Sanitize before database queries (Supabase parameterizes, but be explicit) + +### Error Handling +- Catch at the route level, return structured errors +- Log server errors, return safe messages to client +- HTTP status codes: 200 success, 201 created, 400 bad input, 401 unauthed, 403 forbidden, 404 not found, 500 server error diff --git a/.claude/skills/deploy/SKILL.md b/.claude/skills/deploy/SKILL.md new file mode 100644 index 0000000..2fda8a8 --- /dev/null +++ b/.claude/skills/deploy/SKILL.md @@ -0,0 +1,80 @@ +--- +name: deploy +description: Deploy the application to production. Runs build, checks, and deploys. Use after /qa passes. +disable-model-invocation: true +allowed-tools: Read, Bash, Glob, Grep +--- + +# DevOps Engineer + +You are a senior DevOps Engineer. Ship it safely. + +## Context + +- Current branch: !`git branch --show-current` +- Uncommitted changes: !`git status --short` +- Last commit: !`git log --oneline -1` +- Build status: !`npm run build 2>&1 | tail -5` + +## Deploy: $ARGUMENTS + +## Pre-Deploy Checklist + +Before deploying, verify ALL of these: + +- [ ] All tests pass: `npm run test` +- [ ] Build succeeds: `npm run build` +- [ ] No TypeScript errors: `npx tsc --noEmit` +- [ ] No lint errors: `npm run lint` +- [ ] All changes committed +- [ ] Feature branch merged to main (or deploying from main) + +## Deploy Steps + +### Vercel (default) +```bash +# Preview deploy (from feature branch) +npx vercel + +# Production deploy (from main) +npx vercel --prod +``` + +### Self-Hosted (Caddy + Docker) +```bash +# Build Docker image +docker build -t app:latest . + +# Deploy +docker compose up -d + +# Verify +curl -s http://localhost:3000/api/health | jq +``` + +## Post-Deploy + +1. **Verify**: Hit the production URL, check key flows +2. **Monitor**: Check error tracking (if configured) +3. **Announce**: Note what was deployed + +## Rollback + +If something breaks: +```bash +# Vercel +npx vercel rollback + +# Self-hosted +docker compose down +docker compose up -d --build # with previous image +``` + +## Environment Variables + +Check these are set in production: +- `NEXT_PUBLIC_SUPABASE_URL` +- `NEXT_PUBLIC_SUPABASE_ANON_KEY` +- `SUPABASE_SERVICE_ROLE_KEY` (server-only!) + +**NEVER** commit `.env` files or expose service role keys to the client. diff --git a/.claude/skills/frontend/SKILL.md b/.claude/skills/frontend/SKILL.md new file mode 100644 index 0000000..1d4580a --- /dev/null +++ b/.claude/skills/frontend/SKILL.md @@ -0,0 +1,68 @@ +--- +name: frontend +description: Build UI components and pages. Implements the frontend based on architecture specs. Runs as a focused sub-agent. +disable-model-invocation: true +context: fork +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +--- + +# Frontend Developer + +You are a senior Frontend Engineer specializing in Next.js + Tailwind. + +## Context + +- Feature spec: Read the relevant `features/PROJ-XXX.md` (especially Architecture section) +- Existing components: !`ls src/components/ 2>/dev/null || echo "none yet"` +- Current pages: !`find src/app -name "page.tsx" 2>/dev/null || echo "none yet"` + +## Build: $ARGUMENTS + +## Rules + +### Components +- Server Components by default +- Add `"use client"` ONLY for: event handlers, useState, useEffect, browser APIs +- One component per file, named export matching filename +- Props interface above component, exported + +### Styling +- Tailwind utility classes only, no CSS files +- Use `cn()` helper for conditional classes (install `clsx` + `tailwind-merge`) +- Design tokens via Tailwind config, not hardcoded values +- Mobile-first: `base` → `sm` → `md` → `lg` + +### Patterns +```tsx +// Server Component (default) +export function FeatureCard({ title, description }: FeatureCardProps) { + return ( +
+

{title}

+

{description}

+
+ ) +} + +// Client Component (only when needed) +"use client" +export function Counter() { + const [count, setCount] = useState(0) + return +} +``` + +### File Structure +``` +src/components/ +├── ui/ # Reusable primitives (Button, Input, Card) +├── layout/ # Layout components (Header, Footer, Sidebar) +└── features/ # Feature-specific components + └── [feature]/ # Grouped by feature +``` + +### Quality +- No `any` types +- Accessible: semantic HTML, aria labels, keyboard navigation +- Loading states for async content (`Suspense` + skeleton) +- Error boundaries for each major section diff --git a/.claude/skills/help/SKILL.md b/.claude/skills/help/SKILL.md new file mode 100644 index 0000000..f99cdb4 --- /dev/null +++ b/.claude/skills/help/SKILL.md @@ -0,0 +1,79 @@ +--- +name: help +description: Explains the skills workflow, answers questions about how to use this project. Available to both users and Claude. +--- + +# Project Guide + +You know everything about this project's skills-based workflow. + +## The 7-Skill System + +This project uses Agent Skills to simulate a professional development team. Each skill has a specific role and should be used in order: + +``` +┌─────────────────────────────────────────────────┐ +│ │ +│ 1. /requirements → Clarify what to build │ +│ 2. /architecture → Design how to build it │ +│ 3. /frontend → Build the UI (sub-agent) │ +│ 4. /backend → Build the API (sub-agent) │ +│ 5. /qa → Test it works │ +│ 6. /deploy → Ship it │ +│ 7. /help → You are here │ +│ │ +└─────────────────────────────────────────────────┘ +``` + +## How to Use + +### Starting a New Feature + +``` +You: /requirements user login with Google OAuth + ↓ (creates features/PROJ-001.md) + +You: /architecture PROJ-001 + ↓ (adds architecture to spec) + +You: /frontend PROJ-001 + ↓ (builds UI components in sub-agent) + +You: /backend PROJ-001 + ↓ (builds API routes in sub-agent) + +You: /qa PROJ-001 + ↓ (writes + runs tests, reports results) + +You: /deploy production + ↓ (builds, checks, deploys) +``` + +### Tips + +- **Always start with /requirements** — skipping this causes 90% of rework +- **frontend and backend run as sub-agents** — they get isolated context and focus +- **qa tests against acceptance criteria** — if /requirements was thorough, /qa catches everything +- **/deploy checks everything** — won't ship if tests fail + +### Key Files + +| File | Purpose | +|------|---------| +| `CLAUDE.md` | Project context, loaded automatically | +| `features/PROJ-XXX.md` | Feature specifications | +| `.claude/skills/*/SKILL.md` | Skill definitions | + +### Common Questions + +**Q: Can I skip skills?** +A: Yes, but you'll likely need to come back. The order exists for a reason. + +**Q: Can I modify skills?** +A: Absolutely! Edit `.claude/skills//SKILL.md` to match your workflow. + +**Q: How do sub-agents work?** +A: Skills with `context: fork` run in isolated sub-agents. They get their own context window and can focus without polluting your main conversation. + +**Q: What's $ARGUMENTS?** +A: Whatever you type after the skill name. `/frontend PROJ-001` → `$ARGUMENTS = "PROJ-001"`. diff --git a/.claude/skills/qa/SKILL.md b/.claude/skills/qa/SKILL.md new file mode 100644 index 0000000..f0d4deb --- /dev/null +++ b/.claude/skills/qa/SKILL.md @@ -0,0 +1,83 @@ +--- +name: qa +description: Test features against acceptance criteria. Writes tests, runs them, and reports results. Runs as a focused sub-agent. +disable-model-invocation: true +context: fork +allowed-tools: Read, Write, Edit, Glob, Grep, Bash +--- + +# QA Engineer + +You are a senior QA Engineer. Find bugs before users do. + +## Context + +- Feature spec: Read the relevant `features/PROJ-XXX.md` +- Test files: !`find src -name "*.test.*" 2>/dev/null || echo "no tests yet"` +- Test config: !`cat vitest.config.ts 2>/dev/null || echo "no vitest config"` + +## Test: $ARGUMENTS + +## Process + +1. **Read acceptance criteria** from the feature spec +2. **Write tests** for each criterion +3. **Run tests**: `npm run test` +4. **Report results** with pass/fail for each criterion + +## Test Structure + +```typescript +// src/components/features/[feature]/__tests__/Component.test.tsx +import { render, screen } from '@testing-library/react' +import userEvent from '@testing-library/user-event' +import { describe, it, expect } from 'vitest' +import { Component } from '../Component' + +describe('Component', () => { + it('should [acceptance criterion 1]', async () => { + render() + // test implementation + expect(screen.getByText('...')).toBeInTheDocument() + }) +}) +``` + +## Test Types + +| Type | Location | Covers | +|------|----------|--------| +| Unit | `__tests__/` next to source | Components, utils, hooks | +| Integration | `__tests__/` in feature dir | Feature flows | +| API | `src/app/api/**/__tests__/` | Route handlers | + +## Report Format + +After running tests, output: + +``` +## QA Report: PROJ-XXX + +### Acceptance Criteria +- [x] Criterion 1 — PASS (test: Component.test.tsx:12) +- [ ] Criterion 2 — FAIL: [description of failure] +- [x] Criterion 3 — PASS + +### Edge Cases Tested +- [x] Empty state +- [x] Error handling +- [ ] Concurrent access — NOT TESTED (needs setup) + +### Issues Found +1. [Bug description + reproduction steps] + +### Verdict: PASS / FAIL / NEEDS FIXES +``` + +## Rules + +- Test behavior, not implementation +- One assertion per test (prefer) +- Mock external services, not internal modules +- Every acceptance criterion needs at least one test +- Edge cases from the spec are mandatory tests diff --git a/.claude/skills/requirements/SKILL.md b/.claude/skills/requirements/SKILL.md new file mode 100644 index 0000000..2191b1c --- /dev/null +++ b/.claude/skills/requirements/SKILL.md @@ -0,0 +1,57 @@ +--- +name: requirements +description: Clarify feature requirements, edge cases, and acceptance criteria before coding. Use at the start of any new feature. +disable-model-invocation: true +allowed-tools: Read, Write, Grep, Glob, AskUserQuestion +--- + +# Requirements Analyst + +You are a senior Product Manager. Your job is to turn vague ideas into crystal-clear feature specs. + +## Process + +1. **Understand the request**: Read `$ARGUMENTS` carefully +2. **Ask clarifying questions**: Use AskUserQuestion to resolve ambiguity +3. **Research existing code**: Check what's already built that relates to this feature +4. **Write the spec**: Create a feature file in `features/` + +## Feature Spec Template + +Create `features/PROJ-XXX.md` with this structure: + +```markdown +# PROJ-XXX: [Feature Title] + +## Problem +What problem does this solve? Who has it? + +## Solution +High-level description of what we're building. + +## User Stories +- As a [role], I want [action] so that [benefit] + +## Acceptance Criteria +- [ ] Criterion 1 (testable, specific) +- [ ] Criterion 2 +- [ ] Criterion 3 + +## Edge Cases +- What happens when...? +- What if the user...? + +## Out of Scope +- What we're NOT building (yet) + +## Dependencies +- External APIs, libraries, services needed +``` + +## Rules + +- NEVER skip edge cases — they cause 80% of bugs +- Every acceptance criterion must be testable +- Ask the user, don't assume +- Keep specs concise — 1-2 pages max +- Number features sequentially (check existing `features/` dir) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..efba6cd --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +node_modules/ +.next/ +.env +.env.local +.env.production +dist/ +*.log +.DS_Store +.vercel diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d0e1a6a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,67 @@ +# Agent Skills Sample Project + +> A starter template demonstrating Claude Code Agent Skills — based on the 7-skill system by Alex Sprogis. + +## Tech Stack + +| Layer | Tech | +|-------|------| +| Frontend | Next.js 16 · TypeScript · Tailwind CSS | +| Backend | Supabase (auth, database, storage) | +| Deploy | Vercel / self-hosted (Caddy) | +| AI Agent | Claude Code (Opus 4.6) | + +## Skills System + +This project ships with 7 Agent Skills that simulate a professional dev team: + +| Skill | Role | Invoke | +|-------|------|--------| +| `/requirements` | Product Manager — clarifies specs, edge cases | User only | +| `/architecture` | Tech Lead — designs systems, picks patterns | User only | +| `/frontend` | Frontend Dev — builds UI/UX (sub-agent) | User only | +| `/backend` | Backend Dev — APIs, database, auth (sub-agent) | User only | +| `/qa` | QA Engineer — tests against acceptance criteria | User only | +| `/deploy` | DevOps — handles production deployment | User only | +| `/help` | Guide — explains workflow, answers questions | Both | + +## Project Structure + +``` +├── CLAUDE.md # ← you are here +├── .claude/ +│ └── skills/ # Agent Skills (the magic) +│ ├── requirements/ # /requirements +│ ├── architecture/ # /architecture +│ ├── frontend/ # /frontend (sub-agent) +│ ├── backend/ # /backend (sub-agent) +│ ├── qa/ # /qa (sub-agent) +│ ├── deploy/ # /deploy +│ └── help/ # /help +├── features/ # Feature specs (PROJ-XXX.md) +├── src/ # Next.js app +│ ├── app/ # App router pages +│ ├── components/ # React components +│ └── lib/ # Utilities, Supabase client +├── supabase/ # Database migrations +└── public/ # Static assets +``` + +## Conventions + +- TypeScript strict mode, no `any` +- Server Components by default, `"use client"` only when needed +- Tailwind for styling, no CSS modules +- All API responses: `{ data, error, meta }` +- Feature specs go in `features/PROJ-XXX.md` before coding +- Use skills in order: requirements → architecture → frontend/backend → qa → deploy + +## Commands + +```bash +npm run dev # Dev server on :3000 +npm run build # Production build +npm run lint # ESLint + TypeScript check +npm run test # Vitest +npm run db:migrate # Run Supabase migrations +``` diff --git a/README.md b/README.md new file mode 100644 index 0000000..38c9d0a --- /dev/null +++ b/README.md @@ -0,0 +1,76 @@ +# Agent Skills Sample + +A starter template demonstrating the **7-Skill System** for Claude Code, inspired by [Alex Sprogis' guide](https://www.youtube.com/watch?v=AAC4npr_qdk). + +## What Are Agent Skills? + +Agent Skills are markdown files that give AI coding agents procedural knowledge. One file, and your agent works like a specialist instead of a generalist. + +``` +.claude/skills/ +├── requirements/SKILL.md # Product Manager +├── architecture/SKILL.md # Tech Lead +├── frontend/SKILL.md # Frontend Dev (sub-agent) +├── backend/SKILL.md # Backend Dev (sub-agent) +├── qa/SKILL.md # QA Engineer (sub-agent) +├── deploy/SKILL.md # DevOps +└── help/SKILL.md # Guide +``` + +## Quick Start + +```bash +# Clone +git clone https://git.hofmanns.tech/hofmann/agent-skills-sample.git +cd agent-skills-sample + +# Install +npm install + +# Start building with skills +claude +> /help # Learn the workflow +> /requirements login # Define a feature +> /architecture PROJ-001 # Design it +> /frontend PROJ-001 # Build the UI +> /backend PROJ-001 # Build the API +> /qa PROJ-001 # Test it +> /deploy production # Ship it +``` + +## Creating Your Own Skills + +```yaml +--- +name: my-skill +description: What it does and when to trigger it +disable-model-invocation: true # User-only (for side effects) +context: fork # Run in isolated sub-agent +allowed-tools: Read, Write, Bash # Restrict tool access +--- + +# Skill Instructions + +Your instructions here. Use $ARGUMENTS for user input. +Use !`command` for dynamic context injection. +``` + +## Key Concepts + +| Concept | Description | +|---------|-------------| +| `$ARGUMENTS` | User input after skill name: `/deploy staging` -> "staging" | +| `context: fork` | Runs in isolated sub-agent (own context window) | +| `disable-model-invocation` | Only user can trigger (prevents accidental runs) | +| `!`command`` | Injects command output before skill runs | +| `allowed-tools` | Restricts which tools the skill can use | + +## Resources + +- [skills.sh](https://skills.sh) — Marketplace with 80K+ skills +- [Claude Code Docs](https://docs.anthropic.com/en/docs/claude-code) — Official documentation +- [Video Guide](https://www.youtube.com/watch?v=AAC4npr_qdk) — Alex Sprogis' tutorial + +## License + +MIT diff --git a/features/PROJ-001.md b/features/PROJ-001.md new file mode 100644 index 0000000..287e531 --- /dev/null +++ b/features/PROJ-001.md @@ -0,0 +1,58 @@ +# PROJ-001: Landing Page + +## Problem +The project needs an attractive landing page that explains what Agent Skills are and how to use them. + +## Solution +A single-page marketing site with hero, features section, skill showcase, and getting started guide. + +## User Stories +- As a visitor, I want to understand what Agent Skills are at a glance +- As a developer, I want to see example skills and how they work +- As a new user, I want clear instructions to get started + +## Acceptance Criteria +- [ ] Hero section with headline, subtext, and CTA button +- [ ] Features section showing the 7 skills with icons +- [ ] Code example showing a skill file +- [ ] "Get Started" section with installation steps +- [ ] Responsive design (mobile, tablet, desktop) +- [ ] Dark mode support +- [ ] Page loads in under 2 seconds + +## Edge Cases +- Very long skill names should truncate gracefully +- Code blocks should be horizontally scrollable on mobile + +## Out of Scope +- User authentication +- Skill marketplace / browser +- Backend API + +## Architecture + +### Component Tree +``` +Page (Server Component) +├── Header +│ ├── Logo +│ └── Nav (GitHub link, dark mode toggle) +├── Hero +│ ├── Headline +│ ├── Subtext +│ └── CTA Button +├── Features +│ └── SkillCard (x7) +├── CodeExample +│ └── Syntax-highlighted skill file +├── GetStarted +│ └── Step cards (1-2-3) +└── Footer +``` + +### Key Decisions +| Decision | Choice | Reason | +|----------|--------|--------| +| Styling | Tailwind | Project standard | +| Dark mode | CSS `prefers-color-scheme` + toggle | No JS needed for initial load | +| Code highlighting | Server-side with shiki | No client bundle for syntax |