Developer working with Claude Code skills showing three pathways: reference files, scripts, and AI intelligence converging into an orchestrator pattern

Claude Code Skills Deep Dive Part 1

Imagine teaching an expert programmer a new specialty. You transform them from a generalist into a Kubernetes guru or a PlantUML wizard. Claude Code skills work the same way. They transform Claude from a capable generalist into a domain expert for specific tasks.

Most developers face a familiar challenge. Their first skills work beautifully until they start scaling. A 5KB skill balloons to 50KB. Response times slow to a crawl. Maintenance becomes a nightmare. Your once-elegant skill has become a bloated encyclopedia that loads thousands of lines of documentation you never use. (Check out this article on Claude Skills Conceptual Deep Dive.)

Now we say Claude Code Skills, but really Skills can be used with the Claude API, the Claude Desktop app, Claude Code and the Claude Agent SDK. Thus, Agentic Skills permeates the Anthropic ecosystem, and I think it might be as big as MCP or perhaps even bigger.

And, it now goes beyond just the Anthropic ecosystem Codex, Github Copilot and OpenCode have all announced support for Agentic Skills and have all updated their tools. There is even a marketplace for agentic skills that support Gemini, Aidr, Qwen Code, Kimi K2 Code, Cursor (14+ and counting) and more with Agentic Skill Support via a universal installer. I wrote the skilz universal skill installer that works with Gemini, Claude Code, Codex, OpenCode, Github Copilot CLI, Cursor, Aidr, Qwen Code, Kimi Code and about 14 other coding agents as well as the co-founder of the world’s largest agentic skill marketplace.

There’s a better way.

This two-part series reveals how to build skills that stay lean, fast, and maintainable as they grow in power. We start with fundamentals, then introduce the PDA (progressive disclosure architecture) pattern that lets you build skills that scale gracefully from simple helpers to production-grade automation.

In Part 1, you’ll learn:

What Claude Code skills are and how they work under the hood
How to create your first skill from scratch in under 5 minutes
The three core patterns that cover 90% of use cases
Why the PDA philosophy solves the skill scaling problem
How Claude Code natively supports efficient skill design
A simple decision framework for when to apply PDA

In Part 2 (coming next), we’ll dive deep into implementation:

Three advanced PDA techniques with complete, production-ready code
Real-world examples combining all techniques
Token efficiency analysis showing 80–95% savings
Common pitfalls and how to avoid them

Let’s start at the beginning.

Part 1: Claude Code Skills Fundamentals

What Are Claude Code Skills?

Claude Code skills are custom extensions that teach Claude new capabilities beyond its built-in tools. Think of it this way: Claude Code already knows dozens of programming languages and has powerful built-in tools (Read, Write, Edit, Bash, WebSearch). Skills add domain-specific expertise. They teach Claude “how to use PlantUML” or “how our company publishes to Notion.”

The key difference: built-in tools are always available, but skills activate on-demand when needed.

What Skills Can Do:

Generate specialized content (diagrams, reports, technical documentation)
Integrate with external services (Notion, Confluence, Jira, Slack)
Automate multi-step workflows (convert markdown → PDF → upload → notify)
Provide domain expertise (company processes, internal tools, specialized formats)
Extend Claude’s capabilities (custom file formats, proprietary APIs, legacy systems)
Expert on Software Engineering Documentation (PRD, Design, Architecture)

Example — The Power of Skills:

Without Skills:

User: "Generate a PlantUML sequence diagram for OAuth flow"
Claude: "I can help write PlantUML syntax. Here's a basic example,
        though I may not know all the specialized patterns..."

With PlantUML Skill:

User: "Generate a PlantUML sequence diagram for OAuth flow"
Claude: [Activates plantuml skill]
        "Here's your sequence diagram with proper syntax,
        optimized formatting, and rendered to PNG."

The difference? The skill provides focused, expert-level knowledge. Claude goes from “I can probably help” to “I’m a PlantUML specialist.”

How Skills Work Under the Hood

When you invoke a skill, an elegant process happens behind the scenes:

What Happens During Activation:

Claude recognizes that the request matches a skill’s domain
The skill’s markdown file loads into Claude’s active context
Content becomes part of Claude’s working knowledge, like a specialist consultant joining the conversation
Claude executes the task using the skill’s guidance and patterns
The skill knowledge persists throughout the conversation (no need to reload)

The Key Insight:

