Skip to main content
Skill preloading injects full skill content into agent context when the agent starts. This gives agents domain-specific knowledge without requiring invocation or context loading during execution.

Why Preload?

Instant Availability

Skills are loaded once at startup, not fetched during execution.

Consistent Knowledge

Every agent invocation has the same baseline knowledge.

No Invocation Needed

Agent can reference skill content in every response automatically.

Context Efficiency

Load once vs. repeatedly fetching during conversation.

Basic Preloading

---
name: orchestrator
skills: ["pro-workflow", "api-conventions"]
---

Agent starts with Pro Workflow and API conventions already loaded.
What happens:
  1. Agent invoked (e.g., “Delegate to orchestrator”)
  2. Claude Code reads skills/pro-workflow/SKILL.md
  3. Claude Code reads skills/api-conventions/SKILL.md
  4. Full content of both skills injected into agent context
  5. Agent begins execution with skills available

Preloading vs On-Demand

FeaturePreloadedOn-Demand
Load TimeAgent startupWhen invoked
AvailabilityAlwaysAfter invocation
Context CostUpfrontDeferred
Use CaseCore knowledgeOccasional procedures
InvocationNone needed/skill or Skill()

Load Order

Skills load in the order specified:
---
name: implementer
skills:
  - "project-patterns"      # Loaded first
  - "api-conventions"       # Loaded second
  - "error-handling"        # Loaded third
---
If skills reference each other, list dependencies first.

Context Injection

Preloaded skills are injected as:
Agent System Prompt:

[Agent instructions from AGENT.md]

---

Preloaded Skills:

# Skill: pro-workflow

[Full content of skills/pro-workflow/SKILL.md]

---

# Skill: api-conventions

[Full content of skills/api-conventions/SKILL.md]

---

Examples

Planning Agent with Project Patterns

---
name: planner
tools: ["Read", "Glob", "Grep"]
skills: ["project-patterns"]
model: opus
---

# Planner

Create implementation plans following project patterns.
Skill: skills/project-patterns/SKILL.md
---
name: project-patterns
description: Common patterns in this codebase
---

# Project Patterns

## File Organization

- `src/routes/` — API endpoints
- `src/services/` — Business logic
- `src/db/` — Database queries

## API Endpoint Pattern

```typescript
export async function handler(req: Request, res: Response) {
  const validation = validateInput(req.body);
  if (!validation.success) {
    return res.status(400).json({ error: validation.error });
  }
  const result = await service.execute(validation.data);
  return res.status(200).json(result);
}

Now when planner creates plans, it knows:
- Where to place files
- How to structure endpoints
- Validation patterns to use

### Orchestrator with Multiple Skills

```yaml
---
name: orchestrator
tools: ["Read", "Glob", "Grep", "Bash", "Edit", "Write"]
skills:
  - "pro-workflow"
  - "project-patterns"
  - "testing-strategy"
model: opus
memory: project
---

# Orchestrator

Multi-phase development with Pro Workflow patterns, project structure knowledge, and testing strategy.
Orchestrator starts with:
  1. pro-workflow — Research > Plan > Implement workflow
  2. project-patterns — File organization and code patterns
  3. testing-strategy — When/how to write tests

Reviewer with Security Checklist

---
name: reviewer
tools: ["Read", "Grep", "Bash"]
skills: ["security-checklist", "performance-patterns"]
---

# Reviewer

Code review with security and performance focus.
Skills:
---
name: security-checklist
description: Security items to verify
---

# Security Checklist

## Input Validation
- [ ] All inputs validated
- [ ] SQL injection prevented
- [ ] XSS prevention

## Authentication
- [ ] Passwords hashed
- [ ] JWT expiry set
- [ ] CSRF tokens present

## Secrets
- [ ] No secrets in code
- [ ] Environment variables only
Reviewer automatically checks all items without being told.

Context Budget

Skill Size Guidelines

---
name: naming-conventions
---

# Naming

- camelCase: variables
- PascalCase: classes
- kebab-case: files
Impact: Negligible (~50 tokens)
---
name: api-conventions
---

# API Conventions

[Detailed patterns with examples]
Impact: Moderate (~200-500 tokens)
---
name: complete-architecture
---

# Complete Architecture Guide

[Extensive documentation]
Impact: High (>500 tokens)Recommendation: Split into smaller skills or use on-demand.

Total Context Budget

Base Context
number
default:"200000"
Claude Code context window: 200k tokens
Agent Prompt
number
default:"500-2000"
Agent system prompt: 500-2000 tokens
Preloaded Skills
number
default:"1000-5000"
3-5 skills: 1000-5000 tokens
Remaining
number
default:"190000+"
Available for conversation: 190k+ tokens
Limit to 3-5 skills per agent. More than 5000 tokens for skills is excessive.

Optimizing Skills

1. Concise Language

When you are implementing an API endpoint, it is very important to 
remember that you should always validate the user input before you 
process it, because if you don't validate the input, the user might 
send invalid data and cause errors in your application.
Cost: ~50 tokens

2. Examples Over Prose

## Error Handling

Our application uses custom error classes that extend the base Error 
class. Each error has a code property and a statusCode property. The 
code is a string identifier like 'NOT_FOUND' and the statusCode is the 
HTTP status code to return, like 404.
Cost: ~50 tokens

3. Split Large Skills

Instead of:
skills: ["complete-api-guide"]  # 3000 tokens
Use:
skills:
  - "api-routes"           # 500 tokens
  - "api-auth"             # 500 tokens
  - "api-errors"           # 500 tokens
  # Total: 1500 tokens
Then preload only what’s needed per agent:
# Planning agent
skills: ["api-routes"]

# Implementation agent
skills: ["api-routes", "api-errors"]

# Review agent
skills: ["api-auth", "api-errors"]

Conditional Preloading

Load different skills based on agent purpose:
---
name: frontend-agent
skills:
  - "react-patterns"
  - "css-conventions"
  - "component-structure"
---

Verification

Check what skills are preloaded:
# View agent configuration
cat .claude/agents/orchestrator.md | grep -A 5 'skills:'

# Check skill exists
ls .claude/skills/pro-workflow/SKILL.md

# Estimate skill size
wc -w .claude/skills/pro-workflow/SKILL.md
# Rough token estimate: word_count * 1.3

# Total preloaded size
for skill in pro-workflow api-conventions; do
  echo -n "$skill: "
  wc -w .claude/skills/$skill/SKILL.md | awk '{print int($1 * 1.3) " tokens"}'
done

Best Practices

Limit Per Agent

3-5 skills max. More than that bloats context.

Load What's Needed

Only preload skills the agent will actually use.

Keep Skills Small

Target <1000 tokens per skill. Split large skills.

Examples Required

Every pattern needs a code example. Prose alone isn’t enough.

Next Steps

Skill Frontmatter

Configure skill metadata

Agent Skills

Configure agent skill preloading

Skill Discovery

How skills are found and loaded

Creating Skills

Build custom skills

Build docs developers (and LLMs) love