Project Guidelines Skill (Example)

This is an example of a project-specific skill. Use this as a template for your own projects.

Based on a real production application: Zenith - AI-powered customer discovery platform.

When to Use

Reference this skill when working on the specific project it's designed for. Project skills contain:

Architecture overview File structure Code patterns Testing requirements Deployment workflow Architecture Overview

Tech Stack:

Frontend: Next.js 15 (App Router), TypeScript, React Backend: FastAPI (Python), Pydantic models Database: Supabase (PostgreSQL) AI: Claude API with tool calling and structured output Deployment: Google Cloud Run Testing: Playwright (E2E), pytest (backend), React Testing Library

Services:

┌─────────────────────────────────────────────────────────────┐ │ Frontend │ │ Next.js 15 + TypeScript + TailwindCSS │ │ Deployed: Vercel / Cloud Run │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend │ │ FastAPI + Python 3.11 + Pydantic │ │ Deployed: Cloud Run │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Supabase │ │ Claude │ │ Redis │ │ Database │ │ API │ │ Cache │ └──────────┘ └──────────┘ └──────────┘

File Structure project/ ├── frontend/ │ └── src/ │ ├── app/ # Next.js app router pages │ │ ├── api/ # API routes │ │ ├── (auth)/ # Auth-protected routes │ │ └── workspace/ # Main app workspace │ ├── components/ # React components │ │ ├── ui/ # Base UI components │ │ ├── forms/ # Form components │ │ └── layouts/ # Layout components │ ├── hooks/ # Custom React hooks │ ├── lib/ # Utilities │ ├── types/ # TypeScript definitions │ └── config/ # Configuration │ ├── backend/ │ ├── routers/ # FastAPI route handlers │ ├── models.py # Pydantic models │ ├── main.py # FastAPI app entry │ ├── auth_system.py # Authentication │ ├── database.py # Database operations │ ├── services/ # Business logic │ └── tests/ # pytest tests │ ├── deploy/ # Deployment configs ├── docs/ # Documentation └── scripts/ # Utility scripts

Code Patterns API Response Format (FastAPI) from pydantic import BaseModel from typing import Generic, TypeVar, Optional

T = TypeVar('T')

class ApiResponse(BaseModel, Generic[T]): success: bool data: Optional[T] = None error: Optional[str] = None

@classmethod
def ok(cls, data: T) -> "ApiResponse[T]":
    return cls(success=True, data=data)

@classmethod
def fail(cls, error: str) -> "ApiResponse[T]":
    return cls(success=False, error=error)

Frontend API Calls (TypeScript) interface ApiResponse { success: boolean data?: T error?: string }

async function fetchApi( endpoint: string, options?: RequestInit ): Promise> { try { const response = await fetch(/api${endpoint}, { ...options, headers: { 'Content-Type': 'application/json', ...options?.headers, }, })

if (!response.ok) {
  return { success: false, error: `HTTP ${response.status}` }
}

return await response.json()

} catch (error) { return { success: false, error: String(error) } } }

Claude AI Integration (Structured Output) from anthropic import Anthropic from pydantic import BaseModel

class AnalysisResult(BaseModel): summary: str key_points: list[str] confidence: float

async def analyze_with_claude(content: str) -> AnalysisResult: client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": content}],
    tools=[{
        "name": "provide_analysis",
        "description": "Provide structured analysis",
        "input_schema": AnalysisResult.model_json_schema()
    }],
    tool_choice={"type": "tool", "name": "provide_analysis"}
)

# Extract tool use result
tool_use = next(
    block for block in response.content
    if block.type == "tool_use"
)

return AnalysisResult(**tool_use.input)

Custom Hooks (React) import { useState, useCallback } from 'react'

interface UseApiState { data: T | null loading: boolean error: string | null }

export function useApi( fetchFn: () => Promise> ) { const [state, setState] = useState>({ data: null, loading: false, error: null, })

const execute = useCallback(async () => { setState(prev => ({ ...prev, loading: true, error: null }))

const result = await fetchFn()

if (result.success) {
  setState({ data: result.data!, loading: false, error: null })
} else {
  setState({ data: null, loading: false, error: result.error! })
}

}, [fetchFn])

return { ...state, execute } }

Testing Requirements Backend (pytest)

Run all tests

poetry run pytest tests/

Run with coverage

poetry run pytest tests/ --cov=. --cov-report=html

Run specific test file

poetry run pytest tests/test_auth.py -v

Test structure:

import pytest from httpx import AsyncClient from main import app

@pytest.fixture async def client(): async with AsyncClient(app=app, base_url="http://test") as ac: yield ac

@pytest.mark.asyncio async def test_health_check(client: AsyncClient): response = await client.get("/health") assert response.status_code == 200 assert response.json()["status"] == "healthy"

Frontend (React Testing Library)

Run tests

npm run test

Run with coverage

npm run test -- --coverage

Run E2E tests

npm run test:e2e

Test structure:

import { render, screen, fireEvent } from '@testing-library/react' import { WorkspacePanel } from './WorkspacePanel'

describe('WorkspacePanel', () => { it('renders workspace correctly', () => { render() expect(screen.getByRole('main')).toBeInTheDocument() })

it('handles session creation', async () => { render() fireEvent.click(screen.getByText('New Session')) expect(await screen.findByText('Session created')).toBeInTheDocument() }) })

Deployment Workflow Pre-Deployment Checklist All tests passing locally npm run build succeeds (frontend) poetry run pytest passes (backend) No hardcoded secrets Environment variables documented Database migrations ready Deployment Commands

Build and deploy frontend

cd frontend && npm run build gcloud run deploy frontend --source .

Build and deploy backend

cd backend gcloud run deploy backend --source .

Environment Variables

Frontend (.env.local)

NEXT_PUBLIC_API_URL=https://api.example.com NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

Backend (.env)

DATABASE_URL=postgresql://... ANTHROPIC_API_KEY=sk-ant-... SUPABASE_URL=https://xxx.supabase.co SUPABASE_KEY=eyJ...

Critical Rules No emojis in code, comments, or documentation Immutability - never mutate objects or arrays TDD - write tests before implementation 80% coverage minimum Many small files - 200-400 lines typical, 800 max No console.log in production code Proper error handling with try/catch Input validation with Pydantic/Zod Related Skills coding-standards.md - General coding best practices backend-patterns.md - API and database patterns frontend-patterns.md - React and Next.js patterns tdd-workflow/ - Test-driven development methodology