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

Part 2 of 2: Deep Dive and Implementation

Welcome Back

You’ve learned the fundamentals. You understand why Partial Data Automation matters. Now it’s time to build production-ready skills that leverage PDA’s full power. PDA is progressive disclosure architecture and it is helps minimize the overhead of skills on your context window.

In Part 1, we explored the conceptual foundation of Claude Code skills and the PDA philosophy. You discovered when to apply PDA and how Claude Code natively supports it through the Read tool, Bash tool, and AI reasoning. You learned the critical distinction: skills should be orchestrators that load what they need, not encyclopedias that carry everything.

Part 2 delivers the implementation playbook:

• Three battle-tested PDA techniques with complete, working code
• Real-world integrations combining all three techniques
• Best practices learned from production deployments
• Performance analysis with concrete token savings
• Advanced patterns for scaling your skills

Think of this as your field guide. By the end, you’ll have the knowledge to build skills that are lean, fast, and resilient -- skills that adapt to failures and guide users through complex workflows.

Let’s transform concepts into code.

And, remember now it is not just Claude Code but also Codex, Github Copilot and OpenCode have all announced support for Agentic Skills. 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.

Technique 1: Reference Files and Lazy Loading

The Core Problem

Traditional skills load everything upfront. Every invocation carries the full weight of documentation, regardless of what’s actually needed.

Traditional Approach:

# plantuml.md (50KB)
[Complete syntax for sequence diagrams: 15KB]
[Complete syntax for class diagrams: 18KB]
[Complete syntax for ER diagrams: 12KB]
[Complete syntax for flowcharts: 5KB]

Every time you generate a sequence diagram, you load 50KB -- but you only use 15KB. The remaining 35KB is wasted context.

PDA Approach with Lazy Loading:

.claude/skills/
├── plantuml.md (3KB - routing logic only)
└── reference/
    ├── sequence_diagrams.md (8KB - loaded when needed)
    ├── class_diagrams.md (10KB - loaded when needed)
    ├── er_diagrams.md (7KB - loaded when needed)
    └── flowcharts.md (5KB - loaded when needed)

The skill prompt is a lightweight router. It loads only the specific reference it needs for the current task. This is lazy loading for documentation -- the same principle that makes modern applications fast.

The Lazy Loading Sequence in Action

Here’s exactly what happens when a skill uses lazy loading:

Building Your Lazy Loading Skill

Step 1: Create the Skill Router (plantuml.md** -- 3KB)**

# PlantUML Skill
Generate PlantUML diagrams from descriptions and render to PNG.

**Supported Diagram Types:**
- Sequence diagrams (interactions over time)
- Class diagrams (object-oriented structure)
- ER diagrams (entity relationships)
- Flowcharts (process flows)
**Process:**

1. **Analyze Request**
   - Identify diagram type from user description
   - If unclear, ask user to specify
2. **Load Reference**
   - Sequence diagrams → Read reference/sequence_diagrams.md
   - Class diagrams → Read reference/class_diagrams.md
   - ER diagrams → Read reference/er_diagrams.md
   - Flowcharts → Read reference/flowcharts.md
3. **Generate Code**
   - Use loaded syntax to create PlantUML code
   - Follow best practices from reference
   - Validate syntax correctness
4. **Render Diagram**
   - Execute: `plantuml -tpng diagram.puml`
   - Check output success
   - Return image path to user

**Error Handling:**
- If diagram type unclear: Ask user to clarify
- If reference file missing: Report error, list available types
- If PlantUML command fails: Check syntax, report specific error

Notice what’s not in this file: detailed PlantUML syntax. The skill knows what to load, not the syntax itself.

Step 2: Create Focused Reference Files

Reference File: reference/sequence_diagrams.md (8KB)

# Sequence Diagrams

Sequence diagrams illustrate how participants interact over time, showing the flow of messages and temporal ordering of events. They excel at documenting interaction protocols, communication flows, and complex multi-actor processes.

## Basic Syntax

The simplest sequence diagram declares participants and defines messages between them. Participants can be implicit (created on first mention) or explicit (declared with the `participant` keyword for more control):

