skills/agent-skills-sample
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Initial commit: 7-Skill System for Claude Code

Browse source 
Starter template with requirements, architecture, frontend, backend,
qa, deploy, and help skills — inspired by Alex Sprogis' guide.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Hofmann 2026-03-01 19:12:09 +01:00
commit 1958f8e17e
11 changed files with 728 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
.claude/skills/architecture/SKILL.md Normal file
View file

@ -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

84
.claude/skills/backend/SKILL.md Normal file
View file

@ -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<T> = {
data: T | null
error: string | null
meta: Record<string, unknown> | 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

80
.claude/skills/deploy/SKILL.md Normal file
View file

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

68
.claude/skills/frontend/SKILL.md Normal file
View file

@ -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 (
<div className="rounded-lg border p-4">
<h3 className="text-lg font-semibold">{title}</h3>
<p className="text-muted-foreground">{description}</p>
</div>
)
}
// Client Component (only when needed)
"use client"
export function Counter() {
const [count, setCount] = useState(0)
return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}
```
### 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

79
.claude/skills/help/SKILL.md Normal file
View file

@ -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/<name>/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"`.

83
.claude/skills/qa/SKILL.md Normal file
View file

@ -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(<Component />)
// 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

57
.claude/skills/requirements/SKILL.md Normal file
View file

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

9
.gitignore vendored Normal file
View file

@ -0,0 +1,9 @@
node_modules/
.next/
.env
.env.local
.env.production
dist/
*.log
.DS_Store
.vercel

67
CLAUDE.md Normal file
View file

@ -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
```

76
README.md Normal file
View file

@ -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

58
features/PROJ-001.md Normal file
View file

@ -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 |