secondsky__claude-skills/docs/reference/claude-code-skill-standards.md

Claude Code Skill Standards

Last Updated: 2025-10-20 Source: https://docs.claude.com/en/docs/claude-code/skills Reference Skill: ~/.claude/skills/tailwind-v4-shadcn/

---

What Are Claude Code Skills?

Skills are modular capabilities stored in ~/.claude/skills/ that Claude Code automatically discovers and uses based on user requests.

Key Characteristics:

• Model-invoked - Claude autonomously decides when to use them
• Description-based discovery - Claude matches skills based on YAML frontmatter description
• Templates and documentation - Help users set up projects quickly
• No executable code - Skills provide instructions and templates, not running code

---

Required Structure

~/.claude/skills/skill-name/
├── SKILL.md              # REQUIRED - Instructions with YAML frontmatter
├── README.md             # OPTIONAL - Quick reference (our addition)
├── templates/            # OPTIONAL - File templates
└── reference/            # OPTIONAL - Additional documentation

---

SKILL.md Format (REQUIRED)

YAML Frontmatter (Top of File)

---
name: Skill Display Name
description: |
  What the skill does and when Claude should use it.

  Use when: specific scenarios where this skill applies.

  Keywords: keyword1, keyword2, error messages, technology names
---

Critical: The description field determines when Claude uses the skill. It MUST include:

• What the skill does
• When Claude should use it
• Keywords for discovery

Markdown Content (After Frontmatter)

# Skill Title

Detailed instructions for Claude to follow when using this skill.

## Section 1: Setup
Step-by-step instructions...

## Section 2: Configuration
Examples and code snippets...

## Common Issues
Known problems and solutions...

---

Example: Tailwind v4 Skill

SKILL.md Frontmatter:

---
name: Tailwind v4 + shadcn/ui Stack
description: |
  Production-tested setup for Tailwind CSS v4 with shadcn/ui, Vite, and React.

  Use when: initializing React projects with Tailwind v4, setting up shadcn/ui,
  implementing dark mode, debugging CSS variable issues, fixing theme switching,
  migrating from Tailwind v3, or encountering color/theming problems.

  Keywords: Tailwind v4, shadcn/ui, @tailwindcss/vite, @theme inline, dark mode,
  CSS variables, hsl() wrapper, components.json, React theming, theme switching,
  colors not working, variables broken, theme not applying
---

Directory Structure:

tailwind-v4-shadcn/
├── SKILL.md                      # Full instructions
├── README.md                     # Quick reference (our addition)
├── templates/                    # Ready-to-copy files
│   ├── vite.config.ts
│   ├── index.css
│   ├── components.json
│   └── ...
└── reference/                    # Deep-dive docs
    ├── architecture.md
    ├── common-gotchas.md
    └── ...

---

Our Additions (Beyond Minimum)

We're adding these for better quality:

1. README.md

Purpose: Quick reference with explicit trigger keywords

Format:

# Skill Name

**Status**: Production Ready ✅
**Last Updated**: 2025-10-20

## Auto-Trigger Keywords
- keyword1
- keyword2
- error message

## What This Skill Does
Brief description...

## Known Issues Prevented
Table of errors this skill fixes...

2. templates/

Purpose: Working file templates users can copy

Requirements:

• Complete, tested files
• Latest package versions
• No hardcoded secrets
• Well-commented

3. reference/

Purpose: Additional documentation for complex topics

Examples:

• architecture.md - Deep dive into patterns
• common-gotchas.md - Troubleshooting guide
• migration-guide.md - Upgrading from old versions

---

Discovery Mechanism

How Claude Finds Skills

1. User makes a request
2. Claude checks ~/.claude/skills/ directory
3. Reads SKILL.md frontmatter from each skill
4. Matches description field against user's request
5. If match > threshold, proposes using the skill

Trigger Keywords

In frontmatter description, include:

• Technology names: "Tailwind v4", "Cloudflare Workers"
• Use cases: "dark mode setup", "JWT verification"
• Error messages: "colors not working", "build fails"
• Related terms: "shadcn/ui", "theme switching"

Example:

description: |
  Use when: setting up Cloudflare Workers, configuring Hono routing,
  deploying with wrangler, or encountering "Static Assets not found" errors.

  Keywords: Cloudflare Workers, Hono, wrangler, Static Assets, CF Workers,
  deployment, serverless

---

Quality Standards

Before Committing a Skill

• SKILL.md has valid YAML frontmatter
• Description includes "Use when" scenarios
• Keywords cover common searches and errors
• Instructions are clear and complete
• Templates are tested and working
• Versions are documented
• Official docs are referenced
• No hardcoded secrets

Documentation Requirements

Must Include:

• Version numbers for all packages
• Links to official documentation
• Known issues with sources (GitHub issues, etc.)
• Last updated date
• Production testing evidence

Must Not Include:

• Outdated patterns
• Deprecated approaches
• Unverified information
• Hardcoded credentials
• Untested templates

---

File Naming Conventions

• SKILL.md - Must be exactly this name (case-sensitive)
• README.md - Optional, our addition
• templates/ - Lowercase, plural
• reference/ - Lowercase, plural
• examples/ - Lowercase, plural (if used)

---

Best Practices

Description Field

✅ Good:

description: |
  Sets up Cloudflare Workers with Vite, Hono routing, and Static Assets.

  Use when: creating new CF Workers projects, adding Vite to existing Workers,
  or encountering "Static Assets 404" errors.

  Keywords: Cloudflare Workers, CF Workers, Hono, wrangler, Vite, Static Assets

❌ Bad:

description: "Cloudflare Workers skill"

Instructions

✅ Good: Step-by-step with code examples ❌ Bad: Vague descriptions without specifics

Templates

✅ Good: Complete, working files with comments ❌ Bad: Code snippets or incomplete examples

---

Maintenance

When to Update

• New major version of key dependency
• Security vulnerability reported
• Breaking change announced
• Official docs updated
• Users report skill doesn't work

Update Process

1. Re-verify official documentation
2. Test with new versions
3. Update templates
4. Update SKILL.md
5. Update "Last Updated" date
6. Commit with detailed changelog

---

Examples from Real Skills

Tailwind v4 Skill

What it teaches us:

• ✅ Comprehensive frontmatter with keywords
• ✅ Templates directory with working files
• ✅ Reference docs for deep dives
• ✅ Production-tested evidence

Firecrawl Scraper Skill

What it teaches us:

• ✅ Clear use cases in description
• ✅ API key configuration documented
• ✅ Python and TypeScript templates
• ✅ Error handling patterns

---

Official Documentation

Primary Source: https://docs.claude.com/en/docs/claude-code/skills

Key Points from Official Docs:

• Skills are model-invoked (Claude decides when to use them)
• Description field is critical for discovery
• SKILL.md with YAML frontmatter is required
• Supporting files are optional
• Can be personal (~/.claude/skills/) or project-level (.claude/skills/)

---

Summary

Minimum Required

skill-name/
└── SKILL.md (with YAML frontmatter + instructions)

Our Standard

skill-name/
├── SKILL.md              # Required: Full instructions
├── README.md             # Our addition: Quick reference
├── templates/            # Our addition: Working files
└── reference/            # Optional: Deep-dive docs

Why we add more: Better discoverability, proven templates, comprehensive documentation leads to higher quality skills that actually help users.

---

Next: Use this standard when building all our skills.