```puml
@startuml
participant User
participant "Web Server" as WS
database "Database" as DB

User -> WS : Send Request
WS -> DB : Query Data
DB --> WS : Return Results
WS --> User : Send Response
@enduml

Participant Types

PlantUML supports specialized participant types beyond standard boxes:

• participant - Standard rectangular box
• actor - Stick figure for human actors
• boundary - System boundary representation
• control - Control/logic component
• entity - Data entities
• database - Database systems
• collections - Collection of items
• queue - Message queues

Example:

@startuml
actor User
boundary "Web Interface" as Web
control "Auth Controller" as Auth
entity "Session" as Session
database "User DB" as DB

User -> Web : Login
Web -> Auth : Authenticate
Auth -> DB : Verify Credentials
DB --> Auth : User Data
Auth -> Session : Create Session
Session --> Web : Session Token
Web --> User : Login Success
@enduml

Participant Customization

Renaming with Aliases...

This reference is comprehensive for sequence diagrams but says nothing about class diagrams, ER diagrams, or flowcharts. That’s the point. If you need those, then you load those.

This is a real project that you can download and install. Try out the [PlantUML Skill ](https://github.com/SpillwaveSolutions/plantuml)and see for yourself or just check out the references.

## The Token Math

Let’s calculate real savings with concrete numbers:

**Traditional (Encyclopedia) Approach:**

Every skill invocation for any diagram type:

• Total loaded: 50KB (all diagram types)
• Actually used: 8KB (sequence syntax)
• Wasted: 42KB (84% waste)

**PDA (Orchestrator) Approach:**

Skill invocation for sequence diagram:

• Skill core: 3KB (routing logic)
• Loaded reference: 8KB (sequence syntax only)
• Total: 11KB
• Savings: 39KB (78% reduction)

**Multiple Invocations Scenario:**

If a developer creates 5 diagrams in a conversation (2 sequence, 2 class, 1 flowchart):

Traditional: 50KB × 5 = 250KB total context PDA: 3KB + (8KB + 8KB + 10KB + 10KB + 5KB) = 44KB total context Savings: 206KB (82% reduction)

These aren’t theoretical numbers. This is how much context you actually save in production use.

## Reference File Organization Strategies

How you organize references depends on your skill’s purpose and the structure of the domain you’re documenting. Each strategy optimizes for different access patterns and use cases.

**Strategy 1: By Use Case** groups references around distinct user workflows or diagram types. When users think in terms of “I need a sequence diagram” or “I need a class diagram,” this organization matches their mental model. Each reference file corresponds to a complete, focused task. This is the most intuitive organization for most skills because it mirrors how users naturally describe their goals.

**Strategy 2: By Complexity Level** organizes references along a learning curve -- basic concepts, intermediate patterns, advanced features. This works well for educational skills or when supporting users with varying expertise. The skill can start by loading basic syntax for beginners, then progressively load more sophisticated references as the user’s needs evolve. This prevents overwhelming newcomers while still supporting power users.

**Strategy 3: By Feature Area** breaks down references into orthogonal concepts that can be combined. Instead of complete diagram types, you have references for participants, messages, control flow, and styling. This granular approach works best for complex tools with many independent features. The skill can load multiple small references together when a task requires combining several feature areas, giving you maximum flexibility at the cost of slightly more complex loading logic.

**Strategy 1: By Use Case** (Recommended for most skills)

reference/ ├── sequence_diagrams.md # User interactions ├── class_diagrams.md # Object structure ├── er_diagrams.md # Database design └── flowcharts.md # Process flows

**Why this works:**

- Clear separation of concerns
- Natural lazy loading boundaries
- Easy to find relevant documentation
- Mirrors how users think about diagram types

**Strategy 2: By Complexity Level** (Good for educational skills)

reference/ ├── basic_syntax.md # Beginners ├── intermediate_patterns.md # Common use cases └── advanced_features.md # Power users

**Why this works:**

- Progressive learning path
- Can load basic first, then advanced if needed
- Reduces cognitive overload for newcomers

**Strategy 3: By Feature Area** (Good for complex tools)

reference/ ├── participants.md # Defining actors ├── messages.md # Interactions ├── control_flow.md # Loops, conditions └── styling.md # Visual customization

**Why this works:**

- Granular loading (combine multiple refs if needed)
- Easier to update specific features
- Good for feature-rich tools with orthogonal concepts

This is a real skill with real references. I added a collections of links for various skills.

![](image_03.png)
*PlantUML Partial List of References for PlantUML diagram types*

## Conditional Loading Patterns

**Pattern 1: Simple Switch (Most Common)**

Determine diagram type, then load:

• If "sequence" mentioned → Read reference/sequence.md
• If "class" mentioned → Read reference/class.md
• If "ER" or "entity" mentioned → Read reference/er.md
• If "flow" mentioned → Read reference/flowcharts.md

**Pattern 2: Progressive Loading**

Start simple, load more if needed:

Initial load:

• Read reference/basic_syntax.md If user asks for advanced features:
• Read reference/advanced_features.md If user requests custom styling:
• Read reference/styling.md

**Pattern 3: Confidence-Based Loading**

Load based on confidence in understanding:

If request clearly matches pattern:

• Load only specific reference

If request is ambiguous:

• Load multiple related references
• Ask user to clarify

## Best Practices for Reference Files

**Do:**

- ✅ Keep references focused: One topic per file
- ✅ Name descriptively: sequence_diagrams.md not ref1.md
- ✅ Document loading logic: Clear routing rules in skill prompt
- ✅ Test loading patterns: Verify correct references load
- ✅ Include examples: Show common patterns, not just syntax

**Don’t:**

- ❌ Create giant references: Defeats lazy loading purpose
- ❌ Over-granularize: Too many tiny files = complexity
- ❌ Forget error handling: What if reference doesn’t exist?
- ❌ Skip best practices: References should teach, not just document

If your guide is quite large or a workflow is spread across multiple guides, in your SKILL.md you can specify grep regular expressions and glob file groupings to allow Claude to perform a natural agentic search. This is a form of agentic RAG.

## Technique 2: Scripts for Mechanical Work

## The Fundamental Problem

API operations, data transformations, and complex processing are verbose to explain in prompts. Worse, they bloat your skill with mechanical details.

**Without Scripts (Everything in the Prompt):**

Notion Uploader Skill (30KB prompt)

To upload to Notion:

1. Authenticate with bearer token from NOTION_TOKEN env var
2. Parse markdown: headers become heading blocks, paragraphs become paragraph blocks
3. Handle code blocks: create code block objects with language
4. Upload images: convert to base64 or use external URLs
5. Create page in database with parent relationship
6. Paginate block creation (max 100 blocks per request)
7. Handle rate limiting: exponential backoff with retries
8. Parse Notion API errors: 400/401/404/429 codes
9. Format response URLs for user [... 20KB more of detailed API documentation] [... Markdown parsing rules] [... Error handling for 15+ edge cases] [... Rate limiting algorithms]

This is 30KB of mechanical documentation. Your AI spends tokens understanding API minutiae instead of focusing on user intent and experience.

This example is from a real project that I use a lot.

![](image_04.png)

Check it out the [Notion Uploader/Downloader](https://github.com/SpillwaveSolutions/notion_uploader_downloader) is converts large markdown files with PlantUML and Mermaid diagrams into a Notion page. It can also download Notion pages, which is nice if you let’s say store tasks or PRDs in Notion.

## The Solution: Separation of Concerns

Here’s the architecture that makes skills efficient:

Three-layer architecture diagram: user layer at top, AI orchestrator layer in middle making decisions, script layer executing mechanical work, external APIs at bottom

![](image_05.png)

![](image_06.png)

**The key insight:** Scripts handle **mechanical operations**. AI provides **intelligence and user experience**. This is separation of concerns applied to prompt engineering.

## Production Implementation: Notion Uploader

**Skill Prompt (.claude/skills/notion-uploader.md) -- 3KB**

Notion Uploader Skill

Upload markdown files to Notion databases. When to use:

• User wants to publish documentation to Notion
• User says "upload to Notion", "publish article", etc.

Process:

1. Identify Target File
   • If user specifies file path: Use it
   • If user says "this article": Find relevant .md file
   • If ambiguous: Search for .md files, ask user to choose
2. Identify Target Database
   • If user provides database ID: Use it
   • If user provides Notion URL: Extract database ID
   • Otherwise: Use Notion MCP to search databases, ask user to choose
3. Upload File
   • Execute: python3 .claude/skills/scripts/upload_notion.py <file_path> <database_id>
   • Monitor script output
4. Interpret Results
   • Success: SUCCESS: <page_url> → "✓ Article uploaded to Notion: <page_url>"
   • Error: ERROR: 404 → Database not found → Use Notion MCP to list available databases → Ask user to choose correct database
   • Error: ERROR: 401 → Authentication failed → Guide: "Check your NOTION_TOKEN environment variable" → Show how to get token from Notion settings
   • Error: ERROR: Network timeout → Connection issue → Suggest: "Check internet connection and retry" → Offer to retry automatically
   • Error: ERROR: Invalid markdown → Parsing issue → Show problematic section → Suggest fixes or offer to clean up markdown

Requirements:

• Python 3.8+
• pip install notion-client markdown-to-blocks
• NOTION_TOKEN environment variable set

Notice what’s **in** this skill: intent analysis, parameter preparation, and result interpretation. Notice what’s **not** in this skill: API authentication details, markdown parsing logic, rate limiting algorithms.

**Python Script (.claude/skills/scripts/upload_notion.py) -- Not in context**

#!/usr/bin/env python3 """ Upload markdown file to Notion database. Usage: python3 upload_notion.py <markdown_file> <database_id> Environment: NOTION_TOKEN: Notion API integration token Returns: 0: Success (prints "SUCCESS: <page_url>") 1: Error (prints "ERROR: ") """ import sys import os from pathlib import Path from notion_client import Client from markdown_to_blocks import markdown_to_blocks, MarkdownParseError def extract_title(markdown_content): """Extract title from markdown (first # heading).""" for line in markdown_content.split('\n'): if line.startswith('# '): return line[2:].strip() return "Untitled Document" def upload_to_notion(file_path, database_id): """Upload markdown file to Notion database.""" # Validate inputs if not os.path.exists(file_path): print(f"ERROR: File not found: {file_path}") return 1 # Get Notion token notion_token = os.environ.get("NOTION_TOKEN") if not notion_token: print("ERROR: 401 - NOTION_TOKEN environment variable not set") return 1 # Initialize Notion client try: notion = Client(auth=notion_token) except Exception as e: print(f"ERROR: 401 - Authentication failed: {e}") return 1 # Read markdown file try: with open(file_path, 'r', encoding='utf-8') as f: markdown_content = f.read() except Exception as e: print(f"ERROR: Failed to read file: {e}") return 1 # Extract title title = extract_title(markdown_content) # Parse markdown to Notion blocks try: blocks = markdown_to_blocks(markdown_content) except MarkdownParseError as e: print(f"ERROR: Invalid markdown at line {e.line}: {e.message}") return 1 except Exception as e: print(f"ERROR: Failed to parse markdown: {e}") return 1 # Create page in database try: page = notion.pages.create( .. and so on...

You can see the real scripts for this Skill [here](https://github.com/SpillwaveSolutions/notion_uploader_downloader/tree/master/scripts).

Scripts are “0KB in context” is ⚠️ oversimplified because stdout still returns, but the less the LLM has to do, the more context you save.

## Why This Architecture Wins

**Skill Prompt Benefits:**

- ✅ Stays small: 3KB vs 30KB
- ✅ Focuses on logic: “What to do” not “how to implement”
- ✅ Readable and maintainable: Clear decision flow
- ✅ Easy to extend: Add new features by calling different scripts

**Script Benefits:**

- ✅ Not loaded into context: Zero token cost
- ✅ Testable independently: Use pytest for unit tests
- ✅ Reusable: Call from multiple skills or CLI
- ✅ Uses robust libraries: notion-client, requests, not string manipulation
- ✅ Easy to debug: Standard Python debugging tools
- ✅ Handles complexity: Complex logic without bloating prompts

**User Experience:**

- ✅ Fast responses: Small prompt loads quickly
- ✅ Helpful errors: AI interprets script output intelligently
- ✅ Graceful degradation: AI adapts to failures and guides recovery

## Script Design Patterns That Work

**Pattern 1: Single Responsibility**

Each script does one thing well:

scripts/ ├── upload_notion.py # Upload markdown to Notion ├── download_notion.py # Download Notion page to markdown ├── search_notion.py # Search Notion workspace └── create_database.py # Create new Notion database

**Pattern 2: Clear Input/Output Contract**

Make it easy for AI to call your script:

""" Input: sys.argv[1]: file_path (string) sys.argv[2]: database_id (string) env: NOTION_TOKEN (string) Output: stdout: "SUCCESS: " or "ERROR: - " exit code: 0 (success) or 1 (error) """

**Pattern 3: Structured Error Messages**

Make errors parseable by AI:

**Pattern 4: Environment-Based Configuration**

Use environment variables for secrets:

## Technique 3: AI Resilience Layer -- The Secret Sauce

## Why Scripts Alone Fail Users

Traditional scripts fail hard. They report errors and stop:

![](image_07.png)

Error recovery flow showing AI layer catching script errors, interpreting problems, and implementing fixes or guiding users to resolution

The user is stuck. What database ID should they use? Where do they find it? What are the available options? The script doesn’t know. It can’t help.

## AI as the Resilience Layer

With the AI layer, failures become **opportunities for guidance**:

The AI layer transformed a rigid error into helpful, adaptive guidance. This is the **secret sauce** of PDA.

## The Error Recovery Flow

Here’s how error recovery works in production:

![](image_08.png)

**Critical observation:** Every error path leads to either user guidance or automated recovery. There are **no dead ends**. Users are never left wondering “what now?”

## Edge Cases AI Handles Naturally

**1. Ambiguous Requests**

Traditional script:

With AI resilience:

**2. Invalid Parameters**

Traditional script:

With AI resilience:

**3. Authentication Issues**

Traditional script:

With AI resilience:

**4. Network Failures**

Traditional script:

With AI resilience:

**5. Resource Conflicts**

Traditional script:

With AI resilience:

## Error Handling in Skill Prompts

Structure error interpretation in your skill prompts:

## Complete Conversation Example

Here’s a full interaction showing error recovery in action:

## AI Resilience Patterns

**Pattern 1: Retry with Correction**

**Pattern 2: Graceful Degradation**

**Pattern 3: Progressive Disclosure**

## Complete Example: PlantUML Diagram Publisher

Now let’s combine all three techniques into one production-ready skill that demonstrates the full power of PDA.

**Goal:** Generate PlantUML diagrams from user descriptions and publish them to Notion documentation pages.

## The Complete System Architecture

![](image_09.png)

**Token Usage Breakdown:**

- Skill core: 4KB (routing and logic)
- Loaded reference: 8KB (sequence diagrams only)
- Scripts: 0KB (executed via Bash, not loaded into context)
- Total: 12KB in context

**vs Traditional Approach:**

- All PlantUML syntax documentation: 50KB
- All Notion API documentation: 30KB
- Total: 80KB in context

**Savings: 68KB (85% reduction)**

## File Structure

## Implementation Files

**Skill Prompt: **[**diagram-publisher.md**](http://diagram-publisher.md)** (4KB)**

**Generation Script: scripts/generate_plantuml.sh**

**Upload Script: scripts/upload_notion_with_image.py**

## Usage Example

## Performance Metrics

**Context Usage per Invocation:**

- Skill core: 4KB
- Loaded reference (sequence): 8KB
- Scripts: 0KB (not loaded)
- Total: 12KB

**Traditional Approach:**

- PlantUML syntax (all types): 50KB
- Notion API docs: 30KB
- Total: 80KB

**Savings: 68KB (85% reduction)**

**Benefits Demonstrated:**

✅ **Technique 1 (Lazy Loading)**: Only sequence diagram syntax loaded, not class diagrams, ER diagrams, or flowcharts

✅ **Technique 2 (Scripts)**: Diagram generation and Notion upload handled by scripts, not documented in prompts

✅ **Technique 3 (AI Resilience)**: Error handling for missing pages, auth failures, syntax errors with helpful recovery guidance

✅ **Modularity**: Easy to add new diagram types (just add new reference file)

✅ **Testability**: Scripts can be independently tested with `pytest` or `bash` test frameworks

✅ **Maintainability**: Clear separation means updates are isolated to relevant components

## Best Practices and Common Pitfalls

## Reference File Best Practices

Avoid context rot. Loading everything makes the AI work less. You flood the context with information the LLM does not need to do what you want, which means it more likely to get confused. Also tokens input has a price. Longer processing time and more used up tokens. It is better to use a scalpel to do surgery rather than an axe.

**Organization:**

✅ **Do:**

❌ **Don’t:**

**Content Structure:**

✅ **Do:**

- Include practical examples and common patterns
- Document best practices for each concept
- Show common errors and how to avoid them
- Keep focused on one well-defined topic
- Aim for 5–15KB per reference file

❌ **Don’t:**

- Mix unrelated topics in one file
- Create reference files <2KB (too granular, overhead not worth it)
- Create reference files >20KB (defeats lazy loading efficiency)
- Skip examples (syntax alone isn’t enough)

## Script Design Best Practices

**Structure:**

✅ **Do:**

❌ **Don’t:**

**Error Handling:**

✅ **Do:**

❌ **Don’t:**

## Common Pitfalls

**Pitfall 1: Over-Engineering Simple Skills**

❌ **Don’t use PDA for simple skills:**

**When skill + docs < 5KB, PDA overhead isn’t worth it.**

**Pitfall 2: Under-Documenting References**

❌ **Don’t create sparse references:**

This is too minimal. The AI can’t generate quality diagrams from just syntax.

✅ **Do provide complete guidance:**

**Pitfall 3: Vague Error Messages**

❌ **Don’t be vague:**

1. Decide: Basic or PDA? (Use the decision checklist from Part 1)
2. Implement using patterns from this guide
3. Measure token usage and performance improvements
4. Iterate based on real-world use and feedback

**Share your skills:**

- Document your PDA patterns and discoveries
- Share with the Claude Code community
- Contribute to skill libraries and repositories
- Help others learn and improve their skills
- Build the collective knowledge base

Based on the project files and official spec, here’s a concise overview:

## Claude Skill Best Practice: Make sure you Claude Skill is compliant: Skill Requirements (Official Spec)

## Minimum Structure

## Required YAML Frontmatter

## Optional Frontmatter Fields

**That’s it.** The official spec is minimal: `name` + `description` in frontmatter, followed by markdown content. Also the name of the skill should match the skill directory.

## Claude Skill Best Practice: Description Quality

- Use third-person: “This skill should be used when…” (not “Use this skill when…”)
- Include specific trigger phrases users would say
- Be concrete about scenarios

## Claude Skill Best Practice: Writing Style

- Use imperative/infinitive form throughout the markdown body
- Verb-first instructions, not second person

## Claude Skill Best Practice: Progressive Disclosure Structure

- SKILL.md = routing logic, essential procedures, pointers to resources
- references/ = detailed documentation Claude loads when needed
- scripts/ = deterministic code for repetitive/mechanical tasks
- assets/ = files used in output (templates, images, fonts)

## Claude Skill Best Practice: When to Use Each Resource Type

Resource -- -- -- -- -- -- -- -- -- -Use When

**references/** -- -- -- -- -- -- -- -- Documentation Claude should consult while working (schemas, API docs, detailed guides)

**scripts/** -- -- -- -- -- -- -- -- -- -- Same code gets rewritten repeatedly, or deterministic reliability needed

**assets/** -- -- -- -- -- -- -- -- -- -- -- Files for final output (templates, boilerplate, images)

## Claude Skill Best Practice: Keep SKILL.md Lean

- Target: 1,500–2,000 words
- Maximum: ~5,000 words
- Move detailed content to references/
- Only include essential procedural instructions

## Reference Supporting Files

## Validation Rules (From quick_validate.py)

1. SKILL.md must exist
2. Must start with --- (YAML frontmatter)
3. Must have valid frontmatter format (closed with ---)
4. Must contain name: field
5. Must contain description: field
6. Name must be hyphen-case: ^[a-z0-9-]+$
7. Name cannot start/end with hyphen or have consecutive hyphens
8. Description cannot contain angle brackets (< or >)

## Quick Checklist

## Final Thoughts

The journey from basic skills to PDA mastery is about recognizing when complexity calls for better organization. Skills extend Claude’s capabilities in your domain. PDA makes those extensions efficient, maintainable, and powerful.

You now have the knowledge to build skills that are:

- Lean: Loading only what’s needed (orchestrator pattern)
- Fast: Minimal token overhead (3–12KB vs 50–80KB)
- Resilient: Graceful error handling (AI interpretation layer)
- Maintainable: Modular structure (easy component updates)
- Powerful: AI intelligence combined with script execution

The Claude Code community is waiting to see what you create. Go build something remarkable.

## Agentic Skill Debugger

I wrote a desktop tool to help me write Skills: [The Skills Debugger](https://github.com/SpillwaveSolutions/skills_viewer).

## Skills Debugger: A Developer Tool for Claude Skills

To help streamline the development and debugging of Claude Code skills, I created the [Skills Debugger](https://github.com/SpillwaveSolutions/skills_viewer) -- a desktop tool that provides comprehensive visualization and analysis of your skills.

## Key Features

**Visual Structure Analysis:**

The tool provides an interactive view of your skill’s architecture, showing the relationships between the main skill file, reference documents, and scripts. This makes it easy to understand the scope and complexity of your PDA implementation at a glance.

**Reference and Script Inspection:**

View the complete contents of reference files and scripts directly within the tool. This eliminates the need to switch between files while debugging or refining your skills constantly.

**Trigger Analysis:**

The debugger analyzes your skill’s trigger conditions and provides optimization suggestions. This helps ensure your skills activate at the correct times and respond to the appropriate user intents.

**Quality Reports:**

- Broken Link Detection: Identifies references to files that don’t exist
- PDA Score Analysis: Evaluates how well your skill follows PDA principles
- Spec Compliance: Checks adherence to Claude Code skill specifications
- Trigger Suggestions: Recommends improvements to trigger conditions

**Architectural Diagrams:**

Automatically generates visual diagrams showing the relationships between your skill components. These diagrams help you quickly understand the flow of data and the dependencies within your skill structure.

## Development Status

The Skills Debugger is an evolving side project that continues to add new features based on real-world skill development needs. It’s designed to grow alongside the Claude Code skills ecosystem.

**Get Started:** [https://github.com/SpillwaveSolutions/skills_viewer](https://github.com/SpillwaveSolutions/skills_viewer)

![](image_10.png)

It displays scripts, triggers, content, and diagrams of the tool. It also shows what’s in references and scripts.

![](image_11.png)

It helps you analyze what triggers your skill.

![](image_12.png)

It shows scripts as well.

![](image_13.png)

It draws a nice diagram of the Skills resources so you can get a feel for the scope.

![](image_14.png)

I included reports for broken link references, poor PDA scores, spec compliance, and some trigger suggestion analysis.

![](image_15.png)

It is an evolving side project.

I also started downloading top skills (about 4K so far) and then ran some NLP analysis on them.

![](image_16.png)

I implemented agentic grading, similar to what I built for the Skills Debugger, and used it to evaluate skills. I’m trying to understand how people use Skills and how to write efficient, agentic Skills.

![](image_17.png)

I did a lot of NLP work to find the various categories of skills as well.

**Questions or feedback?** Share your PDA skills and patterns with the community. Let’s build the future of Claude Code together.

## Appendix: Quick Reference

## PDA Decision Checklist

## File Structure Template

## Skill Prompt Template

## Script Template

*End of Part 2*

## 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 skill installer](https://skillzwave.ai/docs/) 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](https://skillzwave.ai/).

Mr. Hightower holds TensorFlow certification and has completed Stanford University’s Machine Learning Specialization. His technical proficiency encompasses supervised learning methodologies, neural network architectures, and AI technologies, which he has leveraged to deliver measurable business outcomes through enterprise-grade solutions. He has earned multiple certifications from Anthropic, including Claude SDK with Vertex AI, Claude SDK with Amazon Bedrock, Claude Tools, and Model Context Protocol (MCP). His hands-on experience includes development with LangChain, LlamaIndex, OpenAI API, LiteLLM, and deployment across AWS, Azure, and Google Cloud Platform. Currently, his work focuses on agentic AI solutions using Claude Code, OpenCode, and Claude Agent SDK, alongside various LLM tools and platforms.

Connect with Rick Hightower on [LinkedIn](https://www.linkedin.com/in/rickhigh/) or [Medium](https://medium.com/@richardhightower) 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](https://spillwave.com/):

## 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](https://github.com/SpillwaveSolutions/skills_viewer) to evaluate Agents skills for safety, usefulness, links and PDA.

![](image_18.png)

![](image_19.png)

![](image_20.png)

## 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
- Claude Agents Collection: A comprehensive collection of 15 specialized agents for various development tasks

## 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**](https://spillwave.com/) -- specialists in bespoke software development and AI-powered automation.