Development

Claude Code Skills

Claude Code Skills Guide

This boilerplate includes built-in Claude Code Skills that help Claude understand your project's patterns and conventions. This guide explains how Skills work, how to use them, and how to customize them.

What Are Skills?
Included Skills
How to Use Skills
Creating New Skills
Editing Existing Skills
Skill File Format
Best Practices
Troubleshooting

What Are Skills?

Skills are markdown files that teach Claude Code how to do specific tasks in your project. They contain:

Instructions for completing common tasks
Code examples that match your project's patterns
Checklists to ensure nothing is missed

Skills are automatically activated when your request matches the skill's description. You don't need to explicitly invoke them.

How Skills Work

Discovery: When Claude Code starts, it loads skill names and descriptions
Matching: When you make a request, Claude checks if any skill matches
Activation: If a match is found, Claude reads the full skill instructions
Execution: Claude follows the skill's guidance to complete your task

Included Skills

This boilerplate includes 6 skills in .claude/skills/:

add-page

Triggers: "add a page", "create a page", "new route"

Creates new pages with:

Proper file location (marketing vs dashboard)
SEO metadata
Navigation updates
Sitemap inclusion

add-blog-post

Triggers: "add a blog post", "write a post", "new article"

Creates MDX blog posts with:

Correct frontmatter format
Author and date configuration
Tags and images
Draft/published status

add-email-template

Triggers: "add email", "new email template", "create notification"

Creates React Email templates with:

Proper component structure
Inline styles for email clients
Integration with Resend

modify-pricing

Triggers: "change pricing", "update plans", "add feature to plan"

Updates pricing configuration:

Plan features and descriptions
Monthly/yearly prices
Stripe Price IDs
Environment variables

add-migration

Triggers: "add migration", "database change", "new table", "add column"

Creates Supabase migrations with:

Proper file naming
RLS policies
Index creation
TypeScript type updates

add-component

Triggers: "add component", "create component", "new component"

Creates React components following:

shadcn/ui patterns
Server vs Client component rules
TypeScript interfaces
Project file organization

How to Use Skills

Automatic Activation

Simply describe what you want to do naturally:

"Add a new blog post about our product launch"

Claude will automatically use the add-blog-post skill.

"Create a new dashboard page for user analytics"

Claude will use the add-page skill with dashboard-specific instructions.

Checking Available Skills

Ask Claude:

"What skills are available?"

Or:

"What can you help me with in this project?"

Explicit Invocation

You can also explicitly request a skill:

"Use the add-migration skill to create a new users table"

Creating New Skills

Step 1: Create the Directory

mkdir -p .claude/skills/your-skill-name

Use lowercase letters, numbers, and hyphens only.

Step 2: Create SKILL.md

Create .claude/skills/your-skill-name/SKILL.md:

---
name: your-skill-name
description: Brief description of what this skill does. Include keywords users might say when they need this skill.
allowed-tools: Read, Write, Edit, Glob, Grep
---

# Skill Title

## Instructions

Step-by-step instructions for Claude to follow.

### Step 1: First Thing

Explain what to do first.

### Step 2: Second Thing

Explain what to do next.

## Examples

Show code examples:

```typescript
// Example code here

Checklist

[ ] First thing to verify
[ ] Second thing to verify


### Step 3: Test the Skill

Start a new Claude Code session and try triggering your skill:

"Help me with [task matching your description]"


### Example: Custom Deployment Skill

```markdown
---
name: deploy-to-vercel
description: Deploy the application to Vercel. Use when deploying, pushing to production, or when the user says "deploy", "ship it", or "go live".
allowed-tools: Bash, Read
---

# Deploying to Vercel

## Prerequisites

Before deploying, ensure:
1. All changes are committed
2. Tests pass locally
3. Environment variables are configured in Vercel

## Instructions

### Step 1: Verify Build

Run the build locally to catch errors:

```bash
npm run build

Step 2: Check Git Status

Ensure all changes are committed:

git status

Step 3: Deploy

Push to trigger deployment:

git push origin main

Or deploy directly with Vercel CLI:

vercel --prod

Post-Deployment

[ ] Verify the deployment at your production URL
[ ] Test critical flows (auth, payments)
[ ] Check for console errors
[ ] Monitor error tracking (if configured)


---

## Editing Existing Skills

### Locating Skills

All skills are in `.claude/skills/`:

.claude/skills/ ├── add-page/ │ └── SKILL.md ├── add-blog-post/ │ └── SKILL.md ├── add-email-template/ │ └── SKILL.md ├── modify-pricing/ │ └── SKILL.md ├── add-migration/ │ └── SKILL.md └── add-component/ └── SKILL.md


### Common Edits

#### Change Trigger Words

Edit the `description` in the frontmatter:

```yaml
---
name: add-page
description: Create a new page. Use when adding routes, creating pages, building new screens, or when the user says "add a page", "new page", "create route", "new screen".
---

Update Code Examples

Replace code examples to match your project's evolving patterns:

### Creating a Page

```tsx
// Update this example when your patterns change
export default function NewPage() {
  return <YourNewPattern />;
}


#### Add New Steps

Insert additional instructions:

```markdown
### Step 4: Add Analytics (New!)

After creating the page, add analytics tracking:

```tsx
import { trackPageView } from '@/lib/analytics';

useEffect(() => {
  trackPageView('page-name');
}, []);


#### Restrict Tools

Limit what tools the skill can use:

```yaml
---
name: read-only-skill
description: Analyze code without making changes
allowed-tools: Read, Grep, Glob
---

Skill File Format

Required Frontmatter

---
name: skill-name          # Required: lowercase, hyphens, max 64 chars
description: Description  # Required: max 1024 chars, include trigger words
---

Optional Frontmatter

---
name: skill-name
description: Description
allowed-tools: Read, Write, Edit    # Restrict available tools
model: claude-sonnet-4-20250514     # Use specific model
context: fork                        # Run in isolated context
user-invocable: false               # Hide from user (Claude can still use)
---

Markdown Body

After the frontmatter, write instructions in Markdown:

Use # headings to organize sections
Use code blocks with language hints
Use tables for reference information
Use checklists for verification steps

Multi-File Skills

For complex skills, reference additional files:

my-skill/
├── SKILL.md           # Main instructions
├── examples.md        # Detailed examples
├── reference.md       # API reference
└── templates/
    └── component.tsx  # Template files

Reference them in SKILL.md:

For more examples, see [examples.md](examples.md).

Use this template as a starting point:

```tsx
// See templates/component.tsx


---

## Best Practices

### 1. Write Clear Descriptions

Include keywords users naturally say:

```yaml
# Good
description: Create database migrations for Supabase. Use when adding tables, columns, indexes, or when the user says "database change", "new table", "add field", "migration".

# Bad
description: Database stuff.

2. Keep Skills Focused

One skill = one task. Don't combine unrelated operations.

# Good
add-page/          # Just for pages
add-component/     # Just for components

# Bad
add-stuff/         # Too broad

3. Include Checklists

Help ensure completeness:

## Checklist

- [ ] Created file in correct location
- [ ] Added TypeScript types
- [ ] Updated navigation
- [ ] Added to sitemap

4. Show Real Examples

Use examples from your actual codebase:

## Example

Here's how we created the Contact page:

```tsx
// /app/contact/page.tsx
// [actual code from your project]


### 5. Keep Instructions Current

When you change project patterns, update relevant skills.

### 6. Restrict Tools When Appropriate

For read-only analysis skills:

```yaml
allowed-tools: Read, Grep, Glob

For skills that should never run commands:

allowed-tools: Read, Write, Edit

Troubleshooting

Skill Not Triggering

Problem: Claude doesn't use your skill when expected.

Solutions:

Check the description includes relevant keywords
Make the description more specific
Verify YAML frontmatter syntax (no tabs, proper --- delimiters)

# Correct
---
name: my-skill
description: My description here
---

# Wrong (missing closing ---)
---
name: my-skill
description: My description here

# Wrong (tabs instead of spaces)
---
name:	my-skill
---

Multiple Skills Conflicting

Problem: Wrong skill activates.

Solution: Make descriptions more distinct:

# Before (too similar)
# Skill 1: "Helps with database operations"
# Skill 2: "Helps with data management"

# After (distinct)
# Skill 1: "Create Supabase SQL migrations for schema changes"
# Skill 2: "Query and analyze data using the Supabase client"

Skill Instructions Ignored

Problem: Claude doesn't follow all steps.