Core Principles

1. The Context Window is a Public Good

Every token in your skill competes with conversation context. Be ruthlessly concise.

Ask for each paragraph:

Does Claude genuinely need this?
Could this be in references/ instead of main SKILL.md?
Is this duplicating information Claude already knows?

2. Progressive Disclosure

Load information in layers:

Layer	When Loaded	Target Size	Content
Metadata	Always	40-55 tokens	name + description
SKILL.md	When triggered	<5k words	Instructions, patterns
Resources	As needed	Variable	scripts/, references/, assets/

3. Freedom Levels

Match instruction specificity to error probability:

High Freedom (text instructions)

For flexible approaches where multiple solutions work
Example: "Structure components for reusability"

Medium Freedom (pseudocode/patterns)

For preferred patterns with some flexibility
Example: Show a pattern with [CUSTOMIZE] placeholders

Low Freedom (specific scripts/templates)

For fragile operations where exact steps matter
Example: Exact wrangler.jsonc configuration for D1 binding

Writing Effective Descriptions

The description is the most critical part - it determines if your skill gets discovered.

Target: 250-350 Characters

# Too short (loses context):
description: "A skill for Tailwind"  # ❌ 25 chars

# Too long (wastes tokens):
description: "This comprehensive skill provides detailed knowledge..."  # ❌ 500+ chars

# Just right:
description: |
  Build modern UIs with Tailwind v4 + shadcn/ui. Covers CSS variable theming,
  component installation, dark mode, and semantic color tokens.

  Use when: setting up Tailwind v4, adding shadcn components, fixing theme issues,
  or troubleshooting "Cannot find module" errors.

Two-Paragraph Structure

Paragraph 1: What you can build + key features (active voice) Paragraph 2: When to use + error keywords for discovery

Description Checklist

Active voice ("Build X" not "This skill provides X")
Specific technologies named
3-5 "Use when" scenarios
2-3 distinctive error messages/keywords
No meta-commentary about the skill itself
250-350 characters total

Bad vs Good Examples

# ❌ Bad: Passive, vague, no discovery keywords
description: |
  This skill helps you with database operations. It provides patterns
  for working with data and can be useful in many situations.

# ✅ Good: Active, specific, discoverable
description: |
  Build type-safe database queries with Drizzle ORM and Cloudflare D1.
  Covers schema definition, migrations, relations, and transaction patterns.

  Use when: setting up D1 database, writing Drizzle schemas, debugging
  "no such table" or "D1_ERROR" issues.

Skill Structure

Required Files

skills/my-skill/
├── SKILL.md          # Main documentation (required)
└── README.md         # Auto-trigger keywords (required)

Optional Resources

skills/my-skill/
├── scripts/          # Executable helpers
│   └── setup.sh      # Example: automated setup script
├── references/       # Extended documentation
│   └── api-guide.md  # Loaded when user needs deep details
└── assets/           # Templates, images
    └── config.json   # Template files for output

When to Use Each

scripts/: Deterministic tasks that must be exact

Database migrations
Project scaffolding
Configuration generation

references/: Extended documentation too long for SKILL.md

Full API references
Comprehensive troubleshooting guides
Migration guides between versions

assets/: Template files for output

Configuration file templates
Boilerplate code
Images/diagrams

YAML Frontmatter

Required Fields

---
name: lowercase-hyphen-case
description: |
  [250-350 chars with "Use when:" section]
---

Optional Fields

---
name: my-skill
description: |
  [description - max 1024 chars]
allowed-tools:
  - Bash
  - Read
  - Write
---

Note: allowed-tools is an optional field to restrict which tools Claude can use. The metadata: field with keywords: array is commonly used in this repository for improved discoverability, though it's not officially documented in the Anthropic spec. Fields like license: are informational but not functionally used by Claude Code.

Field Guidelines

