<< All versions
Skill v1.0.1
currentAutomated scan100/100majiayu000/claude-skill-registry/project-guidelines-example-flag3-dotfiles
3 files
──Details
PublishedMay 25, 2026 at 03:23 PM
Content Hashsha256:d8156f2df70d407d...
Git SHA2c97748f6498
Bump Typepatch
──Files
Files (1 file, 9.5 KB)
SKILL.md9.5 KBactive
SKILL.md · 349 lines · 9.5 KB
version: "1.0.1"
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)
python
from pydantic import BaseModelfrom typing import Generic, TypeVar, OptionalT = TypeVar('T')class ApiResponse(BaseModel, Generic[T]):success: booldata: Optional[T] = Noneerror: Optional[str] = None@classmethoddef ok(cls, data: T) -> "ApiResponse[T]":return cls(success=True, data=data)@classmethoddef fail(cls, error: str) -> "ApiResponse[T]":return cls(success=False, error=error)
Frontend API Calls (TypeScript)
typescript
interface ApiResponse<T> {success: booleandata?: Terror?: 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)
python
from anthropic import Anthropicfrom pydantic import BaseModelclass AnalysisResult(BaseModel):summary: strkey_points: list[str]confidence: floatasync 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 resulttool_use = next(block for block in response.contentif block.type == "tool_use")return AnalysisResult(**tool_use.input)
Custom Hooks (React)
typescript
import { useState, useCallback } from 'react'interface UseApiState<T> {data: T | nullloading: booleanerror: 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)
bash
# Run all testspoetry run pytest tests/# Run with coveragepoetry run pytest tests/ --cov=. --cov-report=html# Run specific test filepoetry run pytest tests/test_auth.py -v
Test structure:
python
import pytestfrom httpx import AsyncClientfrom main import app@pytest.fixtureasync def client():async with AsyncClient(app=app, base_url="http://test") as ac:yield ac@pytest.mark.asyncioasync def test_health_check(client: AsyncClient):response = await client.get("/health")assert response.status_code == 200assert response.json()["status"] == "healthy"
Frontend (React Testing Library)
bash
# Run testsnpm run test# Run with coveragenpm run test -- --coverage# Run E2E testsnpm run test:e2e
Test structure:
typescript
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 buildsucceeds (frontend) - [ ]
poetry run pytestpasses (backend) - [ ] No hardcoded secrets
- [ ] Environment variables documented
- [ ] Database migrations ready
Deployment Commands
bash
# Build and deploy frontendcd frontend && npm run buildgcloud run deploy frontend --source .# Build and deploy backendcd backendgcloud run deploy backend --source .
Environment Variables
bash
# Frontend (.env.local)NEXT_PUBLIC_API_URL=https://api.example.comNEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.coNEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...# Backend (.env)DATABASE_URL=postgresql://...ANTHROPIC_API_KEY=sk-ant-...SUPABASE_URL=https://xxx.supabase.coSUPABASE_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 practicesbackend-patterns.md- API and database patternsfrontend-patterns.md- React and Next.js patternstdd-workflow/- Test-driven development methodology