Modular Skills

Table of Contents

• Overview
• Quick Start
• Workflow and Tasks
• Quality Checks
• Resources

Modular Skills Design

Overview

This framework breaks complex skills into focused modules to keep token usage predictable and avoid monolithic files. We use progressive disclosure: starting with essentials and loading deeper technical details via @include or Load: statements only when needed. This approach prevents hitting context limits during long-running tasks.

Modular design keeps file sizes within recommended limits, typically under 150 lines. Shallow dependencies and clear boundaries simplify testing and maintenance. The hub-and-spoke model allows the project to grow without bloating primary skill files, making focused modules easier to verify in isolation and faster to parse.

Core Components

Three tools support modular skill development:

• skill-analyzer: Checks complexity and suggests where to split code.
• token-estimator: Forecasts usage and suggests optimizations.
• module_validator: Verifies that structure complies with project standards.

Design Principles

We design skills around single responsibility and loose coupling. Each module focuses on one task, minimizing dependencies to keep the architecture cohesive. Clear boundaries and well-defined interfaces prevent changes in one module from breaking others. This follows Anthropic's Agent Skills best practices: provide a high-level overview first, then surface details as needed to maintain context efficiency.

Module Ownership (IMPORTANT)

Deprecated: skills/shared/modules/ directories. This pattern caused orphaned references when shared modules were updated or removed.

Current pattern: Each skill owns its modules at skills/<skill-name>/modules/. When multiple skills need the same content, the primary owner holds the module and others reference it via relative path (e.g., ../skill-authoring/modules/anti-rationalization.md). The validator flags any remaining skills/shared/ directories.

Quick Start

Skill Analysis

Analyze modularity using scripts/analyze.py. You can set a custom threshold for line counts to identify files that need splitting.

python scripts/analyze.py --threshold 100

From Python, use analyze_skill from abstract.skill_tools.

Token Usage Planning

Estimate token consumption to verify your skill stays within budget. Run this from the skill directory:

python scripts/tokens.py

Module Validation

Check for structure and pattern compliance before deployment.

python scripts/abstract_validator.py --scan

Workflow and Tasks

Start by assessing complexity with skill_analyzer.py. If a skill exceeds 150 lines, break it into focused modules following the patterns in ../../docs/examples/modular-skills/. Use token_estimator.py to check efficiency and abstract_validator.py to verify the final structure. This iterative process maintains module maintainability and token efficiency.

Quality Checks

Identify modules needing attention by checking line counts and missing Table of Contents. Any module over 100 lines requires a TOC after the frontmatter to aid navigation.

# Find modules exceeding 100 lines
find modules -name "*.md" -exec wc -l {} + | awk '$1 > 100'

Standards Compliance

Our standards prioritize concrete examples and a consistent voice. Always provide actual commands in Quick Start sections instead of abstract descriptions. Use third-person perspective (e.g., "the project", "developers") rather than "you" or "your". Each code example should be followed by a validation command. For discoverability, descriptions must include at least five specific trigger phrases.

TOC Template

## Table of Contents

