[FEATURE] Pre-built/compiled skills: Why they don't exist and what could be

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Pre-built/compiled skills: Why they don't exist and what could be

"If Anthropic provides pre-built Agent Skills for common document tasks (e.g. PDF), why can't we take a custom skill like 'name' and prebuild it so it is available immediately?"

This document explores the architectural differences between built-in and custom skills, and proposes potential solutions for making custom skills as performant as built-in ones.

Why Anthropic's skills are different

Built-in skills (PDF, etc.):

• Compiled into Claude Code's system
• Part of the core toolset
• Available in the system prompt from the start
• No file I/O required

Custom skills (your naming skill):

• File-based (SKILL.md in a directory)
• Must be read from disk when invoked
• Loaded into context dynamically
• Uses token budget when read

What COULD exist but doesn't (yet)

1. Skill pre-compilation

# Hypothetical command
claude-code compile-skill .claude/skills/name

# Outputs: .claude/skills/name.compiled
# Would be loaded like built-in skills

This could:

• Convert skill docs into optimized format
• Cache them at system level
• Make them instantly available like built-in skills

2. Prompt caching for skills

Claude API has prompt caching that can cache large portions of context:

{
  "system": [
    {
      "type": "text",
      "text": "You are Claude Code...",
      "cache_control": {"type": "ephemeral"}
    },
    {
      "type": "text",
      "text": "[ENTIRE NAMING SKILL CONTENT]",
      "cache_control": {"type": "ephemeral"}
    }
  ]
}

This could:

• Cache skill content for ~5 minutes
• Reuse cached version across sub-agents
• Near-instant loading after first use

Why it might not be exposed:

• Caching adds complexity
• Users might not understand cache invalidation
• File-based skills are simpler conceptually

3. Skill "warming"

# Hypothetical command
claude-code warmup --skills=name,python,test

# Pre-loads skills into session cache

4. Binary skill format

Similar to Python's .pyc files:

.claude/skills/name/
  ├── SKILL.md          # Source
  └── .skill.cache      # Compiled cache

Why this doesn't exist currently

Possible reasons:

1. Simplicity: File-based skills are easy to understand and edit
2. Cache invalidation: "There are only two hard things..." - caching is one of them
3. Development priority: Claude Code is relatively new, advanced caching may come later
4. Token efficiency: Modern LLMs handle context well, so the performance hit might be acceptable
5. Freshness: Always reading from disk ensures latest version

What you CAN do right now

Workaround 1: Minimize skill size (recommended)

By consolidating principles into SKILL.md, we reduced load time significantly:

• Before: Read SKILL.md + 4-5 other files
• After: Read SKILL.md only (most cases)

Implementation:

• Put essential principles directly in SKILL.md
• Keep detailed examples in separate files
• Only read additional files for edge cases

Workaround 2: Session-level caching

Start a conversation, load the skill once, then keep that conversation running:

# In a long-running Claude Code session
# Load skill at the start
/name

# Now all subsequent naming questions are fast
# Context persists in this conversation

Workaround 3: Include in system prompt (manual)

For projects where naming is critical, you could manually add key principles to your project's CLAUDE.md:

## Naming principles (always apply)

### Classes: Name what it IS
- ❌ FileLoader → ✅ TextFile
- ❌ SongGenerator → ✅ Song

### Functions: One level higher
- Describe purpose, not implementation
- Resilient to change

This gets loaded with project context automatically.

Workaround 4: Global skills directory

Make frequently-used skills available globally:

# Symlink to global location
ln -s /Users/mikemindel/Projects/ai/code-fu/.claude/skills/name ~/.claude/skills/name

# Now available in all projects

Feature request potential

This is definitely something worth suggesting to Anthropic:

Feature: Pre-compiled/Cached Skills

• Allow skills to be "compiled" or cached
• Make them available instantly like built-in skills
• Useful for:
• Sub-agents (no re-reading)
• Large skill libraries
• Team-wide standardization

You could open a GitHub issue: https://github.com/anthropics/claude-code/issues

The fundamental difference

┌─────────────────────────────────────────┐
│ Built-in skills (PDF, etc)              │
│ • Part of Claude Code binary            │
│ • Loaded at startup                     │
│ • Always available                      │
│ • No token cost                         │
└─────────────────────────────────────────┘
              vs
┌─────────────────────────────────────────┐
│ Custom skills (naming, etc)             │
│ • File-based                            │
│ • Loaded on demand                      │
│ • Requires file read                    │
│ • Uses token budget                     │
└─────────────────────────────────────────┘

Performance comparison

Current state (custom skills)

