SKILL.md Reference for Claude Code

SKILL.md Reference for Claude Code

SKILL.md is the file format that defines Claude Code Skills.

This guide covers common sections, recommended patterns, and examples for different Skill types. Use this as a reference when creating your own Skills.

What Is SKILL.md in Claude Code?

SKILL.md is a structured Markdown file containing instructions for Claude.

File naming and location:

Skills are typically organized as simple folders containing a SKILL.md file. Check current Claude Code documentation for the active placement and management workflow.

Purpose:

When you invoke a skill directly (for example, /react-component) or when Claude selects it automatically for a relevant task, Claude Code:

1. Locates the SKILL.md file
2. Reads the entire content
3. Injects instructions into Claude's context
4. Generates output following those instructions

Common Sections in a SKILL.md File

A typical SKILL.md file includes these sections.

1. Title

• Use a descriptive, actionable title
• Should clearly state what the Skill does
• Appears as the Skill name in listings

2. Description

Creates React functional components with TypeScript, proper typing, and accessibility
attributes.

• Brief summary (1-2 sentences)
• Explains the Skill's purpose
• Helps users understand when to use this Skill

3. Purpose (Recommended)

## Purpose
Use this Skill when creating new React components in our codebase. It ensures consistent:

Use this Skill when creating new React components in our codebase. It ensures consistent:

• TypeScript typing patterns
• Accessibility compliance (WCAG AA)
• Component file structure
• Testing setup

• More detailed than description
• Explains when to use (and not use) this Skill
• Can reference project-specific context

4. Instructions

## Instructions
Follow these rules when generating React components:

Instructions

Follow these rules when generating React components:

1. File Structure

• Create .tsx file, not .jsx
• Use PascalCase for component names
• One component per file

1. TypeScript

• Define Props interface before component
• Use explicit return type: React.FC or ReactElement
• Enable strict null checks

1. Accessibility

• Include ARIA labels where appropriate
• Use semantic HTML (button, nav, article)
• Ensure keyboard navigation works

• Core guidance for Claude
• Be specific and actionable
• Use numbered or bulleted lists
• Include rationale when needed

5. Examples (Highly Recommended)

Examples

Example 1: Simple Button Component

import React from 'react';
import styles from './Button.module.css';

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export const Button: React.FC<ButtonProps> = ({
  label,
  onClick,
  variant = 'primary'
}) => {
  return (
    <button
      className={`${styles.button} ${styles[variant]}`}
      onClick={onClick}
      aria-label={label}
    >
      {label}
    </button>
  );
};

• Show complete, working code
• Demonstrate patterns described in Instructions
• Include 2-3 examples covering common cases

6. Constraints (Optional)

Constraints

## Constraints
- Requires React 18+
- Assumes TypeScript 4.9 or later
- Uses CSS Modules (must be configured in build)
- Follows WCAG 2.1 Level AA standards

• Technical requirements
• Dependencies or assumptions
• Limitations or boundaries

7. Anti-Patterns (Optional)

Avoid

## Avoid
- Don't use `any` type for Props
- Don't use default exports
- Don't inline complex logic in JSX
- Don't use `div` for clickable elements

• What NOT to do
• Common mistakes to avoid

Example SKILL.md Files for Common Skill Types

Real-world Skill templates for different use cases.

Frontend Component Skill

# Vue Component Generator
Creates Vue 3 Composition API components with TypeScript and Pinia state.

Instructions

1. Use <script setup lang="ts"> syntax
2. Define Props with defineProps()
3. Use Pinia stores for shared state
4. Include <template> with semantic HTML
5. Use <style scoped> with CSS modules

Examples

Example Skill prompt for a Vue component workflow:

# Vue Component Generator
Creates Vue 3 components that match our frontend conventions.

## Instructions
- Use <script setup lang="ts">
- Define typed props with defineProps<T>()
- Keep template structure semantic and accessible
- Prefer Pinia for shared state and local refs for view-only state

## Constraints
- Vue 3.3+
- TypeScript 5.0+
- Pinia 2.x for state management

API Endpoint Skill

# REST API Endpoint
Creates Express API endpoints following our REST conventions.

Instructions

1. Route Structure: /api/v1/resource/:id
2. Method Handlers: Separate files for GET, POST, PUT, DELETE
3. Validation: Use Joi for request validation
4. Error Handling: Return consistent error format
5. Documentation: Include JSDoc for Swagger generation

Examples

Example Skill prompt for an Express API workflow:

# REST API Endpoint
Creates Express endpoints following team API conventions.

## Instructions
- Use /api/v1 resource paths
- Validate requests with Joi before handler logic
- Return JSON errors with code, message, and details
- Add JSDoc comments so Swagger docs can be generated

## Example Request
"Create a POST /api/v1/projects endpoint with Joi validation and standard error handling."

Testing Skill

# Unit Test Generator
Creates Jest/Vitest unit tests following our testing standards.

Instructions

1. File naming: ComponentName.test.ts
2. Structure: Describe blocks for each method/scenario
3. Assertions: Use expect() with specific matchers
4. Mocking: Mock external dependencies
5. Coverage: Aim for >80% line coverage

Examples

Example Skill prompt for generating unit tests:

# Unit Test Generator
Creates Jest or Vitest test files that follow team testing rules.

## Instructions
- Name files ComponentName.test.ts
- Group scenarios with describe blocks
- Mock network and database dependencies
- Assert visible behavior, edge cases, and error paths

## Example Request
"Write Vitest coverage for the auth service, including invalid token and expired session cases."

Common SKILL.md Patterns

Effective patterns when writing Skills.

Pattern 1: Clear, specific rules

Good:

- Use descriptive variable names (no single letters except i, j for loops)
- Functions should do one thing (max 20 lines)
- Extract repeated logic into helper functions

Pattern 2: Code examples over descriptions

Good:

Pattern 3: Consistent structure

Good: Pick a structure and use it across all your team's Skills for familiarity.

Pattern 4: Project-specific context

Good:

Follow the company style guide at [link] with these additions:
- [specific team rules]

Manage Skills in Verdent

Verdent provides a Skill editor with syntax highlighting, validation, and version control.

Edit SKILL.md files directly in the browser with live preview. Changes sync across all projects automatically.

Edit Skills in Verdent