playbook/outfitter-agents/plugins/outfitter/skills/claude-skills/references/performance.md

Performance Considerations

Token impact and optimization strategies for Claude Code skills.

Token Impact

Every skill activation loads the full SKILL.md into context.

SKILL.md Size	Approximate Tokens
100 lines	~700 tokens
300 lines	~2,000 tokens
500 lines	~3,500 tokens
1,000 lines	~7,000 tokens
1,500 lines	~10,000 tokens

Rule: Keep SKILL.md under 500 lines. Use progressive disclosure for details.

Progressive Disclosure

Move details out of SKILL.md:

skill-name/
+-- SKILL.md           # Core workflow (~300 lines)
+-- references/        # Deep-dive docs
|   +-- patterns.md
|   +-- edge-cases.md
+-- examples/          # Worked examples

Loading pattern:

1. SKILL.md loads on activation (~2,000 tokens)
2. References load only when explicitly needed
3. Examples load only for clarification

Tool Restrictions Reduce Latency

Without allowed-tools: Claude asks permission for each tool. With allowed-tools: Listed tools run immediately.

# Fast (no permission prompts)
allowed-tools: Read Grep Glob

# Slower (prompts for unlisted tools)
# (no allowed-tools field)

Context Mode Optimization

When to Fork

Scenario	Recommendation
Verbose intermediate work	Fork (keeps main context clean)
Parallel independent tasks	Fork (run simultaneously)
Building on conversation	Inherit (needs prior context)
Simple one-shot task	Either (fork slightly cleaner)

Fork trades context sharing for isolation. Each fork starts fresh.

Fork Overhead

Each forked skill invocation:

• Loads skill instructions fresh
• No conversation history
• Returns only final output

Benefit: Main context stays lean Cost: No state sharing between forks

Description Efficiency

Descriptions load into system prompt for every message. Keep them concise.

# Good: Concise, specific
description: Parse PDF files for text extraction. Use when working with .pdf files.

# Bad: Verbose, redundant
description: This skill is designed to help you parse and extract text content from PDF files. It can be used whenever you need to work with PDF documents, extract text, or process PDF files for analysis.

Activation Efficiency

Auto-Activation

Claude evaluates skill descriptions against user input. More specific descriptions activate faster (fewer false considerations).

# Specific (fast match)
description: Extract tables from Excel .xlsx files

# Vague (many false considerations)
description: Work with files and data

Manual Activation

For skills that shouldn't auto-activate:

disable-model-invocation: true

Requires explicit Skill tool call. Avoids description evaluation overhead.

Caching

Skills are cached per session. Changes require:

/clear

Or start a new session.

Optimization Checklist

• SKILL.md under 500 lines
• Details in references/
• Specific description with trigger keywords
• allowed-tools for frequently-used tools
• context: fork for verbose processing
• disable-model-invocation: true for manual-only skills