- [Section Name](#section-name)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)

Resources

Shared Modules: Cross-Skill Patterns

Standard patterns for triggers, enforcement language, and anti-rationalization:

• Trigger Patterns: See trigger-patterns.md
• Enforcement Language: See enforcement-language.md
• Anti-Rationalization: See anti-rationalization.md

Skill-Specific Modules

Detailed guides for implementation and maintenance:

• Enforcement Patterns: See modules/enforcement-patterns.md
• Core Workflow: See modules/core-workflow.md
• Implementation Patterns: See modules/implementation-patterns.md
• Migration Guide: See modules/antipatterns-and-migration.md
• Design Philosophy: See modules/design-philosophy.md
• Troubleshooting: See modules/troubleshooting.md
• Optimization Techniques: See modules/optimization-techniques.md - reducing large skill file sizes through externalization, consolidation, and progressive loading

Tools and Examples

• Tools: skill_analyzer.py, token_estimator.py, and abstract_validator.py in ../../scripts/.
• Examples: See ../../docs/examples/modular-skills/ for reference implementations.

A Guide to Implementing Modular Skills

This guide details the implementation of modular skills. Breaking skills into smaller, manageable modules creates a maintainable and predictable architecture.

The Hub-and-Spoke Structure

The framework uses a "hub-and-spoke" pattern for modular skills. A primary "hub" skill contains core metadata and an overview, while optional "spoke" submodules contain detailed information.

Structure example:

modular-skills/
├── SKILL.md (this is the hub, with metadata and an overview)
├── guide.md (this file, which provides an overview of the modules)
├── modules/
│   ├── core-workflow.md (for designing new skills)
│   ├── implementation-patterns.md (for implementing skills)
│   └── antipatterns-and-migration.md (for migrating existing skills)
├── scripts/
│   ├── analyze.py (Python wrapper for skill analysis)
│   └── tokens.py (Python wrapper for token estimation)
└── examples/
    ├── basic-implementation/
    └── advanced-patterns/

Note: The scripts directory contains Python wrappers that use the shared abstract.skill_tools module, eliminating code duplication while providing convenient CLI access from within skill directories.

This modular structure reduces token usage. The core workflow consumes approximately 300 tokens, loading other modules on-demand.

How to Use the Modules

• For new skills, start with core-workflow.md to evaluate scope and design the module architecture. Then, refer to implementation-patterns.md for implementation guidance.

• For migrating existing skills, start with antipatterns-and-migration.md to identify common anti-patterns and plan the migration.

• For troubleshooting, refer to antipatterns-and-migration.md for common issues and solutions.

Concrete examples of modular design patterns are available in the examples/ directory.

Modular Skills Anti-Patterns and Migration

This document covers the common anti-patterns we've seen when building modular skills, and how to migrate away from them.

Anti-Patterns to Avoid

When we first started building skills, we made a few mistakes. Here are some of the things we learned to avoid.

• Monolithic Skills: We used to have single, large files that covered multiple themes. This made them difficult to maintain and understand.
• Deeply Nested Modules: We also had complex dependency chains, with modules that depended on other modules, which in turn depended on other modules. This made it hard to track dependencies and led to a lot of complexity.
• Implicit Dependencies: We didn't always declare our dependencies explicitly. This made it difficult to know what a skill needed to run.
• Content Duplication: Instead of referencing shared content, we would copy it between modules. This led to a lot of duplicated effort and inconsistencies.
• Poor Naming: Our naming conventions were inconsistent, which made it hard to find and understand our skills.

Warning Signs

Here are a few warning signs that a skill might not be as modular as it could be:

• The skill file is larger than 2KB.
• The skill covers more than three main themes.
• The same instructions are repeated across multiple skills.
• There are complex import chains.
• It's not clear when to use specific modules.

Migration Guide

If you have existing skills that are not as modular as they could be, you can use this guide to help you migrate them to our modular design patterns.

Converting Existing Skills

1. Analyze: The first step is to run a complexity analysis on the existing skill. This will help you identify the different themes and concerns that are covered by the skill. 2. Extract: Once you've identified the different themes, you can start to extract them into separate modules with clear boundaries. 3. Modularize: Now you can create the new modular structure, with a hub skill and separate modules for each theme. 4. Document: It's important to update all the references and call patterns to reflect the new modular structure. 5. Validate: Finally, you should test the new modular structure to make sure everything is working as expected.

Maintaining Compatibility

During the transition, we recommend maintaining the original skill as a hub. This will validate that existing workflows that depend on the original skill continue to work. You should also provide documentation that explains the new modular structure and how to use it.

We recommend testing both the old and new patterns to validate that everything is working as expected. You should also monitor the token usage of the new modular structure to see if it's providing the improvements you were hoping for.

For new skills, you should start with the core workflow guidance. For more detailed implementation guidance, see the implementation patterns documentation.

The Core Workflow for Modular Skills

This is our core workflow for designing and building modular skills. We follow this process to validate that our skills are well-designed, maintainable, and efficient.

Phase 1: Evaluating the Scope

Before we start building, we first evaluate the scope of the skill. This helps us decide if the skill should be modularized and how it fits into our existing skill architecture.

Complexity Analysis

The first step is to analyze the complexity of the proposed skill. We use the skill-analyzer tool to help with this.

skill-analyzer --path path/to/skill --threshold 150

We look at a few key metrics:

• Line count: If the skill is more than 150 lines, it's a good candidate for modularization.
• Theme coverage: If the skill covers more than three distinct themes, we'll break it up.
• Token footprint: A skill with a token footprint of more than 2KB is another sign that it should be modularized.
• Overlap detection: If the skill shares workflows with other skills, we'll look for opportunities to extract those shared workflows into a separate module.

Dependency Mapping

Next, we map out any existing workflows that could be shared. This includes things like:

• ADR templates and processes
• Git workflows (commit messages, PR templates, review patterns)
• Testing patterns (unit, integration, and end-to-end)
• Documentation standards

Token Usage Estimation

Finally, we estimate the token usage of the proposed skill. The token-estimator tool can help with this.

token-estimator --file skill.md --include-dependencies

Phase 2: Designing the Module Architecture

Once we've evaluated the scope, we move on to designing the module architecture.

The Hub-and-Spoke Pattern

We use a "hub-and-spoke" pattern for our modular skills. This means we have a primary "hub" skill that contains the core metadata and an overview, and then optional "spoke" submodules that contain more detailed information.

This is an example of the structure:

skill-category/
├── SKILL.md (this is the hub, with metadata and an overview)
├── guide.md (this is a spoke, with a detailed workflow)
├── scripts/ (this is a spoke, with related scripts)
│   ├── analyzer.py
│   └── validator.py
└── examples/ (this is a spoke, with examples)
    ├── basic-implementation/
    └── advanced-patterns/

Naming Conventions

We use consistent prefixes for our skills to make them easier to find and understand. For example:

• architecture-paradigm-* for architectural patterns
• testing-* for testing workflows
• documentation-* for documentation standards
• workflow-* for process automation

Dependency Rules

We follow a few simple rules for dependencies:

• Maximum depth of 2 levels: We stick to a simple hub -> module structure and avoid any deeper nesting.
• No circular dependencies: A hub can depend on a module, but a module can't depend on a hub.
• Explicit dependency declaration: All dependencies must be declared in the skill's frontmatter.
• Default behavior for missing dependencies: If a dependency is missing, the skill should still function, even if it's in a limited capacity.

Once you've designed your architecture, you can move on to implementation patterns for more detailed guidance.

Design Patterns

Placeholder module for the modular-skills skill.

This module is referenced from neighbouring documentation but its content has not yet been written. Contributions welcome - see the parent SKILL.md for the skill's overall purpose and the role this module is expected to play.

Our Approach to Modular Design

Core Principles

We follow a few core principles when designing modular skills:

Progressive Disclosure

Progressive disclosure starts with a high-level overview and provides details as needed: metadata, overview, details, then tools.

Implementation:

• Level 1: Metadata (YAML frontmatter) - Quick overview and categorization
• Level 2: Overview section - Essential information and quick start
• Level 3: Detailed content - In-depth explanations and examples
• Level 4: Modules - Specialized content for advanced use cases

Benefits:

• Reduces initial cognitive load
• Allows users to control information depth
• Improves loading performance
• Maintains detailed functionality

Shallow Dependencies

The "hub and spoke" model connects a central skill to independent modules. This simplifies architecture.

Architecture Pattern:

Main Skill
├── Module A (independent)
├── Module B (independent)
└── Module C (independent)

Avoid:

Module A → Module B → Module C (deep chain)
Module A ↔ Module B ↔ Module C (complex web)

Benefits:

• Simplified dependency management
• Easier testing and debugging
• Better performance and loading
• Clearer architecture understanding

Consistent Naming

Consistent naming patterns for skills and modules enhance discoverability and predictability.

Naming Conventions:

• Skills: kebab-case, descriptive purpose
• Modules: category-specific-topic.md
• Scripts: action-analyzer, token-estimator
• Directories: skills/skill-name/scripts/

Examples: skills/modular-skills/modules/design-patterns.md scripts/skill_analyzer.py skills/api-scaffolding/scripts/backend-generator

skills/ModularSkill/module/DesignPatterns skills/skill-name/Scripts/analyzer random_module_file.md

Tool Integration

Tools integration maximizes skill capability by automating tasks.

Tool Categories:

• Analysis Tools: Evaluate skill quality and structure
• Generation Tools: Create content and configurations
• Validation Tools: Check compliance and standards
• Automation Tools: Execute common workflows

Integration Benefits:

• Reduces manual effort
• Provides consistent results
• Enables complex workflows
• Improves user experience

Token Efficiency

Token usage optimization is central to design patterns.

Efficiency Strategies:

• Content Density: Maximize information per token
• Progressive Loading: Load content as needed
• External Resources: Move large content to separate files
• Smart Referencing: Use links instead of duplication

Metrics:

• Target: <4,000 tokens per skill
• Ideal: <2,000 tokens for focused skills
• Monitor: Regular token usage analysis

Design Workflow

1. Scoping and Planning

• Define clear skill purpose and boundaries
• Identify potential modules and their responsibilities
• Plan progressive disclosure structure
• Estimate token usage and complexity

2. Module Design

• Apply single responsibility principle
• validate loose coupling between modules
• Design clear interfaces and boundaries
• Plan for extensibility and maintenance

3. Implementation

• Start with metadata and overview
• Implement core functionality first
• Add detailed content progressively
• Integrate tools for automation

4. Validation and Optimization

• Test module independence and interfaces
• Validate against design principles
• Optimize token usage and performance
• Document usage patterns and examples

Quality Gates

Module Quality Checklist

• [ ] Single, clear purpose
• [ ] Minimal dependencies
• [ ] Consistent naming and structure
• [ ] Progressive disclosure implemented
• [ ] Token usage optimized
• [ ] Tools integrated where appropriate
• [ ] Clear documentation and examples

Architecture Validation

• [ ] Hub-and-spoke dependency model
• [ ] No circular dependencies
• [ ] Clear module boundaries
• [ ] Explicit dependency declarations
• [ ] Testable in isolation

Performance Requirements

• [ ] Total tokens <4,000
• [ ] Loading time <2 seconds
• [ ] Memory usage reasonable
• [ ] Context window efficient
• [ ] Tools responsive and reliable

Enforcement Patterns for Skill Design

Overview

This module provides patterns for designing skill frontmatter that validates reliable discovery and appropriate enforcement. These patterns complement the shared modules in shared-modules/ with skill-specific guidance.

The Frontmatter-Only Trigger Pattern

Problem

Claude's skill selection uses the description field to decide which skill to read. If conditional logic is in the skill body:

1. Claude must already be reading the skill to discover it applies (chicken-and-egg) 2. Skills get read unnecessarily, wasting tokens 3. Skill triggering becomes inconsistent

Solution

Put ALL trigger logic in the description field:

description: |
  [ACTION VERB + CAPABILITY]. [1-2 sentences max]

  Triggers: [comma-separated keywords for discovery]

  Use when: [specific scenarios, symptoms, or contexts]

  DO NOT use when: [explicit negative triggers] - use [ALTERNATIVE] instead.

  [ENFORCEMENT if applicable]

Implementation Checklist

When creating a new skill:

• [ ] Write description with Triggers, Use when, DO NOT use when
• [ ] Do NOT add "When to Use" section in body
• [ ] Match enforcement language to skill category
• [ ] Name alternative skills explicitly in negative triggers
• [ ] Verify description is self-contained (readable alone)

Skill Category Classification

Classify your skill to determine appropriate enforcement language:

Enforcement Language by Category

Discipline-Enforcing Skills (Maximum Intensity)

description: |
  [Capability statement].

  Triggers: [keywords]

  Use when: [conditions]

  DO NOT use when: [exclusions] - use [alternative] instead.

  YOU MUST use this skill when [critical conditions]. This is NON-NEGOTIABLE.
  NEVER skip this skill when [requirements].
  No exceptions without explicit user permission.

Key phrases: "YOU MUST", "NON-NEGOTIABLE", "NEVER skip", "No exceptions"

Workflow Skills (High Intensity)

description: |
  [Capability statement].

  Triggers: [keywords]

  Use when: [conditions]

  DO NOT use when: [exclusions] - use [alternative] instead.

  Use this skill BEFORE starting [task type]. Check even if unsure.
  If you think this doesn't apply, reconsider - it probably does.

Key phrases: "BEFORE starting", "Check even if unsure", "reconsider"

Technique Skills (Medium Intensity)

description: |
  [Capability statement].

  Triggers: [keywords]

  Use when: [conditions]

  DO NOT use when: [exclusions] - use [alternative] instead.

  Consider this skill when [symptoms appear].

Key phrases: "Use when", "Consider when", "Recommended for"

Reference Skills (Low Intensity)

description: |
  [Capability statement].

  Triggers: [keywords]

  Use when: [conditions]

  DO NOT use when: [exclusions] - use [alternative] instead.

  Available for [use cases]. Consult when needed.

Key phrases: "Available for", "Consult when needed"

Negative Trigger Design

Why Negative Triggers Matter

Without explicit "DO NOT use when":

• Skills with overlapping domains trigger simultaneously
• Claude wastes context reading irrelevant skills
• Users get confused about which skill applies

Pattern for Negative Triggers

Always: 1. Identify skills with overlapping domains 2. Name each explicitly in "DO NOT use when" 3. Provide clear handoff guidance

DO NOT use when: evaluating existing skill quality - use skills-eval instead.
DO NOT use when: writing prose for humans - use writing-clearly-and-concisely.
DO NOT use when: debugging runtime errors - use systematic-debugging instead.

Common Overlaps to Address

CSO (Claude Search Optimization)

Effective Keywords

Use concrete, specific terms that match what users say:

Good triggers:

• "flaky tests", "race conditions", "memory leak"
• "TypeError", "undefined", "null reference"
• "refactoring skills", "breaking down monolith"
• "token optimization", "context efficiency"

Avoid generic terms:

• "help", "process", "manage"
• "improve", "fix", "update" (without specificity)
• "work with", "handle"

Keyword Selection Process

1. List user phrases that should trigger this skill 2. Include error messages and symptoms 3. Add task-type keywords 4. Include technology-specific terms 5. Remove generic words that don't differentiate

Integration with Modular Design

When designing modular skills:

1. SKILL.md frontmatter: All trigger logic here 2. SKILL.md body: Start immediately with workflow/overview 3. modules/: Progressive disclosure of details 4. Shared modules: Reference via relative paths

skills/<skill-name>/
├── SKILL.md           # Frontmatter has ALL triggers
│                      # Body has NO "When to Use" section
└── modules/
    └── *.md           # Deep-dive content, loaded on demand

Validation

Before shipping a skill, verify with skills-eval:

# Check trigger isolation compliance
python scripts/compliance_checker.py --skill-path path/to/skill/SKILL.md

Expected output:

• No "Body contains 'When to Use'" warnings
• Trigger isolation score >= 7/10
• All negative triggers present

Related Resources

• Trigger Patterns - Description field templates
• Enforcement Language - Intensity calibration
• Anti-Rationalization - Bypass prevention
• Trigger Isolation Analysis - Evaluation criteria

Modular Skills Implementation Patterns

This document covers the implementation patterns we use for our modular skills. We follow these patterns to validate that our skills are easy to understand, maintain, and use.

Phase 3: Implementing the Skill

The Progressive Disclosure Structure

We design our skills around the idea of "progressive disclosure." This means that we start with a high-level overview and then provide more detail as needed. This allows users to get the information they need without being overwhelmed with detail.

Here's how we structure our skills:

• Level 1: Metadata (the YAML frontmatter in `SKILL.md`): This is the first thing a user sees. It should provide a one-line summary of what the skill does, as well as other key information like the category, tags, dependencies, and tools.

    ---
    name: skill-name
    description: One-line summary
    category: workflow-type
    tags: [relevant, tags]
    dependencies: [skill-dependency1, skill-dependency2]
    scripts: [script1, script2]
    usage_patterns: [pattern1, pattern2]
    complexity: beginner|intermediate|advanced
    estimated_tokens: number
    ---

• Level 2: Overview (the body of `SKILL.md`): This section provides a bit more detail. It should include a quick start guide, a "when to use" section, a list of available scripts, and links to other resources.

• Level 3: Detailed Workflow (`guide.md`): This is where you'll find the step-by-step instructions for using the skill. It should include code examples and guidance for resolving common issues.

• Level 4: Executable Scripts (`scripts/`): This directory contains any automation scripts, validation utilities, or analysis tools that are part of the skill.

Script Integration

We believe that the most capable skills are those that integrate with scripts to automate tasks. When we build scripts, we follow these guidelines:

• They should be executable from the command line.
• They should be self-contained and have a clear interface.
• They should be documented with usage examples.
• They should be tested for security and performance.

Phase 4: Documentation, Validation, and Measuring Success

Once the skill is implemented, we move on to the final phase: documentation, validation, and measuring success.

Documentation

We create clear documentation for our skills so that others can understand how to use them. This includes:

• When to load each module
• How the modules interact with each other
• What the secondary options are if a primary one is not available
• Common ways to use the skill

Validation

Before we deploy a new skill, we validate it to make sure it's working as expected. We use the module_validator tool for this.

module_validator --skill-path . --check-dependencies

The validator checks for:

• Completeness of the frontmatter
• Availability of dependencies
• Functionality of the scripts
• Accuracy of the token usage estimation

We also have a testing strategy that includes unit tests for our scripts, integration tests for our workflows, token usage validation, and performance benchmarking.

Measuring Success

We look at both quantitative and qualitative measures to determine if a skill is successful.

On the quantitative side, we look for:

• A reduction in token usage (we aim for at least a 30% reduction)
• An improvement in load time
• A reduction in maintenance overhead
• How often the skill is reused across different projects

On the qualitative side, we look for:

• How easy it is for our developers to use the skill
• How easy it is to find the skill
• How clear the documentation is
• How widely the skill is adopted within our team

To get started with the modular skills design process, refer to the core workflow documentation for guidance on scope evaluation and architecture design.

Optimization Techniques for Large Skills

Systematic methodology to reduce skill file size through externalization, consolidation, and progressive loading patterns.

When To Use

Symptoms that trigger optimization:

• Skills-eval validation shows "[WARN] Large skill file" warnings
• SKILL.md files exceed 300 lines
• Multiple code blocks (10+) with similar functionality
• Heavy Python implementations inline with markdown
• Functions >20 lines embedded in documentation

Core Pattern: Externalize-Consolidate-Progress

Transformation Pattern

Before: 654-line skill with heavy inline Python implementations After: ~150-line skill with external tools and references

Key Changes:

• Externalize heavy implementations (>20 lines) to dedicated tools
• Consolidate similar functions with parameterization
• Replace code blocks with structured data and tool references
• Implement progressive loading for non-essential content

Size Reduction Strategies

File Organization

skill-name/
  SKILL.md              # Core documentation (~150-200 lines)
  modules/
    examples.md         # Usage examples and anti-patterns
    patterns.md         # Detailed implementation patterns
  tools/
    analyzer.py         # Heavy implementations with CLI
    config.yaml         # Structured data
  examples/
    basic-usage.py      # Minimal working example

Optimization Workflow

Phase 1: Analysis

• Identify files >300 lines
• Count code blocks and functions
• Measure inline code vs documentation ratio
• Find repeated patterns and similar functions

Phase 2: Externalization

• Move heavy implementations (>20 lines) to separate files
• Add CLI interfaces to externalized tools
• Create tool directory structure
• Add usage examples for each tool

Phase 3: Consolidation

• Merge similar functions with parameterization
• Replace code blocks with structured data where appropriate
• Implement progressive loading for non-essential content
• Update skill documentation to reference external tools

Phase 4: Validation

• Verify line count <300 (target: 150-200)
• Test all externalized tools work correctly
• Confirm progressive loading functions
• Run skills-eval validation to verify size reduction

Quick Decision Tree

Is skill >300 lines?
+-- No -> Continue as-is
+-- Yes -> Analyze composition
    +-- Has heavy code blocks (>20 lines)?
    |   -> Externalize to tools/ with CLI (60-70% reduction)
    +-- Has repeated patterns?
    |   -> Consolidate with parameterization (15-20% reduction)
    +-- Has structured config data embedded?
    |   -> Extract to config.yaml (10-15% reduction)
    +-- Has non-essential details?
        -> Use progressive loading (5-10% reduction)

Key Success Factors

DO:

• Always add CLI interfaces to external tools
• Keep core concepts inline in SKILL.md
• Consolidate related functionality
• Include working examples
• Test all tools have correct references

DON'T:

• Externalize without CLI (hard to use/test)
• Create too many small files (increases complexity)
• Remove essential documentation (reduces discoverability)
• Add complex dependencies (hard to maintain)
• Skip usage examples (unclear tool usage)

Expected Outcome

• 50-70% line count reduction
• 40-60% token usage reduction
• No skills-eval warnings
• Clear separation of concerns
• Maintainable external tools with CLI interfaces

Modular Skills Troubleshooting

Common Issues and Solutions

Module Validation Failures

Issue: module_validator reports structural violations or compliance issues

# Check specific skill with verbose output
scripts/module_validator -s path/to/skill.md --verbose

# Validate YAML frontmatter specifically
scripts/module_validator -s path/to/skill.md -c

Common Solutions:

• Missing Required Fields: validate name, description, and category are present in YAML frontmatter
• Invalid YAML: Check for proper indentation and syntax in frontmatter
• Token Limits: Verify estimated tokens are reasonable for skill complexity
• Tool References: validate all listed tools are accessible and executable

Inaccurate Token Estimations

Issue: Token counts don't match actual usage or seem incorrect

# Get detailed token breakdown
scripts/token-estimator -f path/to/skill.md -v

# Compare design alternatives
scripts/token-estimator -f design1.md > design1_tokens.txt
scripts/token-estimator -f design2.md > design2_tokens.txt

Common Solutions:

• Code Block Weighting: Code blocks use more tokens - consider externalizing large examples
• Content Duplication: Remove repeated content and use references instead
• Verbose Descriptions: Condense explanations while maintaining clarity
• Example Bloat: Move complex examples to separate files or modules

Skills Still Inefficient After Applying Patterns

Issue: Despite following modular design patterns, skills remain inefficient

# Analyze dependency depth and complexity
scripts/skill-analyzer --path path/to/skill.md --threshold 100

# Check if skill should be split
scripts/skill-analyzer --path path/to/skill.md --verbose

Common Solutions:

• Module Granularity: Break down larger modules into smaller, focused components
• Dependency Optimization: Reduce inter-module dependencies and coupling
• Content Organization: Reorganize content for better progressive disclosure
• Tool Integration: Add executable tools to reduce manual overhead

Tools Not Loading Correctly

Issue: Executable tools are not accessible or fail to run

# Check tool permissions
ls -la scripts/

# Make tools executable
find scripts/ -type f -exec chmod +x {} \;

# Test individual tools
scripts/skill-analyzer --help

Common Solutions:

• File Permissions: validate all tools have execute permissions (chmod +x)
• Path Issues: Verify tools are in correct directory structure
• Python Dependencies: Install required packages (pip install -r requirements.txt)
• Shebang Lines: validate Python scripts have proper #!/usr/bin/env python3

Advanced Troubleshooting

Complexity Analysis Discrepancies

Issue: Different analysis tools give conflicting complexity assessments

# Use custom threshold for strict evaluation
scripts/skill-analyzer --path path/to/skill.md --threshold 50

# Analyze all skills in directory
scripts/skill-analyzer --path path/to/skills/ --verbose

Diagnostic Approaches:

• Threshold Tuning: Adjust complexity thresholds based on your specific requirements
• Multi-Tool Analysis: Compare results from different analysis tools
• Context Consideration: Consider skill complexity in relation to its purpose
• Historical Tracking: Monitor complexity changes over time

Module Design Issues

Issue: Modules don't follow best practices or have structural problems

# Validate against modular design principles
scripts/module_validator -d path/to/skills/ --fail-on-warnings

# Check for structural violations
scripts/module_validator -s path/to/skill.md --verbose

Design Validation Checklist:

• Single Responsibility: Each module has one clear purpose
• Clear Boundaries: Well-defined interfaces and responsibilities
• Minimal Coupling: Low inter-module dependencies
• High Cohesion: Related functionality grouped together
• Explicit Dependencies: All dependencies clearly declared

Performance Optimization

Issue: Skills are slow to load or consume excessive resources

# Token usage analysis
scripts/token-estimator -d path/to/skills/

# Identify optimization opportunities
scripts/skill-analyzer --path path/to/skill.md | grep -i recommend

Optimization Strategies:

• Progressive Loading: Load essential content first, details later
• Content Compression: Remove redundant explanations and examples
• External Resources: Move large datasets or examples to separate files
• Caching: Implement caching for frequently accessed modules
• Lazy Loading: Load modules only when actually needed

Design Pattern Validation

Single Responsibility Principle

• Each module serves one clear purpose
• No mixed concerns or responsibilities
• Focused, cohesive functionality
• Clear scope and boundaries

Validation Questions:

• Can this module be described in a single sentence?
• Does the module address only one concern?
• Would splitting this module create more complexity?

Loose Coupling

• Minimal dependencies between modules
• Clear interfaces and boundaries
• Independent testability
• No circular dependencies

Validation Questions:

• Can this module be tested in isolation?
• Are dependencies minimal and explicit?
• Would changing another module break this one?

High Cohesion

• Related functionality grouped together
• Consistent patterns within modules
• Logical organization
• Unified purpose

Validation Questions:

• Do all parts of this module belong together?
• Is the module organization logical and consistent?
• Would moving functionality improve or hurt organization?

Clear Boundaries

• Well-defined interfaces and responsibilities
• Explicit dependency relationships
• No hidden or circular dependencies
• Clear entry and exit points

Validation Questions:

• Are module boundaries clearly defined?
• Is it obvious what belongs in vs. outside the module?
• Are all dependencies explicitly declared?

Getting Help

Analysis Mode

Use --verbose flag for detailed breakdowns:

scripts/skill-analyzer --verbose --path skill.md

Help System

All tools support --help for usage guidance:

scripts/module_validator --help
scripts/token-estimator --help

Custom Thresholds

Adjust analysis parameters with --threshold:

scripts/skill-analyzer --threshold 100 --path skill.md

Batch Analysis

Process multiple skills with directory paths:

scripts/skill-analyzer --path path/to/skills/
scripts/token-estimator -d path/to/skills/

Validation Scripts

Use --fail-on-warnings for strict checking:

scripts/module_validator --fail-on-warnings -s skill.md

Modular Skills Framework

Design patterns and implementation guidelines for reusable skill components.

Core Principles

• Single Responsibility: One focused purpose per skill
• Composable Design: Skills are composable
• Clear Interfaces: Well-defined tool contracts
• Token Efficiency: Minimal context overhead

Quick Start

# Analyze existing skills
skill-analyzer --scan

# Validate module structure
module_validator --check-all

# Estimate token usage
token-estimator --skill <path>

Module Structure

skill-name/
├── SKILL.md           # Skill definition
├── modules/           # Optional sub-modules
└── scripts/           # Associated scripts

Design Patterns

Focused Modules

• Single purpose tools
• Minimal dependencies
• Clear success criteria

Hierarchical Dependencies

• Parent-child relationships
• Dependency injection
• Interface contracts

Cross-Cutting Concerns

• Shared utilities
• Common patterns
• Standard interfaces

Validation Tools

• module_validator: Structure and quality checks
• skill-analyzer: detailed skill analysis
• token-estimator: Context usage optimization

Best Practices

1. Keep skills under 1000 tokens 2. Use clear, descriptive names 3. Document tool contracts 4. Test thoroughly 5. Follow established patterns