Claude Code Skills: Best Practices and the Meta-Skill Framework

Research Date: 2026-01-20 Source URL: https://x.com/doodlestein/status/2011468541321744512

Reference URLs

• Original X Post - Jeffrey Emanuel
• Best Practices Guide
• meta_skill Repository
• Creating Share Images Skill
• Crafting README Files Skill
• Official Anthropic Docs - Skill Best Practices
• Claude Code Skills Documentation
• anthropics/skills Repository

Summary

Jeffrey Emanuel (@doodlestein) published a widely-engaged post (33.8K views, 1035 bookmarks) on January 15, 2026, advocating for frequent creation of SKILL.md files when using Claude Code. The core recommendation involves having Claude read a comprehensive best practices guide before generating skills, which reportedly improves skill quality. Emanuel shared the guide from the meta_skill repository—a Rust CLI tool for managing Claude Code skills that includes indexing, building, bundling, and sharing capabilities.

The best practices guide synthesizes documentation from official Anthropic sources, Claude Code documentation, the anthropics/skills repository, and community analysis from 2025-2026. It provides detailed technical architecture explanations, structural requirements, design principles, and anti-patterns. The guide emphasizes that skills function as “onboarding guides for specialized tasks”—modular instruction packages that Claude loads dynamically when contextually relevant.

The practical workflow recommendation is to create skills whenever a task is repeated across multiple projects, with Emanuel suggesting skill creation “a couple times a day at least” for active developers. Two example skills demonstrate the pattern: one for generating social media link previews (Open Graph/Twitter Card metadata) and another for crafting GitHub README files.

Technical Architecture

Mental Model: Skills vs CLAUDE.md

Skills occupy a distinct architectural niche compared to project-level configuration files. The following table illustrates the fundamental differences:

CLAUDE.md is appropriate for unchanging conventions, coding standards, and always-on project rules. Skills are appropriate for complex workflows, scripts, templates, and domain expertise activated contextually.

Token Loading Hierarchy

Skills implement a three-level progressive loading architecture:

This hierarchy enables efficient context window utilization by loading only what is necessary at each stage.

Selection Mechanism

The skill selection mechanism operates through pure LLM reasoning rather than algorithmic matching. Claude evaluates all skill descriptions via natural language understanding—no embeddings, classifiers, or keyword-matching are involved. This architectural decision has several implications:

• Description quality is critical for reliable triggering
• Vague descriptions result in skills that never trigger
• Specific trigger phrases enable reliable activation

Execution Model

Skills use a dual-message injection pattern:

1. Metadata message (isMeta: false) — visible to user as status indicator
2. Skill prompt message (isMeta: true) — hidden from UI, sent to API

This pattern provides transparency to users without displaying instruction walls in the chat interface.

Required Structure

Directory Layout

skill-name/
├── SKILL.md           # Required - instructions + frontmatter
├── scripts/           # Optional - executable code
│   └── validate.py
├── references/        # Optional - docs loaded into context
│   ├── api.md
│   └── schema.md
└── assets/            # Optional - files used in output (not loaded)
    └── template.docx

Frontmatter Requirements

The YAML frontmatter requires two fields:

---
name: processing-pdfs        # Required: lowercase, hyphens only
description: >-              # Required: what + when to use
  Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when user mentions PDFs, forms,
  or document extraction.
---

Validation rules:

• name: ≤64 characters, [a-z0-9-] only, cannot contain “anthropic” or “claude”
• description: ≤1024 characters, non-empty, no XML tags

Body Guidelines

The SKILL.md body contains instructions Claude follows after skill triggers. Target length is under 500 lines. When exceeding this threshold, content should be split into reference files.

Core Design Principles

Principle 1: Conciseness

Context window space is a shared resource. Every token competes with conversation history, other skills, and user requests. The default assumption should be that Claude is already intelligent—only add what Claude does not inherently know.

Example comparison:

