Complete Guide: Building a Claude Code Frontend Design Skillset from Scratch

Transform Claude into your personal React and responsive design expert by building a professional frontend development skill module from scratch

Table of Contents

1. What are Claude Code Skills
2. How Skills Work
3. Prerequisites
4. Creating the Frontend Design Skill
5. Understanding SKILL.md
6. Creating Practical Templates
7. Activating and Using the Skill
8. Best Practices
9. Troubleshooting
10. Summary

What are Claude Code Skills

Skills are modular capability extensions in Claude Code that package domain-specific expertise into reusable modules. Think of them as specialized knowledge packs that Claude can automatically discover and apply when needed.

Skills vs Slash Commands

Understanding the difference between Skills and Slash Commands is crucial for effective use:

In simple terms: Skills are like having a specialized consultant on standby who jumps in when their expertise is needed, while Slash Commands are like calling a specific function when you want it.

Three Types of Skills

Skills can be installed at different scopes depending on your needs:

1. Personal Skills (~/.claude/skills/)

• Available globally across all your projects
• Perfect for general capabilities like code review, documentation, or personal coding preferences
• Follow you everywhere, like your personal toolkit

2. Project Skills (.claude/skills/)

• Available only within the current project
• Ideal for project-specific workflows, coding standards, or team conventions
• Shared with your team through version control

3. Plugin Skills

• Installed from the community marketplace
• Maintained by Anthropic or community contributors
• Quick to install, professionally maintained

How Skills Work

Understanding the mechanics helps you write better Skills that Claude will actually use.

Discovery Mechanism

Here's what happens when you make a request to Claude:

1. Scan Skills directories
   ↓
2. Read SKILL.md descriptions
   ↓
3. Analyze your request
   ↓
4. Match relevant Skills based on context
   ↓
5. Apply Skill expertise to generate response

Claude doesn't just blindly apply all Skills—it intelligently matches them to your needs. This is why writing good descriptions is critical.

Core Files

Every Skill must contain at minimum:

• SKILL.md: The heart of your Skill. Defines capabilities, use cases, best practices, and when Claude should invoke it
• Optional files: Templates, scripts, configuration examples, or reference materials

The SKILL.md file is where the magic happens—it's your instruction manual for Claude.

Prerequisites

Before we dive into creating your first Skill, let's make sure you have everything set up.

1. Install Claude Code

Ensure you're running the latest version of Claude Code:

claude --version

If you need to update, follow the installation instructions from the official documentation.

2. Add Plugin Marketplace (Optional)

To browse and install official Skills from Anthropic:

/plugin marketplace add anthropics/skills

This gives you access to professionally maintained Skills that you can use as references or starting points.

3. Browse Available Skills (Optional)

Want to see what's already available?

/plugin

This opens an interactive browser showing all available plugins and skills. It's a great way to get inspiration for your own Skills or find existing solutions.

Creating the Frontend Design Skill

Now for the exciting part—let's build a comprehensive frontend development Skill that will transform Claude into your React and responsive design expert.

Step 1: Create Directory Structure

Navigate to your project root and create the Skill directory:

mkdir -p .claude/skills/frontend-design
mkdir -p .claude/skills/frontend-design/templates

This creates a clean structure:

.claude/skills/frontend-design/
└── templates/

The templates folder will hold reusable code patterns we'll create later.

Step 2: Create SKILL.md

This is the most important file. Create .claude/skills/frontend-design/SKILL.md with the following content:

---
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
---

# Frontend Design & Development Specialist

You are a frontend development specialist focused on creating high-quality, modern web applications with expertise in React, responsive design, and user experience.

## Core Expertise

### React Development
- Modern React patterns (hooks, context, composition)
- Component architecture and design systems
- State management (useState, useReducer, Context API, or external libraries)
- Performance optimization (React.memo, useMemo, useCallback)
- Server components and client components (Next.js App Router)

### Responsive Design
- Mobile-first approach
- CSS Grid and Flexbox layouts
- Breakpoint strategies
- Responsive typography and spacing
- Touch-friendly interfaces

### UI/UX Best Practices
- Intuitive navigation and information architecture
- Visual hierarchy and consistency
- Loading states and error handling
- Micro-interactions and animations
- User feedback mechanisms