Skills are prompt extensions. When you activate a skill, you dynamically inject specialized instructions into Claude’s context. It’s not a separate system or plugin. It’s well-organized text that makes Claude smarter for specific tasks.

Skills Have a Directory Structure:

.claude/skills/
├── plantuml/
│   ├── skill.md              # Main skill instructions
│   ├── scripts/              # Executable scripts
│   │   └── render.sh
│   └── references/           # Documentation and resources
│       └── syntax-guide.md
├── notion-uploader/
│   ├── skill.md
│   └── scripts/
│       └── upload.py
└── pdf-converter/
    ├── skill.md
    └── references/
        └── conversion-options.md

Each skill has its own directory containing a SKILL.md file with the main instructions. Skills can reference executable scripts under ./scripts, additional markdown documentation under ./references, and other resources as needed. This structure keeps skills organized and allows them to leverage external tools and documentation without bloating the main skill file.

Creating Your First Skill

Let’s build a simple skill from scratch to see how easy it is. We’ll create a “greeting-formatter” that formats messages in different professional styles.

Step 1: Create the Skills Directory

mkdir -p .claude/skills

Step 2: Create Your Skill File

touch .claude/skills/greeting-formatter.md

Step 3: Write the Skill Instructions

Open greeting-formatter.md and add:

# Greeting Formatter Skill

Step 4: Register the Skill (Optional but Recommended)

Add to your .claude/CLAUDE.md to help Claude discover your skill:

## Available Skills

- **greeting-formatter**: Formats greetings in formal, casual, or enthusiastic styles for professional communication

This is an optional step, Claude should find your skill just by being in ~/.claude/skills or in your local project ./.claude/skills.

This registration tells Claude when to activate your skill proactively.

Step 5: Test Your Skill

Start Claude Code and try:

User: "Create a formal greeting for John Smith"
Claude: [Activates greeting-formatter skill]

"Here's your formal greeting:
Dear John Smith, I hope this message finds you well.
Would you like me to adjust the tone or add specific content?"



This skill formats greetings in various professional styles.

**When activated:**
1. Analyze the user's greeting request
2. Identify the requested style (formal, casual, enthusiastic)
3. Generate an appropriate greeting

**Styles:**
**Formal**:
- Template: "Dear [Name], I hope this message finds you well."
- Use case: Professional emails, business correspondence, executive communication

**Casual**:
- Template: "Hey [Name]! How's it going?"
- Use case: Friendly messages, team communication, informal check-ins

**Enthusiastic**:
- Template: "Hi [Name]!!! So great to hear from you! 🎉"
- Use case: Celebrations, positive announcements, team wins

**Process:**
1. Extract recipient name from user request
2. Determine style (or ask if unclear)
3. Format greeting using appropriate template
4. Present result with option to adjust

**Example Usage:**
- "Create a formal greeting for John Smith"
- "Write a casual greeting for my teammate Sarah"
- "Make an enthusiastic greeting for the whole engineering team"

Congratulations! You’ve just created your first Claude Code skill. In under 5 minutes, you taught Claude a new capability.

Anatomy of a Well-Designed Skill File

Let’s break down the structure that makes skills effective:

YAMLFRONTMATTER with name and description where the description 
has triggers when to use the skill. 

# [Skill Name]                    ← Clear, descriptive title

[Brief description]               ← What this skill does (1-2 sentences)

**When activated:**               ← Activation triggers and context
- [What requests trigger this skill]
- [What problems it solves]

**Process:**                      ← Step-by-step instructions
1. [Step 1]
2. [Step 2]
3. [Step 3] [inline or a link to a file in references]

**Examples:** (optional)          ← Sample inputs/outputs
- Example 1
- Example 2

**Best Practices:** (optional)    ← Guidelines for quality
- Guideline 1 [links to file in references]
- Guideline 2

**Error Handling:** (optional)    ← What to do when things fail
- If X happens, do Y
- Recovery strategies

Why This Structure Works:

Title and description: Helps Claude quickly assess relevance
Activation conditions: Clarifies when to use this skill versus others
Process steps: Provides clear, actionable guidance
Examples: Anchors understanding with concrete cases
Best practices: Ensures quality output
Error handling: Creates resilience and better user experience

This structure keeps skills organized, scannable, and easy to maintain.

Note: While you can create skills manually following the patterns above, there’s a much easier way! Claude Code includes a skill-creator skill that automates the entire process.

