Handbook Skill - Read Before You Code

Purpose

This skill instructs Claude to read the project's handbook BEFORE implementing any code in an Amplify Gen 2 project.

The handbook contains proven, production-tested patterns for:

• Authentication (Google OAuth, Cognito, security)
• Data modeling (DynamoDB, GraphQL schemas, TTL)
• Lambda functions (scheduled, triggers, DynamoDB access)
• Webhooks (Slack, Stripe, GitHub)
• Frontend patterns (MUI, design systems)
• Troubleshooting and debugging

Core Principle: No Hallucinations, Only Handbook Patterns

When a user asks you to implement anything in an Amplify Gen 2 project:

1. STOP - Don't immediately write code
2. CHECK - Does resources/handbook/ exist in the current project?
3. LEARN - Read the handbook to understand the correct patterns
4. THEN CODE - Implement using handbook patterns, not generic approaches

The Workflow

Step 1: Check for Handbook

# Is there a handbook in this project?
ls resources/handbook/README.md

If it exists, you have access to the complete Amplify Gen 2 handbook.

Step 2: Start with Table of Contents

ALWAYS begin here:

• Read resources/handbook/README.md
• This contains the full table of contents
• Understand what sections exist (Auth, Functions, Data, Webhooks, etc.)
• Treat it like a textbook - respect the organization

Step 3: Navigate to Relevant Section

Based on what the user wants to build:

Step 4: Learn the Pattern

• Read the guide completely
• Understand the Amplify Gen 2 way to do it
• Note any security considerations
• Check for common pitfalls
• Look at examples if available

Step 5: Implement the Code

NOW you write the code, following the handbook patterns you just learned.

Critical Rules (Always Follow)

The "No CDK" Rule

• ❌ NEVER import from aws-cdk-lib for standard tasks
• ✅ ONLY use: defineAuth, defineData, defineFunction, defineStorage
• See: resources/handbook/AI-DEVELOPMENT-GUIDELINES.md

The "No API Gateway" Rule

• ❌ NEVER create API Gateway resources
• ✅ Internal operations: GraphQL custom mutations
• ✅ External webhooks: Next.js API routes
• See: resources/handbook/NO-API-GATEWAY.md

The "Learn First" Rule

• ❌ Don't write code based on generic knowledge or hallucinations
• ✅ Read the handbook section first, THEN code
• This prevents using wrong patterns or outdated approaches

Navigation Aid

The handbook README.md has a comprehensive "I Need To..." table that maps user needs to specific documentation. Use it as your guide.

What This Prevents

❌ Using outdated Amplify Gen 1 patterns ❌ Importing unnecessary CDK libraries ❌ Creating API Gateway resources (not needed) ❌ Manually writing IAM policies (handled by Amplify) ❌ Making up APIs that don't exist ❌ Generic Lambda code that doesn't integrate properly

✅ Using correct Amplify Gen 2 abstractions ✅ Following proven, production-tested patterns ✅ Writing code that works first try ✅ Proper integration with Amplify resources

Remember

Every time you're about to write Amplify Gen 2 code:

1. Check for resources/handbook/
2. Read the relevant section
3. Learn the pattern
4. Then code

This ensures you implement things the correct way, following the template's established patterns and best practices.

Updating the Handbook

To get latest handbook: Use the handbook-sync skill

To contribute new patterns: Use the handbook-updater skill