### Accessibility (a11y)
- Semantic HTML structure
- ARIA labels and roles
- Keyboard navigation support
- Screen reader compatibility
- Color contrast and visual accessibility
- Focus management

### Performance Optimization
- Code splitting and lazy loading
- Image optimization (Next.js Image component)
- Bundle size management
- Core Web Vitals (LCP, FID, CLS)
- Caching strategies

### Modern Frontend Architecture
- Component-based architecture
- Design tokens and theming
- CSS-in-JS or Tailwind CSS
- TypeScript for type safety
- Testing strategies (unit, integration, e2e)

## When to Use This Skill

Invoke this skill when:
- Building new React components or features
- Implementing responsive layouts
- Optimizing frontend performance
- Ensuring accessibility compliance
- Refactoring component architecture
- Setting up design systems
- Debugging UI/UX issues
- Implementing animations or interactions

## Best Practices

1. **Component Design**
   - Keep components focused and single-purpose
   - Use composition over inheritance
   - Implement proper prop typing with TypeScript
   - Extract reusable logic into custom hooks

2. **Styling Approach**
   - Use consistent spacing and sizing scales
   - Implement responsive breakpoints systematically
   - Follow naming conventions (BEM, CSS Modules, or utility classes)
   - Avoid magic numbers; use design tokens

3. **Performance**
   - Minimize re-renders with proper memoization
   - Lazy load components and routes
   - Optimize images and assets
   - Monitor bundle size

4. **Accessibility**
   - Start with semantic HTML
   - Test with keyboard navigation
   - Use proper heading hierarchy
   - Provide alternative text for images
   - Ensure sufficient color contrast

5. **Code Quality**
   - Write self-documenting code
   - Add JSDoc comments for complex logic
   - Handle edge cases and loading states
   - Implement proper error boundaries

## Common Patterns