name: Lowercase letters, numbers, hyphens only. Max 64 chars. Gerund form recommended (e.g., processing-pdfs)
description: Max 1024 chars. Must include what it does AND when to use it. Third-person perspective.
allowed-tools: Restricts which tools Claude can use when skill is active (rare, optional)

Common Mistakes

1. Description Too Vague

# ❌ Won't be discovered
description: "Helps with authentication"

# ✅ Will be discovered
description: |
  Implement authentication with Clerk - React components, middleware,
  and Cloudflare Workers integration with JWT verification.

  Use when: adding auth to React apps, protecting API routes, or
  troubleshooting "clerk/backend" import errors.

2. Duplicating Claude's Knowledge

# ❌ Claude already knows JavaScript basics
## Variables
Use `const` for constants and `let` for variables...

# ✅ Focus on what Claude might get wrong
## Critical: Cloudflare Workers Differences
- No `process.env` - use `env` parameter from fetch handler
- No Node.js `fs` module - use R2 or KV for storage

3. Missing Error Keywords

Skills are often triggered when users hit errors. Include common error messages:

description: |
  ...
  Use when: troubleshooting "Cannot read properties of undefined",
  "NEXT_REDIRECT" errors, or hydration mismatches.

4. Overly Rigid Instructions

# ❌ Too rigid (breaks if API changes)
Always call api.configure({ version: "2.1.0" }) first.

# ✅ Flexible with rationale
Configure the API client before making calls. The version should match
your installed package version (check package.json).

5. No Production Validation

Skills should be tested in real projects, not just theoretically correct:

## Production Example

Tested in [Project Name]:
- Build time: 45 seconds
- Errors prevented: 6/6 documented issues
- Zero runtime errors after deployment

Token Efficiency

Measuring Efficiency

Compare tokens used with vs without skill:

Metric	Without Skill	With Skill	Savings
Setup tokens	~15k	~5k	67%
Errors hit	2-3	0	100%
Iterations	3-4	1	75%

Optimization Techniques

Move examples to references/: Keep SKILL.md under 5k words
Use code blocks strategically: One good example > three mediocre ones
Link don't duplicate: Reference official docs instead of copying
Prune ruthlessly: If Claude knows it, don't include it

Testing Your Skill

Discovery Test

Ask Claude Code naturally:

"Help me set up [technology your skill covers]"

Claude should propose using your skill. If not:

Check description has relevant keywords
Verify README.md has auto-trigger keywords
Ensure skill is symlinked to ~/.claude/skills/

Functionality Test

Build a real project using only the skill's guidance:

Did you need to search for additional information?
Did you hit any errors the skill should have prevented?
Was any instruction unclear or wrong?

Verification Script

./scripts/check-metadata.sh <skill-name>

Quality Checklist

Before committing a skill:

Name is lowercase-hyphen-case, max 40 chars
Description is 250-350 chars with "Use when:" section
SKILL.md under 5k words
All code examples tested and working
Package versions verified current
Known issues documented with sources (GitHub issues, etc.)
Production tested (not just theoretically correct)
README.md has auto-trigger keywords
Symlinked and discoverable

References

Official Spec: https://github.com/anthropics/skills/blob/main/agent_skills_spec.md
Our Standards: planning/claude-code-skill-standards.md
Checklist: ONE_PAGE_CHECKLIST.md
Example Skills: skills/tailwind-v4-shadcn/, skills/cloudflare-d1/

Quick Command Reference

# Create new skill
/create-skill my-skill-name

# Install skill
./scripts/install-skill.sh my-skill-name

# Verify metadata
./scripts/check-metadata.sh my-skill-name

# Check all skills
./scripts/check-all-versions.sh

# Generate marketplace manifest
./scripts/generate-plugin-manifests.sh my-skill-name

skill-creator

Skill Creator

Quick Start

More from evolv3ai/claude-skills-archive

winadmin-powershell

admin

mcp-server-management

snowflake-platform

azure-auth

tiptap