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