User asks naming question
    ↓
Invoke /name skill
    ↓
Read SKILL.md from disk (~2-3 KB)
    ↓
Read supporting docs if needed (~20-30 KB total)
    ↓
Load into context (uses tokens)
    ↓
Generate response

Time: ~1-2 seconds for skill loading
Tokens: ~5,000-10,000 tokens for full skill

Ideal state (pre-compiled skills)

User asks naming question
    ↓
Access pre-loaded skill (already in context)
    ↓
Generate response

Time: Instant (no loading)
Tokens: 0 additional tokens (already cached)

Impact on sub-agents

This limitation particularly affects sub-agents:

Current behavior:

# Parent agent has skill loaded
parent_context = [skill_content, ...]

# Sub-agent starts fresh
sub_agent = Task(prompt="Name this class")
# ❌ Sub-agent must re-read skill files
# ❌ Duplicates token usage
# ❌ Slower invocation

Ideal behavior with caching:

# Parent agent has skill loaded and cached
parent_context = [skill_content, ...]

# Sub-agent inherits cached skills
sub_agent = Task(prompt="Name this class")
# ✅ Sub-agent uses cached skill
# ✅ No duplicate token usage
# ✅ Instant invocation

Proposed API

If Anthropic were to implement skill compilation/caching:

Command-line interface

# Compile a skill
claude-code compile-skill .claude/skills/name

# Compile all skills
claude-code compile-skill .claude/skills/*

# Clear skill cache
claude-code clear-skill-cache

# Warmup skills for session
claude-code warmup --skills=name,python,test

Configuration file

{
  "skills": {
    "preload": ["name", "python"],
    "cache": {
      "enabled": true,
      "ttl": 300,
      "strategy": "ephemeral"
    }
  }
}

Runtime behavior

// Automatic caching
skill.load('name', { cache: true, ttl: 300 })

// Force refresh
skill.load('name', { cache: false })

// Preload for sub-agents
task.create({
  preload_skills: ['name'],
  prompt: "Name this class"
})

Alternative architectures

1. Skill registry service

┌─────────────────────────────────────┐
│     Claude Code Skill Registry      │
│  • In-memory skill cache            │
│  • Shared across conversations      │
│  • Intelligent invalidation         │
└─────────────────────────────────────┘
           ↑
           │ (fast access)
           ↓
┌─────────────────────────────────────┐
│     Claude Code Session             │
│  • References cached skills         │
│  • No disk I/O needed               │
└─────────────────────────────────────┘

2. Skill compilation step

# At skill development time
cd .claude/skills/name
claude-code skill compile

# Generates optimized format
# .skill.compiled - binary format
# .skill.index - quick reference
# .skill.meta - version, hash, etc.

3. Dynamic skill loading with cache layers

Request → L1 Cache (memory) → L2 Cache (disk) → Source files
           ↑ (instant)         ↑ (fast)         ↑ (slow)

Implementation challenges

1. Cache invalidation:

• How to detect when SKILL.md changes?
• File watching? Hash comparison? Timestamp?

2. Version management:

• What if skill updates while cached?
• How to handle breaking changes?

3. Cross-session sharing:

• Should cache persist across Claude Code restarts?
• Security implications of cached content?

4. Memory management:

• How many skills to keep in cache?
• Eviction policy (LRU, LFU, TTL)?

5. Debugging:

• How to debug when using cached vs. fresh content?
• Cache miss diagnostics?

Conclusion

The question exposes a real limitation in Claude Code's current architecture: custom skills cannot achieve the same performance characteristics as built-in skills.

While workarounds exist (consolidation, session persistence, manual inclusion), a proper solution would require:

1. Skill compilation or caching mechanism
2. Cross-agent context sharing
3. Intelligent cache invalidation
4. Developer-friendly tooling

This would be a valuable feature for:

• Power users building comprehensive skill libraries
• Teams standardizing on common practices
• Projects with complex domain knowledge
• Performance-critical applications

Current status: Feature doesn't exist, but architectural foundation suggests it's feasible.

Next steps:

• File feature request with Anthropic
• Continue optimizing custom skills (consolidation approach)
• Explore community workarounds
• Monitor Claude Code updates for caching features

References

• Claude Prompt Caching
• Claude Code Skills Documentation
• Claude Code GitHub Issues

Proposed Solution

$ claude-code compile-skill .claude/skills/name

Alternative Solutions

Claude Code could:

1. Read all custom skills at startup
2. Keep them in memory
3. Inject them into context when needed
4. No disk I/O during conversation

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

_No response_

Additional Context

_No response_