Using the Skill Creator:

User: "Use the Skill Creator to Create a skill for formatting JSON with 
syntax highlighting"

Claude: [Activates skill-creator skill]
  "I'll create a JSON formatter skill for you..."
  
  ✓ Created .claude/skills/json-formatter/
  ✓ Generated skill.md with proper structure
  ✓ Added examples and best practices
  ✓ Registered in CLAUDE.md
  
  "Your json-formatter skill is ready to use!"

The skill-creator handles:

Directory structure setup
SKILL.md file generation with proper formatting
Example usage and best practices
Testing recommendations

When to Use Manual Creation vs. Skill Creator:

Use skill-creator: For most skills, especially when you’re starting out or want consistency
Use manual creation: When learning skill structure, making quick prototypes, or needing fine-grained control

The patterns and structures discussed above remain valuable. They help you understand how skills work and enable you to customize skills generated by the skill-creator tool.

There is a plugin development plugin that includes a skill builder skill that is more complete.

Common Skill Patterns

Three patterns cover 90% of skill use cases. Master these, and you can build most skills you’ll need.

Pattern 1: Generator Skills

These skills create content from user descriptions.

# [Type] Generator Skill

**Purpose:** Generate [content type] from user requirements

**Process:**
1. Analyze user requirements and goals
2. Generate [content type] using domain best practices
3. Validate output for correctness and quality
4. Present to user with refinement options

**Examples:**
- Diagram generators (PlantUML, Mermaid, draw.io)
- Report generators (test reports, status reports)
- Code scaffolding (boilerplate, project structures)

Pattern 2: Integrator Skills

These skills enable Claude to connect to external services.

# [Service] Integration Skill

**Purpose:** Integrate with [external service]

**Process:**
1. Understand user's goal and requirements
2. Prepare data in format required by [service]
3. Call [tool/script/API] to perform action
4. Handle response (success, errors, warnings)
5. Report results to user with actionable details

**Examples:**
- Notion uploader (publish documentation)
- Confluence publisher (team knowledge base)
- Jira ticket creator (project management)

Pattern 3: Converter Skills

These skills transform content between formats.

# [Format A] to [Format B] Converter

**Purpose:** Convert content between formats

**Process:**
1. Read source file
2. Parse [Format A] structure
3. Transform to [Format B] structure
4. Write output file
5. Verify conversion accuracy and completeness

**Examples:**
- Markdown to PDF (professional documents)
- Jupyter notebook to Python script (code extraction)
- DOCX to Markdown (content migration)

Pattern Recognition:

Need to create something? → Generator pattern
Need to connect to an external service? → Integrator pattern
Need to transform between formats? → Converter pattern

Most complex skills combine these patterns. For example, a “documentation publisher” might generate diagrams (generator), convert to PDF (converter), and upload to Notion (integrator).

Best Practices for Basic Skills

When creating your first skills, follow these proven guidelines:

Do:

✅ Write clear, numbered steps: Claude follows sequential instructions well
✅ Provide concrete examples: Show expected inputs and outputs
✅ Keep it concise: 2–5KB for simple skills is ideal
✅ Single responsibility: One job, well-defined
✅ Document edge cases: Guide Claude on uncommon situations

Don’t:

❌ Embed massive documentation: (We’ll solve this with PDA in Part 2!)
❌ Try to cover every edge case: Focus on the common path first
❌ Make it too generic: “Handle all diagrams” is worse than “Handle PlantUML sequence diagrams”
❌ Forget error handling: Always tell Claude what to do when things fail

The 5KB Rule:

If your skill grows beyond 5KB, you’re probably:

Including too much reference documentation (solution: PDA lazy loading)
Covering too many use cases (solution: split into focused skills)
Documenting every edge case (solution: leverage Claude’s intelligence)

We’ll tackle the documentation problem with PDA shortly.

Using Skills Effectively

Activation Methods:

Method 1: Explicit Invocation (via command):

User: Use the skill plantuml to...

Method 2: Natural Language (Claude recognizes the need):

User: "Generate a sequence diagram showing OAuth flow"
Claude: [Automatically activates plantuml skill]

Method 3: CLAUDE.md Guidance (proactive activation):

Add to your .claude/CLAUDE.md:

## Skills Usage Policy

Proactively activate these skills when:
- **plantuml**: User asks for diagrams or architecture visuals
- **notion-uploader**: User wants to publish documentation
- **pdf-converter**: User needs to work with PDF files

