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<T> { success: boolean data?: T error?: string }

async function fetchApi<T>( endpoint: string, options?: RequestInit ): Promise<ApiResponse<T>> { 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<T> { data: T | null loading: boolean error: string | null }

export function useApi<T>( fetchFn: () => Promise<ApiResponse<T>> ) { const [state, setState] = useState<UseApiState<T>>({ 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(<WorkspacePanel />) expect(screen.getByRole('main')).toBeInTheDocument() })

it('handles session creation', async () => { render(<WorkspacePanel />) 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