meta-42skill

name	meta-42skill
description	Use when creating, improving, or packaging Claude Code skills. This skill guides through the complete skill creation workflow: (1) Understanding use cases through concrete examples, (2) Planning reusable resources (scripts/references/assets), (3) Writing effective SKILL.md with proper frontmatter and CSO optimization, (4) Validating and packaging skills for distribution.
version	3.0

42skill-v3: Skill Creation Guide

Overview

This skill transforms ideas into effective Claude Code skills. A skill is a folder containing instructions, scripts, and resources that Claude loads dynamically to perform specialized tasks.

Core Principle: Skills are "onboarding guides" for specific domains. Only include information Claude doesn't already know. Default assumption: Claude is smart—add value, not verbosity.

When to Use

• Creating a new skill from scratch
• Improving an existing skill's effectiveness
• Packaging a skill for distribution
• Converting a proven technique into a reusable skill

Don't use for:

• One-off solutions specific to a single project (put those in project README)
• Standard practices well-documented elsewhere
• Project conventions (put those in .claude/CLAUDE.md)

Quick Reference

Task	Action
Initialize skill	scripts/init_skill.py <name> --path <dir>
Validate skill	scripts/validate_skill.py <skill-path>
Package skill	scripts/package_skill.py <skill-path> [output-dir]
Check structure	Ensure SKILL.md exists with valid frontmatter

Skill Anatomy

skill-name/
├── SKILL.md          # Required: Instructions + frontmatter
├── scripts/          # Optional: Executable code (Python/Bash)
├── references/       # Optional: Documentation loaded as needed
└── assets/           # Optional: Files used in output (templates, images)

Progressive Disclosure

Skills use three-level loading to manage context:

1. Metadata (~100 words) - Always in context: name + description
2. SKILL.md body (<500 lines) - Loaded when skill triggers
3. Bundled resources (unlimited) - Loaded as needed by Claude

Workflow

Phase 1: Understand Use Cases

Goal: Clarify concrete examples of how the skill will be used.

Ask questions like:

• "What specific tasks should this skill handle?"
• "Can you give 2-3 examples of user requests this skill would serve?"
• "What would a user say that should trigger this skill?"
• "What existing workflow or technique is this skill capturing?"

Exit criteria: Clear understanding of 3+ concrete use cases.

Phase 2: Plan Resources

Analyze each use case to identify reusable components:

Resource Type	When to Include	Example
scripts/	Same code rewritten repeatedly, or deterministic reliability needed	rotate_pdf.py, validate_schema.py
references/	Documentation Claude should reference while working (>100 lines)	api_docs.md, schema.md, policies.md
assets/	Files used in output (not loaded into context)	template.pptx, logo.png, boilerplate/

Avoid duplication: Information lives in SKILL.md OR references, not both. Keep SKILL.md lean.

Phase 3: Create SKILL.md

3.1 Frontmatter (Required)

---
name: skill-name-with-hyphens
description: "Use when [trigger conditions] - [what it does and how it helps]"
---

Rules:

• name: lowercase, hyphens only, max 64 chars, use gerund form (creating-X, not X-creation)
• description: third-person, starts with "Use when...", max 1024 chars total
• Avoid reserved words: "anthropic", "claude" in names

CSO (Claude Search Optimization):

# BAD - Too vague
description: For async testing

# BAD - First person
description: I help you with flaky tests

# GOOD - Triggers + action
description: Use when tests have race conditions or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests

3.2 Document Structure

# Skill Name

## Overview
Core principle in 1-2 sentences.

## When to Use
- Trigger conditions (symptoms, use cases)
- When NOT to use

## Quick Reference
Table or bullets for common operations.

## [Main Content Sections]
Choose structure based on skill type:
- Workflow-Based: Sequential steps (## Step 1, ## Step 2...)
- Task-Based: Different operations (## Task A, ## Task B...)
- Reference-Based: Standards/specs (## Guidelines, ## Specifications...)

## Common Mistakes
What goes wrong + how to fix.

## Resources
References to scripts/, references/, assets/.

3.3 Writing Style

• Imperative form: "To accomplish X, do Y" (not "You should do X")
• Concise: Challenge each sentence—does Claude need this?
• Concrete: Real examples beat generic templates
• One excellent example beats many mediocre ones

Compression techniques:

# BAD - 42 words
Your human partner asks: "How did we handle authentication errors?"
You should respond: "I'll search past conversations."
Then dispatch a subagent with the query.

# GOOD - 20 words
Partner: "How did we handle auth errors?"
You: Searching...
[Dispatch subagent → synthesis]

3.4 Degrees of Freedom

Match specificity to task complexity:

Task Type	Guidance Level	Example
High freedom (creative)	Broad principles, let Claude adapt	"Use when designing APIs"
Low freedom (critical)	Explicit steps, validation checks	"Use when deploying to production - follow exact checklist"

Red flag: Over-constraining creative tasks or under-specifying critical operations.

Phase 4: Validate and Package

Validation checks:

• SKILL.md exists with valid YAML frontmatter
• name matches directory name
• description starts with "Use when..."
• description is third-person
• Total frontmatter < 1024 characters
• SKILL.md < 500 lines
• No [TODO] placeholders remaining
• Resources referenced in SKILL.md actually exist

Package command:

scripts/package_skill.py <skill-path> [output-dir]

Creates skill-name.zip containing the complete skill directory.

Common Mistakes

Mistake	Why It Fails	Fix
Vague description	Claude can't find it	"Use when [specific trigger]..."
First-person description	Injected into system prompt	Use third-person
Narrative storytelling	Wastes tokens	Focus on reusable patterns
Multi-language examples	Dilutes quality	One excellent example
Missing when-to-use	No clear trigger	Add "When to Use" section
Over-documented obvious things	Wastes context budget	Claude is smart—skip basics
Time-sensitive information	Becomes stale	Keep content evergreen
Deep file path references	Confusing	Keep references simple

Quality Checklist

Before Writing

• Technique isn't obvious or well-documented elsewhere
• Pattern applies broadly (not project-specific)
• Would reference this across multiple projects

Frontmatter

• Name uses gerund form (creating-X)
• Description starts with "Use when..."
• Description includes triggers AND what skill does
• Total frontmatter < 1024 characters

Content

• Overview states core principle (1-2 sentences)
• "When to Use" section with symptoms
• Quick reference table
• One excellent code example (if technique skill)
• Common mistakes section
• Keywords throughout for searchability
• Degrees of freedom match task complexity

Quality

• SKILL.md under 500 lines
• No narrative storytelling
• Supporting files only if needed (>100 lines reference)
• Cross-references use skill name, not file paths
• No time-sensitive information
• Concrete examples (not fill-in-blank templates)

Resources

Scripts

Script	Purpose
scripts/init_skill.py	Initialize new skill from template
scripts/validate_skill.py	Check skill structure and quality
scripts/package_skill.py	Create distributable zip

References

• references/skill_spec.md - Official Claude skill specification
• references/examples.md - Annotated examples of good skills

Assets

• assets/template/ - Starter template for new skills