This tells Claude when to activate skills without explicit requests automatically.

Skills in Multi-Step Workflows:

Skills chain together naturally for complex workflows:

User: "Create a diagram and upload it to Notion"
Claude:
  1. [Activates plantuml skill] → Generates diagram
  2. [Activates notion-uploader skill] → Uploads to Notion
  "✓ Diagram created and uploaded: [URL]"

Skill Composition:

Skills can invoke other skills to create powerful pipelines:

# Document Publisher Skill

**Purpose:** Generate and publish technical documentation

**Process:**
1. Generate diagrams (activate plantuml skill)
2. Convert markdown to PDF (activate pdf-converter skill)
3. Upload to Notion (activate notion-uploader skill)
4. Send notification (activate slack-notifier skill)

See https://github.com/SpillwaveSolutions/plantuml/blob/main/SKILL.md to see a skill I use on a regular basis or https://github.com/SpillwaveSolutions/design-doc-mermaid/blob/main/SKILL.md. These are real examples of the SKILL file format and the directory layout for a skill.

This modular approach keeps individual skills focused while enabling sophisticated automation.

When NOT to Use Skills:

One-off tasks: Not worth the complexity of creating a skill
Built-in tools handle it: Don’t reinvent what already works
Too complex for instructions: Needs custom code or agent framework

Part 2: PDA Concepts

The Skill Scaling Problem

You’ve created basic skills. They work beautifully! But then reality hits:

Your PlantUML skill needs 50KB of syntax documentation for all diagram types
Your Notion skill needs detailed API documentation for 20 different operations
Your Confluence skill needs examples for every content type and edge case

What do you do?

Traditional Approach (The Encyclopedia):

# plantuml.md (50KB)

## Sequence Diagram Syntax
[8KB of detailed documentation]
## Class Diagram Syntax
[10KB of detailed documentation]
## ER Diagram Syntax
[7KB of detailed documentation]
## State Diagram Syntax
[6KB of detailed documentation]
## Activity Diagram Syntax
[8KB of detailed documentation]
... [11KB more for component, deployment, use case, timing, and network diagrams]

The Problems with This Approach:

Token Waste: Loads ALL documentation every time, even if you just want a simple flowchart. Also known as context rot!!
Slow Response: More tokens to process means longer wait times
Higher Costs: Every invocation uses maximum tokens regardless of need
Maintenance Nightmare: 50KB monolithic file is hard to update and test
Context Pollution: Unrelated documentation crowds out working space for actual task execution

Real-World Impact:

Let’s watch what happens when a user wants a simple flowchart:

User: "Create a flowchart showing the login process"
Traditional Skill Context Usage:
- Skill prompt loaded: 50KB (all diagram types)
- Actually needed: 5KB (flowchart syntax only)
- Token waste: 45KB (90% completely unused!)
- Response time: Slower due to unnecessary context

This happens every single time the skill runs. Load enough of these context rot skills and you have less context for Claude to do its job. It also just has more noise to signal problem. You are making it less accurate and slower.

The Core Problem:

The encyclopedia approach treats all knowledge as equally important. It can’t distinguish between “I need this now” and “I might need this someday.”

Introducing Progressive Disclosure Architecture (PDA)

The PDA Philosophy:

💡 “A skill should be an orchestrator, not an encyclopedia.”

Instead of cramming all knowledge into the skill, PDA separates concerns into four distinct roles:

Comparison showing traditional encyclopedia skill (50KB monolithic) versus PDA orchestrator skill (3KB core with lazy-loaded references and scripts)

Skill prompt (the orchestrator): Contains routing logic — “what to do when”
Reference files (the library): Hold detailed documentation, loaded on-demand
Scripts (the workers): Handle mechanical work like API calls and data processing
AI reasoning (the intelligence): Provides error handling, adaptation, and user experience

Visual Comparison: Encyclopedia vs Orchestrator

Token Efficiency in Action:

Let’s compare the same flowchart request:

Encyclopedia Approach:

Initial load: 50KB (everything)
Actually used: 5KB (flowchart syntax)
Wasted: 45KB (90%)

Orchestrator Approach:

Initial load: 3KB (skill routing logic)
On-demand load: 5KB (flowchart syntax only)
Total: 8KB
Savings: 84%