# Inefficient (~150 tokens) - explains obvious concepts
PDF (Portable Document Format) files are a common file format that
contains text, images, and other content. To extract text from a PDF,
you'll need to use a library. There are many libraries available...

# Efficient (~50 tokens) - assumes competence
## Extract PDF text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

The guiding question for each line: "Does Claude need this? Does this justify its token cost?"

### Principle 2: Progressive Disclosure

Never front-load everything. Structure for on-demand loading:

```markdown
# In SKILL.md - overview + pointers

## Quick start
[Essential code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)

Claude loads FORMS.md only when the user needs forms functionality.

Critical rules:

• Keep references one level deep from SKILL.md
• Avoid chains: SKILL.md → advanced.md → details.md (Claude may partial-read)
• Long files (>100 lines): include table of contents at top

Principle 3: Degrees of Freedom

Match specificity to task fragility:

Analogy: A narrow bridge with cliffs requires low freedom (exact guardrails). An open field permits high freedom (general direction only).

Writing Effective Descriptions

The description is the sole triggering mechanism. Claude uses it to select from potentially 100+ available skills.

Description Rules

1. Third person always — “Processes Excel files” not “I can help you” or “You can use this”
2. Specific + trigger phrases — Include what it does AND when to invoke
3. Key terms for discovery — Use synonyms the user might say

Examples

# Effective - specific, includes triggers
description: >-
  Analyze Excel spreadsheets, create pivot tables, generate charts.
  Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

# Effective - action + context
description: >-
  Generate descriptive commit messages by analyzing git diffs.
  Use when user asks for help writing commit messages or reviewing staged changes.

# Ineffective - vague
description: Helps with documents
description: Processes data
description: Does stuff with files

Bundled Resources

scripts/ — Executable Code

When to use: Same code rewritten repeatedly, deterministic reliability needed.

scripts/
├── rotate_pdf.py
├── validate_form.py
└── extract_text.py

Benefits:

• Token efficient (executed without loading into context)
• Deterministic (no generation variance)
• Consistent across uses

In SKILL.md, distinguish intent:

# Execute (most common)
Run `python scripts/validate.py input.pdf`

# Read as reference (rare, for complex logic)
See `scripts/validate.py` for the validation algorithm

references/ — Context-Loaded Documentation

When to use: Documentation Claude should reference while working.

references/
├── schema.md      # Database schemas
├── api.md         # API specifications
├── policies.md    # Company rules
└── patterns.md    # Domain patterns

Design pattern for multi-domain skills:

# In SKILL.md
## Available datasets
- **Finance**: Revenue, ARR → See [references/finance.md](references/finance.md)
- **Sales**: Pipeline, accounts → See [references/sales.md](references/sales.md)

## Quick search
```bash
grep -i "revenue" references/finance.md

For large files (>10k words), include grep patterns in SKILL.md for targeted access.

### assets/ — Output Files (Not Loaded)

**When to use:** Files used in output, not instruction context.

assets/ ├── logo.png ├── template.pptx ├── font.ttf └── boilerplate/

Claude references by path, copies/modifies—never loads into context.

## Workflow Patterns

### Checklist Pattern (Complex Multi-Step)

```markdown
## Form filling workflow
Copy and track progress:

- [ ] Step 1: Analyze form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)

**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`

Feedback Loop Pattern (Quality-Critical)

## Validation loop
1. Make edits to document
2. **Validate immediately**: `python scripts/validate.py output/`
3. If validation fails:
   - Review error message
   - Fix issues
   - Run validation again
4. **Only proceed when validation passes**

Template Pattern

## Report structure
ALWAYS use this template:

# [Analysis Title]

## Executive summary
[One-paragraph overview]

## Key findings
- Finding 1 with data
- Finding 2 with data

## Recommendations
1. Actionable recommendation

Anti-Patterns

Content to Exclude

Skills should not include:

• README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
• User-facing documentation
• Setup/testing procedures
• Auxiliary context about creation process

Skills are for AI agents, not humans.

Common Mistakes

Bad: Multiple Options Without Default

# Ineffective
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image..."

# Effective
"Use pdfplumber for text extraction: [code]
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

Advanced Patterns

”THE EXACT PROMPT” Pattern

Encode reproducible prompts in all-caps sections for agent-to-agent handoff:

## THE EXACT PROMPT — Plan Review

Carefully review this entire plan for me and come up with your best
revisions in terms of better architecture, new features...

Benefits:

• Prompts are copy-paste ready
• Stream Deck / automation friendly
• No ambiguity about phrasing
• Enables cross-model workflows (GPT Pro → Claude Code)

Risk Tiering Tables

For safety/security skills, use explicit tier classifications:

Robot Mode / Machine-Readable Output

For orchestration tools, document JSON/NDJSON APIs:

## Robot Mode (AI Automation)
```bash
ntm --robot-status    # Sessions, panes, agent states
ntm --robot-snapshot  # Unified state: sessions + beads + mail

Output format:

{"type":"request_pending","request_id":"abc123","tier":"dangerous"}

## Common Skill Archetypes

### CLI Reference Skill

**Structure:**
```markdown
# Tool Name Skill

## Authentication
[auth commands]

## Core Operations
[main commands grouped by function]

## Common Workflows
[multi-step recipes]

Token efficiency approach: Pure reference, minimal prose. Claude already knows CLI semantics.

Methodology Skill

Structure:

# Methodology Name

> **Core Philosophy:** [one-liner insight]

## Why This Matters
[brief motivation]

## THE EXACT PROMPT
[copy-paste ready prompt]

## Why This Prompt Works
[technical breakdown]

## Before/After Examples
[concrete demonstrations]

Safety Tool Skill

Structure:

# Tool Name

## Why This Exists
[threat model]

## Critical Design Principles
[architecture decisions]

## What It Blocks / Allows
[tables of patterns]

## Security Considerations
[limitations, threat model assumptions]

Practical Workflow Recommendation

Emanuel’s workflow recommendation:

1. Identify repetition — When explaining the same thing to Claude across multiple projects, that is a skill candidate
2. Have Claude read the guide first — Before skill creation, instruct Claude to read the best practices document
3. Create skills frequently — Target “a couple times a day at least” for active development
4. Use progressive disclosure — Include reference files in the skill directory for token efficiency

Example Skills from Emanuel

Social Media Preview Skill (creating-share-images):

• Handles Open Graph and Twitter Card metadata generation
• Ensures link previews display correctly on X, Telegram, WhatsApp, Facebook, iMessage

README Writing Skill (crafting-readme-files):

• Generates consistent GitHub README files
• Uses reference files for structure templates

Both skills demonstrate the pattern of including additional reference files in the skill directory for progressive disclosure.

Key Findings

• Skills function as dynamically-loaded, task-specific instruction packages that transform Claude from general-purpose to domain-expert
• The description field is the sole triggering mechanism, operating through LLM reasoning rather than algorithmic matching
• Token efficiency is achieved through a three-level progressive loading hierarchy (metadata → body → resources)
• Effective skills target under 500 lines in SKILL.md with reference files for extended content
• The meta_skill repository provides both best practices documentation and a Rust CLI for skill management
• Frequent skill creation (multiple times per day) is recommended when patterns emerge across projects

References

1. Jeffrey Emanuel X Post - January 15, 2026
2. Dicklesworthstone/meta_skill Repository - Accessed January 20, 2026
3. Best Practices for Writing and Using SKILL.md Files - Accessed January 20, 2026
4. Skill Authoring Best Practices - Anthropic Docs
5. Agent Skills - Claude Code Docs
6. anthropics/skills Repository
7. Claude Skills Deep Dive - Lee Han Chung
8. Claude Code Customization Guide - alexop.dev