Claude Code Skills vs Prompts: Why Pre-Built Workflows Produce Better Code

#productivity #ai #typescript #claudeai

Claude Code Skills Are Different from Prompts

A prompt is a question or instruction you type once.
A skill is a pre-built workflow stored in a file that Claude reads before acting -- giving it deep, structured context about exactly what to do.

The difference in output quality is significant.

How Claude Code Skills Work

1. You type /auth in Claude Code
2. Claude reads the skill file (structured instructions)
3. Claude asks you 3-5 targeted questions
4. Claude generates a complete, correct implementation
   tailored to your exact project setup

vs. without a skill:
1. You type 'implement auth'
2. Claude guesses your stack
3. Claude generates generic boilerplate
4. You spend 45 minutes adapting it

The /auth Skill

# /auth skill (excerpt)

## What this skill does
Implements complete authentication using NextAuth v5 for Next.js 14 App Router.

## Questions to ask before generating
1. Which providers do you need? (Google, GitHub, email, credentials)
2. Do you need role-based access? (admin/user/moderator)
3. Do you have a database configured? (Prisma/Drizzle/none)
4. Do you want session callbacks? (custom JWT claims)
5. What routes need protection?

## What to generate
- app/api/auth/[...nextauth]/route.ts
- lib/auth.ts (authOptions, helpers)
- middleware.ts (route protection)
- types/next-auth.d.ts (session augmentation)
- Prisma schema additions (User, Account, Session)
- Login page component

## Common mistakes to avoid
- Using getSession() instead of getServerSession() in Server Components
- Missing the 'use client' boundary on SignIn/SignOut buttons
- Forgetting to add NEXTAUTH_SECRET and NEXTAUTH_URL to .env

The /pay Skill

# /pay skill (excerpt)

## Questions to ask
1. Subscriptions, one-time payments, or both?
2. If subscriptions: which plans? (free/pro/enterprise)
3. Do you need a customer portal (self-serve billing)?
4. Is auth already set up?

## What to generate
- lib/stripe.ts (client initialization)
- app/api/checkout/route.ts (create checkout session)
- app/api/webhooks/stripe/route.ts (subscription events)
- app/api/billing/portal/route.ts (customer portal)
- Prisma schema: Subscription model
- lib/subscription.ts (access checking helpers)
- Dashboard billing page

## Patterns to use
- Verify webhook signatures with raw body (req.text(), not req.json())
- Upsert subscriptions on every event (idempotent)
- Store stripeCustomerId on User, not on Subscription

The /deploy Skill

# /deploy skill (excerpt)

## Questions to ask
1. Target platform? (Vercel, Railway, Docker, AWS)
2. Do you need a CI/CD pipeline?
3. Database migrations on deploy?
4. Environment variable list (what to configure)

## What to generate
- .github/workflows/deploy.yml
- vercel.json (or Dockerfile)
- scripts/smoke-test.sh
- .env.example (all required variables)

Why Skills Beat Raw Prompts for Repeated Tasks

Without skill:
  'Add Stripe to my app'
  -> Claude doesn't know your auth setup
  -> Claude doesn't know your DB schema
  -> Claude guesses and generates wrong patterns
  -> You fix for 2 hours

With /pay skill:
  Skill reads your existing lib/auth.ts
  Skill checks your Prisma schema
  Skill asks 4 targeted questions
  Generates exactly what your project needs
  Works first time

Ship Fast Skill Pack: All 10 Skills

/auth    -- NextAuth v5, Google + GitHub, Prisma adapter
/pay     -- Stripe subscriptions, webhooks, portal
/deploy  -- Vercel/Docker CI/CD, migrations, env setup
/test    -- Jest tests for any function or route
/api     -- REST endpoint with auth, validation, error handling
/db      -- Prisma schema from plain English description
/review  -- Security and performance code review
/refactor -- Safe refactoring with test generation first
/docs    -- JSDoc generation for exported functions
/debug   -- Systematic debugging loop