Now imagine the next request is for a sequence diagram. The encyclopedia still loads 50KB. The orchestrator loads 3KB + 8KB (sequence syntax) = 11KB. Still 78% savings.

The orchestrator adapts to what you need. The encyclopedia treats every request the same. If you are using a lot of skills on the same request and they are all poorly constructed, you could be wasting a lot of context space.

The Three Pillars of PDA

PDA isn’t a framework or library you install. It’s a design pattern built on three techniques that work together:

Pillar 1: Reference Files & Lazy Loading

Heavy documentation lives in separate files outside the skill. The skill loads only what’s needed, when needed.

Why This Matters:

Saves tokens by avoiding unnecessary loading (80–95% savings typical)
Faster response times (less context to process)
Easier maintenance (update specific reference files without touching skill logic)
Scales gracefully (add new references without bloating core skill)

Pillar 2: Scripts for Mechanical Work

API calls, data processing, and complex operations move to external scripts. The skill prompt stays focused on decision logic.

Why This Matters:

Scripts run outside Claude’s context (zero token cost for implementation details)
Reusable across skills and projects
Testable independently (unit tests, integration tests)
Language-appropriate (use Python for data processing, Bash for system ops)

Pillar 3: AI Resilience Layer

Claude provides the intelligence layer for edge cases, error interpretation, and user experience.

Why This Matters:

Handles ambiguity and unexpected situations gracefully
Interprets errors from scripts and references in user-friendly ways
Adapts to context (user skill level, project requirements)
Asks clarifying questions when needed

The Power of Combination:

Together, these three pillars create skills that are:

Token-efficient: Load only what’s needed (80–95% savings)
Fast: Minimal context processing overhead
Maintainable: Modular structure (easy updates)
Powerful: Combine AI intelligence with script automation
Resilient: Handle errors gracefully with great UX
Scalable: Add capabilities without sacrificing performance

How Claude Code Natively Supports PDA

Here’s the best news: You don’t need special tools, frameworks, or plugins for PDA. Claude Code’s built-in capabilities already provide everything you need.

Built-in PDA Support:

1. Read Tool (For Reference Files)

The Read tool enables natural lazy loading:

# In your skill prompt (plantuml.md) 
(it actaully goes in the description of the skill in the YAML FRONTMATTER).

**When user requests sequence diagram:**
  1. Use Read tool: .claude/skills/reference/plantuml_sequence.md
  2. Generate diagram using loaded syntax
  3. Execute rendering script
**When user requests class diagram:**
  1. Use Read tool: .claude/skills/reference/plantuml_class.md
  2. Generate diagram using loaded syntax
  3. Execute rendering script
**When user requests flowchart:**
  1. Use Read tool: .claude/skills/reference/plantuml_flowchart.md
  2. Generate diagram using loaded syntax
  3. Execute rendering script

The Read tool only executes when the skill decides to load that reference. Natural lazy loading with no framework overhead.

2. Bash Tool (For Scripts)

The Bash tool enables external script execution:

# In your skill prompt

**To generate diagram:**
  Execute: bash .claude/skills/scripts/generate_plantuml.sh [diagram_code]
**To upload to Notion:**
  Execute: python3 .claude/skills/scripts/upload_notion.py [file_path] [database_id]
**To convert to PDF:**
  Execute: bash .claude/skills/scripts/markdown_to_pdf.sh [markdown_file]

Scripts run as external processes. Their implementation details stay outside Claude’s context. Only inputs and outputs matter. Zero token cost for the script’s internal logic.

3. AI Reasoning (Built-in Intelligence)

Claude’s natural intelligence handles:

Decision-making: Which references to load based on user request analysis
Error interpretation: Translating script errors into user-friendly guidance
Graceful degradation: Handling errors with helpful suggestions
Context adaptation: Adjusting to user skill level and project needs
Clarification: Asking questions when requirements are ambiguous

PDA is Natural in Claude Code:

You’re not fighting against the system. You’re working with its design:

# plantuml.md (3KB core skill)

## PlantUML Diagram Generator
Analyze user request to determine diagram type.

**For sequence diagrams:**
  1. Read references/plantuml_sequence.md
  2. Generate PlantUML code using loaded syntax
  3. Bash: .claude/skills/scripts/plantuml.sh generate [code]
  4. Return image path to user

**For class diagrams:**
  1. Read references/plantuml_class.md
  2. Generate PlantUML code using loaded syntax
  3. Bash: .claude/skills/scripts/plantuml.sh generate [code]
  4. Return image path to user