### Component Structure
\`\`\`tsx
interface ComponentProps {
  // Props definition
}

export function Component({ prop }: ComponentProps) {
  // Hooks at the top
  // Event handlers
  // Render logic
  return (
    // JSX
  )
}
\`\`\`

### Responsive Design
- Use Tailwind breakpoints: \`sm:\`, \`md:\`, \`lg:\`, \`xl:\`, \`2xl:\`
- Mobile-first: base styles for mobile, breakpoints for larger screens
- Container queries for component-level responsiveness

### State Management
- Local state for UI-only concerns
- Context for shared state across component tree
- Server state management for API data

## Tools and Technologies

- **Framework**: React, Next.js
- **Styling**: Tailwind CSS, CSS Modules, styled-components
- **Type Safety**: TypeScript
- **Testing**: Jest, React Testing Library, Playwright
- **Build Tools**: Vite, Next.js, Webpack
- **Version Control**: Git

## Output Expectations

When working on frontend tasks:
1. Write clean, readable, and maintainable code
2. Follow project conventions and style guides
3. Ensure cross-browser compatibility
4. Implement responsive design by default
5. Consider accessibility from the start
6. Optimize for performance
7. Handle errors gracefully
8. Provide appropriate user feedback

What makes this SKILL.md effective:

• Clear frontmatter: The allowed-tools section defines which operations this Skill can perform
• Comprehensive expertise: Detailed breakdown of what the Skill knows
• Explicit activation triggers: The "When to Use This Skill" section tells Claude exactly when to engage
• Actionable guidelines: Best practices give Claude concrete rules to follow
• Real patterns: Code examples show the expected output style

Creating Practical Templates

Templates are ready-to-use code patterns that embody your Skill's best practices. Let's create four essential templates.

Template 1: Basic Component Template

Create .claude/skills/frontend-design/templates/component.tsx:

import { ReactNode } from 'react'

interface ComponentNameProps {
  children?: ReactNode
  className?: string
}

/**
 * ComponentName - Brief description of what this component does
 *
 * @param children - Child elements to render
 * @param className - Additional CSS classes
 */
export function ComponentName({
  children,
  className = ''
}: ComponentNameProps) {
  return (
    <div classname="{className}">
      {children}
    </div>
  )
}

Why this template matters: It establishes consistent component structure, TypeScript typing, and documentation patterns.

Template 2: Custom Hook Template

Create .claude/skills/frontend-design/templates/hook.ts:

import { useState, useEffect } from 'react'

interface UseHookNameOptions {
  // Configuration options
}

/**
 * useHookName - Brief description of what this hook does
 *
 * @param options - Configuration options for the hook
 * @returns Hook return values
 */
export function useHookName(options: UseHookNameOptions = {}) {
  const [state, setState] = useState()

  useEffect(() => {
    // Side effects here

    return () => {
      // Cleanup
    }
  }, [])

  return {
    state,
    // Other return values
  }
}

Why this template matters: Custom hooks are a powerful React pattern. This template ensures consistent implementation with proper cleanup and documentation.

Template 3: Responsive Layout

Create .claude/skills/frontend-design/templates/responsive-layout.tsx:

import { ReactNode } from 'react'

interface ResponsiveLayoutProps {
  children: ReactNode
  sidebar?: ReactNode
  header?: ReactNode
  footer?: ReactNode
}

/**
 * ResponsiveLayout - A responsive layout component with optional sidebar, header, and footer
 *
 * Mobile: Single column stack
 * Tablet (md): Header/content/footer stack
 * Desktop (lg+): Header + sidebar/content grid + footer
 */
export function ResponsiveLayout({
  children,
  sidebar,
  header,
  footer
}: ResponsiveLayoutProps) {
  return (
    <div classname="min-h-screen flex flex-col">
      {/* Header */}
      {header && (
        <header classname="sticky top-0 z-50 bg-white border-b">
          {header}
        </header>
      )}

      {/* Main Content Area */}
      <div classname="flex-1 flex flex-col lg:flex-row">
        {/* Sidebar - Hidden on mobile, shown on desktop */}
        {sidebar && (
          <aside classname="hidden lg:block lg:w-64 border-r bg-gray-50">
            <div classname="sticky top-16 p-4">
              {sidebar}
            </div>
          </aside>
        )}

        {/* Main Content */}
        <main classname="flex-1 p-4 md:p-6 lg:p-8">
          <div classname="max-w-7xl mx-auto">
            {children}
          </div>
        </main>
      </div>

      {/* Footer */}
      {footer && (
        <footer classname="border-t bg-gray-50">
          {footer}
        </footer>
      )}
    </div>
  )
}

Why this template matters: Responsive layouts are fundamental to modern web development. This template demonstrates mobile-first design with progressive enhancement.

Template 4: Form Pattern

Create .claude/skills/frontend-design/templates/form-pattern.tsx:

import { FormEvent, useState } from 'react'

interface FormData {
  // Define form fields
  email: string
  name: string
}

interface FormPatternProps {
  onSubmit: (data: FormData) => Promise<void>
  initialData?: Partial<formdata>
}

/**
 * FormPattern - Accessible form component with validation and error handling
 */
export function FormPattern({
  onSubmit,
  initialData = {}
}: FormPatternProps) {
  const [formData, setFormData] = useState<formdata>({
    email: initialData.email || '',
    name: initialData.name || ''
  })
  const [errors, setErrors] = useState<partial<record<keyof formdata,="" string="">>>({})
  const [isSubmitting, setIsSubmitting] = useState(false)

  const validateForm = (): boolean => {
    const newErrors: Partial<record<keyof formdata,="" string="">> = {}

    if (!formData.email) {
      newErrors.email = 'Email is required'
    } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(formData.email)) {
      newErrors.email = 'Please enter a valid email'
    }

    if (!formData.name) {
      newErrors.name = 'Name is required'
    }

    setErrors(newErrors)
    return Object.keys(newErrors).length === 0
  }

  const handleSubmit = async (e: FormEvent) => {
    e.preventDefault()

    if (!validateForm()) return

    setIsSubmitting(true)
    try {
      await onSubmit(formData)
    } catch (error) {
      console.error('Form submission error:', error)
      setErrors({ email: 'An error occurred. Please try again.' })
    } finally {
      setIsSubmitting(false)
    }
  }

  return (
    <form onsubmit="{handleSubmit}" classname="space-y-4">
      {/* Name Field */}
      <div>
        <label htmlfor="name" classname="block text-sm font-medium text-gray-700 mb-1">
          Name
        </label>
        <input id="name" type="text" value="{formData.name}" onchange="{(e)" ==""> setFormData({ ...formData, name: e.target.value })}
          className="w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
          aria-invalid={!!errors.name}
          aria-describedby={errors.name ? 'name-error' : undefined}
        />
        {errors.name && (
          <p id="name-error" classname="mt-1 text-sm text-red-600">
            {errors.name}
          </p>
        )}
      </div>

      {/* Email Field */}
      <div>
        <label htmlfor="email" classname="block text-sm font-medium text-gray-700 mb-1">
          Email
        </label>
        <input id="email" type="email" value="{formData.email}" onchange="{(e)" ==""> setFormData({ ...formData, email: e.target.value })}
          className="w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
          aria-invalid={!!errors.email}
          aria-describedby={errors.email ? 'email-error' : undefined}
        />
        {errors.email && (
          <p id="email-error" classname="mt-1 text-sm text-red-600">
            {errors.email}
          </p>
        )}
      </div>

      {/* Submit Button */}
      <button type="submit" disabled="{isSubmitting}" classname="w-full px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors">
        {isSubmitting ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  )
}
</record<keyof></partial<record<keyof></formdata></formdata></void>

Why this template matters: Forms are ubiquitous in web applications. This template demonstrates proper validation, error handling, accessibility, and loading states—all essential for production-quality forms.

Step 3: Create README Documentation

Create .claude/skills/frontend-design/README.md to document your Skill for team members:

# Frontend Design Skill

This skill enhances Claude's capabilities for frontend development tasks, with a focus on React, responsive design, accessibility, and modern web development best practices.

## What This Skill Provides

- **React Development**: Modern patterns, hooks, component architecture
- **Responsive Design**: Mobile-first layouts, breakpoint strategies
- **UI/UX Best Practices**: User experience, visual hierarchy, interactions
- **Accessibility**: WCAG compliance, semantic HTML, keyboard navigation
- **Performance**: Optimization techniques, Core Web Vitals
- **Modern Architecture**: Component design, type safety, testing

## How It Works

Claude will automatically invoke this skill when you:
- Ask to build React components or features
- Request help with responsive layouts
- Need accessibility improvements
- Want to optimize frontend performance
- Refactor component architecture
- Set up design systems

## Templates

This skill includes ready-to-use templates in the `templates/` directory:

- **component.tsx**: Basic React component structure with TypeScript
- **hook.ts**: Custom React hook template
- **responsive-layout.tsx**: Responsive layout with header, sidebar, and footer
- **form-pattern.tsx**: Accessible form with validation and error handling

## Usage

Simply ask Claude for frontend development help, and this skill will be automatically invoked. For example:

\`\`\`
"Create a responsive card component with hover effects"
"Build an accessible navigation menu"
"Optimize this component for performance"
"Add dark mode support to this layout"
\`\`\`

## Allowed Tools

This skill has access to:
- Read, Write, Edit (for file operations)
- Bash (for running build/test commands)
- Glob, Grep (for searching the codebase)

## Best Practices Enforced

1. Mobile-first responsive design
2. Semantic HTML and ARIA attributes
3. TypeScript for type safety
4. Performance optimization by default
5. Proper error handling and loading states
6. Consistent code style and conventions

## Customization

You can modify `SKILL.md` to:
- Add project-specific conventions
- Include custom design system guidelines
- Define additional patterns and practices
- Restrict or expand tool access

---

**Note**: This is a project-specific skill. It will only be available when working in this project directory.

Understanding SKILL.md

Let's break down what makes a great SKILL.md file and why each section matters.

Frontmatter Configuration

---
allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
---

Purpose and benefits:

• Security: Restricts which operations the Skill can perform, preventing unintended actions
• Clarity: Makes tool permissions explicit and auditable
• Flexibility: Can be adjusted based on Skill requirements (read-only for review Skills, full access for development Skills)

This configuration is optional—if omitted, the Skill inherits default tool permissions.

Core Expertise Section

This section defines the Skill's knowledge domains. Think of it as the Skill's resume—what it knows and what it can do.

Key areas covered:

• React Development: Component patterns, hooks, state management techniques
• Responsive Design: Layout strategies, mobile-first approaches, breakpoint design
• Accessibility: WCAG standards, ARIA attributes, keyboard navigation
• Performance: Optimization techniques, metrics, best practices

Writing tips for this section:

• Be specific, not generic ("Use React.memo for expensive computations" vs. "Improve performance")
• Include actual technology and tool names (Next.js, Tailwind CSS, TypeScript)
• Provide concrete examples and patterns
• Organize information logically in subsections

When to Use This Skill

This is arguably the most critical section. It tells Claude when to activate this Skill.

Effective triggers:

Invoke this skill when:
- Building new React components or features
- Implementing responsive layouts
- Optimizing frontend performance
- Ensuring accessibility compliance

Why this works:

• Clear, action-oriented triggers
• Specific enough to avoid false positives
• Broad enough to cover the Skill's domain

Ineffective triggers:

Use this skill for frontend work

Why this fails:

• Too vague and generic
• Doesn't provide clear activation criteria
• Could match almost any web development request

Best Practices Section

This section provides concrete guidelines that Claude should follow. Think of it as a style guide and quality checklist rolled into one.

What to include:

• Code style conventions
• Architectural decision criteria
• Performance optimization checklists
• Accessibility requirements
• Error handling patterns

Example of actionable best practices:

1. **Component Design**
   - Keep components focused and single-purpose
   - Use composition over inheritance
   - Implement proper prop typing with TypeScript
   - Extract reusable logic into custom hooks

These aren't abstract principles—they're concrete actions Claude can take.

Activating and Using the Skill

Now that you've created your Skill, let's get it up and running.

Step 1: Restart Claude Code

Skills are loaded at startup, so you need to restart Claude for changes to take effect:

claude restart

Important: You must restart after:

• Creating a new Skill
• Modifying SKILL.md
• Adding or changing templates

Step 2: Verify Skill is Loaded

After restart, verify that Claude has discovered your Skill. The easiest way is to ask directly:

"Do you have a frontend design skill available?"

Claude should confirm that it has access to the frontend design skill and can describe its capabilities.

Step 3: Test the Skill

Now it's time to put your Skill to work. Here are test requests that should trigger the Skill:

Test 1: Create a Component

"Create a responsive product card component with image, title, price, and a call-to-action button. It should have hover effects and be fully accessible."

Test 2: Optimize Performance

"Review this component and identify performance optimization opportunities. Apply React.memo where appropriate."

Test 3: Improve Accessibility

"Make this navigation menu accessible for keyboard users and screen readers. Add proper ARIA attributes and focus management."

Recognizing Skill Activation

When the Skill is successfully activated, you'll notice that Claude's responses:

• Follow defined best practices: Uses TypeScript, proper component structure, accessibility attributes
• Reference specific technologies: Mentions tools and patterns defined in the Skill (Tailwind classes, React patterns)
• Apply coding conventions: Follows the style guides and patterns specified
• Provide detailed, specialized suggestions: Goes beyond generic advice to offer framework-specific solutions

If Claude's responses feel generic or don't follow your Skill's guidelines, the Skill may not be activating properly. See the Troubleshooting section.

Best Practices

Let's explore how to create Skills that are effective, maintainable, and actually get used by Claude.

1. Keep Skills Focused

Each Skill should have a clear, well-defined scope. Don't try to make one Skill do everything.

Good Skill scopes:

• frontend-design: React, responsive design, accessibility, performance
• backend-api: REST API design, database patterns, authentication
• testing: Unit tests, integration tests, E2E test patterns
• documentation: README files, API docs, inline comments

Poor Skill scopes:

• web-development: Too broad, encompasses both frontend and backend
• coding: No focus at all, could apply to anything
• best-practices: Too vague, lacks specific domain

Why focus matters: Claude matches Skills based on context. A tightly focused Skill with clear triggers is more likely to be invoked at the right time than a broad, generic one.

2. Write Detailed, Specific Descriptions

Skill discovery relies heavily on the quality of your descriptions. Claude reads your SKILL.md to determine if it's relevant.

Effective description:

Invoke this skill when building React components that need to be responsive, accessible, and performant. Use for implementing mobile-first layouts, adding ARIA attributes, optimizing re-renders, or creating reusable component patterns.

Why this works:

• Specific technologies mentioned (React, ARIA)
• Clear use cases (responsive, accessible, performant)
• Concrete actions (mobile-first layouts, optimizing re-renders)

Ineffective description:

Use for frontend work when needed.

Why this fails:

• No specific triggers
• Vague terminology
• No actionable criteria

3. Provide Practical, Production-Ready Templates

Templates should be more than placeholder code—they should embody your best practices and be ready to use with minimal modification.

What makes a good template:

• Complete TypeScript types and interfaces
• Comprehensive JSDoc documentation
• Error handling and edge cases considered
• Follows the Skill's style conventions
• Includes accessibility features
• Ready to copy and adapt

Example of template quality:

// ❌ Poor template - too minimal
export function Button({ onClick }) {
  return <button onclick="{onClick}">Click</button>
}

// ✅ Good template - production-ready
interface ButtonProps {
  onClick: () => void
  variant?: 'primary' | 'secondary'
  disabled?: boolean
  children: ReactNode
}

/**
 * Accessible button component with variants
 */
export function Button({
  onClick,
  variant = 'primary',
  disabled = false,
  children
}: ButtonProps) {
  return (
    <button onclick="{onClick}" disabled="{disabled}" classname="{/*" styles="" based="" on="" variant="" *="" }="" aria-disabled="{disabled}">
      {children}
    </button>
  )
}

4. Update Skills as Your Project Evolves

Skills shouldn't be "set and forget." As your project grows and changes, keep your Skills in sync.

When to update:

• Adding new frameworks or libraries to your stack
• Discovering new patterns or best practices
• Changing coding conventions or style guides
• Fixing issues discovered during use
• Adding new templates for common patterns

Tip: Schedule periodic Skill reviews (e.g., monthly) to ensure they reflect your current practices.

5. Carefully Configure Tool Permissions

The allowed-tools section controls what operations your Skill can perform. Adjust based on the Skill's purpose.

Read-only Skill (for code review):

allowed-tools:
- Read
- Grep
- Glob

Development Skill (for active coding):

allowed-tools:
- Read
- Write
- Edit
- Bash
- Grep
- Glob

Why this matters:

• Security: Prevents unintended file modifications
• Clarity: Makes the Skill's capabilities explicit
• Debugging: Helps identify permission issues

6. Choose the Right Skill Scope

Deciding between project Skills and personal Skills is important for organization and reusability.

Use Project Skills (.claude/skills/) when:

• The Skill is specific to current project workflows
• It contains project-specific conventions or patterns
• You want to share it with team members via version control
• It references project configuration or structure

Examples:

• Design system component patterns
• Project-specific testing strategies
• Custom deployment workflows

Use Personal Skills (~/.claude/skills/) when:

• The Skill applies to general development capabilities
• You want it available across all your projects
• It reflects your personal coding preferences
• It's a general-purpose capability (code review, documentation)

Examples:

• General React best practices
• Git commit message formatting
• Personal code review checklist

Troubleshooting

Even with careful setup, you might encounter issues. Here's how to diagnose and fix common problems.

Skill Not Being Activated

If Claude doesn't seem to be using your Skill, work through this checklist:

1. Confirm restart

Skills are only loaded at startup. Make sure you've restarted Claude:

claude restart

2. Verify file structure

Check that files are in the correct locations:

find .claude/skills/frontend-design -type f

Expected output:

.claude/skills/frontend-design/SKILL.md
.claude/skills/frontend-design/README.md
.claude/skills/frontend-design/templates/component.tsx
...

3. Validate SKILL.md format

Common formatting issues:

• Frontmatter must be surrounded by exactly three dashes (---)
• YAML in frontmatter must be properly indented
• No smart quotes or special Unicode characters
• Valid Markdown syntax throughout

4. Make requests more explicit

Vague requests may not trigger Skill matching. Be specific:

❌ Too vague: "Help me with code"
✅ Specific: "Create a responsive React component for displaying user profiles with avatar, name, and bio"

5. Check Claude's response

Ask Claude directly: "Which skills are you using right now?" This can help you understand if the Skill is being recognized.

Skill Tool Permission Errors

If Claude reports that it can't perform certain actions:

Symptom:

I don't have permission to write files with this skill

Solution:

1. Check the allowed-tools list in your SKILL.md
2. Add the required tool (e.g., Write, Edit)
3. Restart Claude Code

---
allowed-tools:
- Read
- Write  # Add this if skill needs to create/modify files
- Edit   # Add this if skill needs to modify existing files
---

Multiple Skills Conflicting

If you have several Skills that might overlap:

Problem signs:

• Claude seems confused about which approach to use
• Responses mix patterns from different Skills inconsistently

Solutions:

1. Differentiate activation triggers: Make "When to Use" sections more specific

# Frontend Skill
Invoke when: Building React UI components, layouts, or interactions

# Backend Skill  
Invoke when: Creating APIs, database operations, or server logic

1. Add explicit scope boundaries: Clarify what each Skill does and doesn't handle
2. Consider merging: If two Skills are very similar, combine them into one comprehensive Skill

Skills Not Being Discovered

If Claude can't find any Skills at all:

Check directory location:

# For project skills
ls -la .claude/skills/

# For personal skills
ls -la ~/.claude/skills/

Verify Claude Code can access the directory:

• Check file permissions
• Ensure no .gitignore rules are hiding the .claude directory
• Confirm you're in the correct project directory

Advanced Techniques

Once you're comfortable with basic Skills, these advanced techniques can make them even more powerful.

1. Progressive File Disclosure

For Skills with large templates or reference materials, use file references instead of embedding everything in SKILL.md:

## Templates

This skill includes templates for common patterns:
- Component structure: See `templates/component.tsx`
- Custom hooks: See `templates/hook.ts`
- Forms: See `templates/form-pattern.tsx`

Claude will read these files when needed.

Benefits:

• Keeps SKILL.md focused and readable
• Reduces initial loading time
• Makes templates easier to maintain
• Allows templates to be actual working code that you can test

2. Combine Multiple Skills

Skills are designed to work together. Claude can intelligently use multiple Skills for complex tasks:

Example workflow:

1. User: "Build a user profile page with tests"
2. frontend-design skill: Creates the React component
3. testing skill: Generates comprehensive test suite
4. documentation skill: Adds JSDoc and README section

How to enable this:

• Give each Skill clear, non-overlapping domains
• Write specific activation triggers
• Let Claude automatically orchestrate which Skills to use

3. Reference Project Configuration

Make your Skill aware of project-specific settings:

## Project Configuration

This skill follows conventions defined in:
- `tsconfig.json` for TypeScript compiler settings
- `.prettierrc` for code formatting rules
- `tailwind.config.js` for design tokens and theme
- `.eslintrc` for code quality standards

When generating code, check these files for project-specific requirements.

Benefits:

• Generated code matches your project's style automatically
• Reduces need for manual adjustments
• Ensures consistency across all generated code

4. Create Skill Suites

For comprehensive workflows, create related Skills that cover different aspects:

.claude/skills/
├── frontend-design/      # UI component development
├── api-integration/      # Backend API connection
├── state-management/     # Global state patterns
├── performance/          # Optimization techniques
└── deployment/           # Build and deploy processes

Benefits:

• Each Skill stays focused and maintainable
• Easy to enable/disable specific capabilities
• Team members can contribute to individual Skills
• Skills can evolve independently

Real-World Use Cases

Let's see how this Skill performs in real development scenarios.

Scenario 1: Building New Features

Your request:

"I need to build a user profile page with avatar upload, editable fields, and real-time validation. The page should be responsive and accessible."

What happens with the Skill activated:

1. Component Structure: Creates properly typed React components with TypeScript interfaces
2. Responsive Layout: Implements mobile-first design with appropriate breakpoints
3. Form Handling: Uses the form pattern template with validation and error handling
4. Image Upload: Adds accessible file input with preview and loading states
5. Accessibility: Includes ARIA labels, keyboard navigation, and screen reader support
6. Error Boundaries: Wraps components in error boundaries for graceful failure handling

The result: A production-ready feature that follows all your established patterns, rather than generic boilerplate code.

Scenario 2: Performance Optimization

Your request:

"This dashboard component is rendering slowly. Can you optimize it?"

What happens with the Skill activated:

1. Analysis: Identifies unnecessary re-renders and expensive computations
2. Memoization: Applies React.memo, useMemo, and useCallback appropriately
3. Code Splitting: Suggests lazy loading for heavy components
4. List Optimization: Implements virtualization for long lists
5. Image Optimization: Adds Next.js Image component for automatic optimization
6. Measurement: Suggests monitoring tools and metrics to track improvements

The result: Concrete, actionable optimizations based on React best practices, not generic "make it faster" advice.

Scenario 3: Accessibility Improvements

Your request:

"Make this modal dialog accessible for all users."

What happens with the Skill activated:

1. Semantic HTML: Ensures proper dialog/modal structure
2. ARIA Attributes: Adds role="dialog", aria-labelledby, aria-describedby
3. Keyboard Navigation: Implements Esc to close, Tab focus trap
4. Focus Management: Returns focus to trigger element on close
5. Screen Reader: Adds announcements for state changes
6. Visual Accessibility: Checks color contrast, provides visual focus indicators

The result: A fully accessible modal that meets WCAG 2.1 Level AA standards.

Further Reading

Official Documentation

• Claude Code Skills Documentation - Complete reference for Skills
• Plugin Marketplaces - Browse and install community Skills
• Slash Commands vs Skills - Understanding the differences

Related Resources

• React Official Documentation - React best practices and patterns
• WCAG Accessibility Guidelines - Web accessibility standards
• Web Vitals - Performance metrics that matter
• TypeScript Handbook - TypeScript best practices

Summary

Congratulations! You've learned how to create a professional Claude Code Skill from scratch. Let's recap what you've accomplished:

What You've Learned

1. ✅ Understanding Skills: How they work, when they activate, and why they're powerful
2. ✅ Creating Skills: Built a complete frontend design Skill with SKILL.md
3. ✅ Writing Quality Descriptions: Crafted clear activation triggers and best practices
4. ✅ Creating Templates: Developed production-ready code patterns
5. ✅ Activating Skills: Loaded and tested your custom Skill
6. ✅ Best Practices: Learned how to make Skills focused, maintainable, and effective

Quick Reference Card

Essential steps to create any new Skill:

# 1. Create directory structure
mkdir -p .claude/skills/[skill-name]
mkdir -p .claude/skills/[skill-name]/templates

# 2. Create SKILL.md
# (Use templates from this tutorial as starting point)

# 3. Add templates and resources (optional)
# Create reusable code patterns in templates/

# 4. Restart Claude Code
claude restart

# 5. Test the Skill
# Make requests that should trigger the Skill

Key Takeaways

For Skills to work effectively:

• Write specific, detailed activation triggers
• Keep Skills focused on one domain
• Provide production-ready templates
• Update Skills as your project evolves
• Test Skills with real requests

Remember:

• Skills are automatically matched to your requests
• Good descriptions are critical for discovery
• Templates embody your best practices
• Tool permissions control what Skills can do

Next Steps

Now that you understand the fundamentals, try creating Skills for other domains:

Suggested Skills to build:

• Backend Development: Node.js, Express, database patterns, API design
• Testing: Unit tests with Jest, integration tests, E2E with Playwright
• DevOps: CI/CD pipelines, Docker containerization, deployment automation
• Documentation: README templates, API docs, inline comment standards
• Code Review: Quality checklists, security considerations, performance audits

Tips for your next Skill:

1. Start with SKILL.md - get the description and triggers right first
2. Add templates gradually as you identify common patterns
3. Test with real requests from your daily work
4. Refine based on how Claude actually uses the Skill
5. Share with your team and gather feedback

Appendix

Complete File Structure

Here's the complete structure of our frontend design Skill:

.claude/skills/frontend-design/
├── SKILL.md                      # Core definition (required)
├── README.md                     # Documentation for humans
└── templates/                    # Reusable code patterns
    ├── component.tsx             # Basic React component
    ├── hook.ts                   # Custom hook pattern
    ├── responsive-layout.tsx     # Layout component
    └── form-pattern.tsx          # Form with validation

Example Requests to Test Your Skill

Copy these requests to quickly test that your Skill is working:

"Create a card component with image, title, description, and action buttons. Make it responsive and add hover effects."

"Build a navigation bar that's responsive with a hamburger menu on mobile. Ensure it's keyboard accessible."

"Implement a data table with sorting, filtering, and pagination. Optimize it for performance with large datasets."

"Create an accessible modal dialog that contains a contact form with validation. Include proper focus management."

"Review this component and identify opportunities to reduce re-renders. Apply memoization where appropriate."

"Add dark mode support to this layout component using CSS variables and React context."

"Create a skeleton loading state for this user profile card. Make the animation smooth and accessible."

You're now equipped to transform Claude into a specialized frontend development expert!

If you have questions or run into issues, refer to the official documentation or revisit the troubleshooting section. Happy coding with Claude Code Skills!