**For flowcharts:**
  1. Read references/plantuml_flowchart.md
  2. Generate PlantUML code using loaded syntax
  3. Bash: .claude/skills/scripts/plantuml.sh generate [code]
  4. Return image path to user

This is PDA:

✅ Conditional reference loading (Read tool)
✅ Script execution (Bash tool)
✅ AI decision-making (natural reasoning)
✅ Error handling (AI interprets Bash output)

No special framework needed. You’re just using Claude Code’s built-in tools intelligently.

PDA in Action: A Simple Example

Let’s watch PDA work with a concrete example to see the efficiency gains:

User: "Create a sequence diagram for a login flow"

Claude (with PDA skill):
  1. [AI Reasoning] Analyzes request
     → Recognizes: user wants sequence diagram
     → Decision: load sequence diagram reference only
  2. [Read Tool] Loads targeted documentation
     → Executes: Read .claude/skills/reference/plantuml_sequence.md
     → Loaded: 8KB of sequence diagram syntax
     → Note: Did NOT load class, flowchart, ER, or state diagram references
  3. [AI Reasoning] Generates PlantUML code
     → Uses loaded syntax rules and best practices
     → Creates properly formatted sequence diagram code
     → Validates structure
  4. [Bash Tool] Generates image
     → Executes: .claude/skills/scripts/plantuml.sh generate login_flow.puml
     → Script runs PlantUML JAR (zero token cost for script internals)
     → Output: login_flow.png created successfully
  5. [AI Reasoning] Checks result
     → Script exit code: 0 (success)
     → Image file exists: verified
     → Reports success to user with path

Result: "✓ Created sequence diagram: login_flow.png"
Context Used:
- Skill prompt: 3KB (routing logic)
- Sequence reference: 8KB (loaded on-demand)
- Total: 11KB
Traditional Approach: 50KB (would've loaded everything)
Savings: 78%

What Happens Next?

If the next request is for a flowchart, the skill loads the 5KB flowchart reference instead. The skill adapts dynamically to each request’s needs.

Why This Works:

Intelligent routing: AI decides what to load based on context
Lazy loading: Only reference needed documentation
Script isolation: Implementation details stay outside token budget
Error resilience: AI interprets script output and handles failures gracefully

When to Apply PDA

Not every skill needs PDA. Here’s a simple decision framework:

Apply PDA When Your Skill:

✅ Has >10KB of reference documentation
✅ Supports multiple distinct use cases (each needs different docs)
✅ Integrates with external APIs or complex tools
✅ Requires mechanical processing (file conversion, API calls, data transformation)
✅ Will grow over time (more features means more documentation)
NOTE: If you do have a rather large skill, consider breaking it up into a set of related skills instead of having one giant skill with 100K of reference docs.

Stick with Basic Skills When:

✅ Total size <5KB (all instructions fit comfortably)
✅ All information is always needed (no conditional logic benefit)
✅ Simple workflow (no external scripts or APIs needed)
✅ Stable and focused (won’t grow significantly)

Quick Self-Assessment:

Answer these questions about your skill:

Would my skill prompt exceed 10KB with all documentation?

Yes → Consider PDA (reference files will help)

2. Do different use cases need different documentation?

Yes → Consider PDA (lazy loading will help)

3. Does my skill call external APIs or tools?

Yes → Consider PDA (scripts will help)

4. Will I need to update or expand this skill regularly?

Yes → Consider PDA (easier maintenance)

If you answered “Yes” to 2 or more questions → Use PDA

Real-World Examples: Basic vs PDA

Here’s how real skills compare in token efficiency:

Key Comparisons:

greeting-formatter

Traditional: 2KB
PDA: 2KB (no change)
Savings: 0%
Verdict: ❌ Already optimal

plantuml

Traditional: 50KB
PDA: 3KB + refs (8KB avg)
Savings: 78–94%
Verdict: ✅ Multiple diagram types

notion-uploader

Traditional: 45KB
PDA: 3KB + script
Savings: 93%
Verdict: ✅ Complex API operations

code-reviewer

Traditional: 8KB
PDA: 8KB (no change)
Savings: 0%
Verdict: ❌ All rules always apply

confluence

Traditional: 52KB
PDA: 4KB + scripts
Savings: 92%
Verdict: ✅ Multiple operations, API

simple-formatter

Traditional: 3KB
PDA: 3KB (no change)
Savings: 0%
Verdict: ❌ Simple, focused task

Pattern Recognition:

Simple, focused skills (<5KB): Stay basic — overhead isn’t worth it
Multi-purpose skills with heavy docs (>10KB): Apply PDA — massive token savings
API integration skills: Apply PDA — scripts isolate complexity
All-rules-apply skills: Stay basic — no conditional loading benefit

The Inflection Point:

Around 10KB is when PDA starts paying dividends. Below that, the overhead of organizing references and scripts exceeds the benefit. Above 10KB, the savings compound rapidly. Your results my vary. If it is a skill just for you or your team, you may opt for a 10KB before you start applying PDA. If it is a general purpose skill, you might want to really reduce that to 3KB.

Transitioning from Basic to PDA

You don’t have to start with PDA. Skills can evolve naturally as needs grow:

Stage 1: Basic Skill (Initial Version)

# plantuml.md (5KB)
Basic instructions for creating simple flowcharts and sequence diagrams.
Covers the two most common use cases with minimal documentation.

When This Works:

Team primarily needs flowcharts and sequence diagrams
Reference documentation is brief
Response times are fast

Stage 2: Growing Skill (Getting Bloated)

# plantuml.md (25KB)

Added class diagrams, ER diagrams, state diagrams, examples for each...
Getting harder to navigate and maintain.
Starting to slow down responses noticeably.
Users complain about lag.

When You Know It’s Time to Refactor:

File exceeds 10KB and growing
Response times are noticeably slower
Maintenance requires scrolling through walls of text
Adding features means more bloat

Stage 3: PDA Refactor (Organized, Scalable)

# plantuml.md (3KB - routing logic only)

.claude/skills/
├── plantuml.md (3KB)
├── reference/
│   ├── plantuml_sequence.md (8KB)
│   ├── plantuml_class.md (10KB)
│   ├── plantuml_flowchart.md (5KB)
│   ├── plantuml_er.md (7KB)
│   └── plantuml_state.md (6KB)
└── scripts/
    └── plantuml.sh (generation script)

Side Note: We actually have a PlantUML skill and Mermaid Skill.

Find out more about these skills and Spillwave in the About the Author section. We created tools to evaluate Skills for correctness and grade them for things like compliance and PDA. We have written many skills and put them in our github repo.

Benefits of the Refactor:

✅ Back to fast responses (3KB vs 25KB initial load)
✅ Easy to add new diagram types (just add new reference file)
✅ Scripts handle generation logic (testable, reusable)
✅ AI provides seamless user experience (error handling, adaptation)
✅ Maintainable (update specific references without touching core logic)

The Transition Path:

Identify heavy sections: What documentation could move to references?
Extract references: Create focused reference files for each use case
Create scripts: Move mechanical work (API calls, processing) to scripts
Update skill logic: Add conditional loading based on request analysis
Test thoroughly: Ensure all use cases still work
Monitor token usage: Verify savings are real

Preparing for Part 2

In Part 1, we’ve covered the foundations:

✅ What Claude Code skills are and how they work under the hood
✅ Creating your first skill from scratch in under 5 minutes
✅ Three core patterns covering 90% of use cases
✅ The PDA philosophy and why it solves the scaling problem
✅ How Claude Code natively supports PDA with Read, Bash, and AI reasoning
✅ A decision framework for when to apply PDA versus basic approaches

Coming in Part 2: “Mastering PDA Automation”

We’ll dive deep into production-ready implementation:

1. Technique 1: Reference Files & Lazy Loading

File organization strategies for maximum efficiency
Conditional loading patterns with real code
Complete PlantUML implementation example
Token savings analysis with metrics

2. Technique 2: Scripts for Mechanical Work

Separating AI logic from mechanical execution
Script design patterns (input/output contracts)
Integration examples (Notion, Confluence, Jira)
Error handling between skill and script layers

3. Technique 3: AI Resilience Layer

Graceful error handling techniques
User experience polish strategies
Adaptive behavior patterns
Complete conversation flows with examples

4. Complete Real-World Example: PlantUML + Notion Publisher

Combining all three techniques in production code
Full working implementation you can use immediately
Testing and iteration strategies
Performance metrics (before/after token usage)

5. Advanced Patterns & Best Practices

Multi-stage pipeline orchestration
Caching strategies for repeat requests
Common pitfalls to avoid (with war stories)
Maintenance considerations as skills evolve

Ready to Master PDA? Part 2 transforms you from a skill creator to a PDA expert, with complete code examples, real-world patterns, and production-ready implementations you can adapt to your needs.

Key Takeaways

Before moving to Part 2, lock in these core concepts:

1. Skills are prompt extensions

They add specialized knowledge to Claude’s context
Activate on-demand when needed
Just markdown files with no magic, no complexity
Although they can have scripts

2. PDA is a design pattern, not a framework

Use Read for lazy loading references
Use Bash for script execution
Use AI reasoning for intelligence and adaptation

3. Orchestrator beats encyclopedia

Load what you need, when you need it
80–95% token savings for complex skills
Faster responses, lower costs, better maintenance

4. Token efficiency matters at scale

Below 5KB: basic skills are fine
Above 10KB: PDA pays dividends quickly
At 50KB: PDA is essential (78–94% savings)

5. Not every skill needs PDA

Simple, focused skills (<5KB): stay basic
Growing, multi-purpose skills (>10KB): apply PDA
API integration: almost always benefits from PDA

6. Claude Code has everything you need

Read, Bash, and AI reasoning enable PDA naturally
No special frameworks or plugins required
Work with the system, not against it

The Journey Ahead:

The path from basic skills to PDA mastery is about recognizing when complexity calls for better organization. In Part 2, we’ll show you exactly how to implement that organization with production-ready patterns, complete code examples, and real-world metrics.

You’ll walk away with skills that scale gracefully, respond quickly, and maintain easily as they grow in power and sophistication.

Want to practice before Part 2? Try creating a basic skill for a task you do often. Keep it simple (2–5KB) and focus on clear, numbered instructions. You can always refactor it with PDA techniques after reading Part 2. The best way to learn is by building.

About the Author

Rick Hightower is a technology executive and data engineer with extensive experience at a Fortune 100 financial services organization, where he led the development of advanced Machine Learning and AI solutions to optimize customer experience metrics. His expertise spans both theoretical AI frameworks and practical enterprise implementation.

Rick wrote the skilz universal agent skill installer that works with Gemini, Claude Code, Codex, OpenCode, Github Copilot CLI, Cursor, Aidr, Qwen Code, Kimi Code and about 14 other coding agents as well as the co-founder of the world’s largest agentic skill marketplace.

Connect with Rick Hightower on LinkedIn or Medium for insights on enterprise AI implementation and strategy.

Community Extensions & Resources

The Claude Code community has developed powerful extensions that enhance its capabilities. Here are some valuable resources from Spillwave Solutions (Spillwave Solutions Home Page):

Integration Skills

Notion Uploader/Downloader: Seamlessly upload and download Markdown content and images to Notion for documentation workflows
Confluence Skill: Upload and download Markdown content and images to Confluence for enterprise documentation
JIRA Integration: Create and read JIRA tickets, including handling special required fields

Recently, I wrote a desktop app called Skill Viewer to evaluate Agents skills for safety, usefulness, links and PDA.

Advanced Development Agents

Architect Agent: Puts Claude Code into Architect Mode to manage multiple projects and delegate to other Claude Code instances running as specialized code agents
Project Memory: Store key decisions, recurring bugs, tickets, and critical facts to maintain vital context throughout software development

Visualization & Design Tools

Design Doc Mermaid: Specialized skill for creating professional Mermaid diagrams for architecture documentation
PlantUML Skill: Generate PlantUML diagrams from source code, extract diagrams from Markdown, and create image-linked documentation
Image Generation: Uses Gemini Banana to generate images for documentation and design work
SDD Skill: A comprehensive Claude Code skill for guiding users through GitHub’s Spec-Kit and the Spec-Driven Development methodology.
PR Reviewer Skill: Comprehensive GitHub PR code review skill for Claude Code. Automates data collection via gh CLI, analyzes against industry-standard criteria (security, testing, maintainability), generates structured review files, and posts feedback with approval workflow. Includes inline comments, ticket tracking, and professional review templates.

AI Model Integration

Gemini Skill: Delegate specific tasks to Google’s Gemini AI for multi-model collaboration
Image_gen: Image generation skill that uses Gemini Banana to generate images.

Explore more at Spillwave Solutions — specialists in bespoke software development and AI-powered automation.

Sleepless Dev

Rick

Monday, January 12, 2026