---
name: antipatterns-and-migration
description: Common anti-patterns in modular skill development and migration strategies for improving existing monolithic skills
category: refactoring
tags: [antipatterns, migration, modular-skills, refactoring, best-practices]
dependencies: [modular-skills]
tools: [skill-analyzer]
complexity: advanced
estimated_tokens: 1000
---

# 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.

---
name: core-workflow
description: Primary workflow for designing and building modular skills with systematic evaluation and architecture patterns
category: workflow
tags: [core-workflow, modular-skills, skill-design, architecture, evaluation]
dependencies: [modular-skills]
tools: [skill-analyzer]
complexity: intermediate
estimated_tokens: 800
---

# 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.

```bash
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.

```bash
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.

---
name: design-philosophy
description: Core principles and philosophical approach to designing modular skills with emphasis on simplicity, maintainability, and user experience
category: design
tags: [design-philosophy, modular-skills, principles, architecture, user-experience]
dependencies: [modular-skills]
tools: []
complexity: beginner
estimated_tokens: 500
---

# 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**:

```text
# Follows the conventions
skills/modular-skills/modules/design-patterns.md
scripts/skill_analyzer.py
skills/api-scaffolding/scripts/backend-generator

# Does not
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 so a session finds the skill when it fits and skips it when it does not. 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:

```yaml
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
- [ ] Triggers describe fit accurately, without pressure language
- [ ] 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:

| Category | Description | Examples |
|----------|-------------|----------|
| **Discipline-Enforcing** | Process must be followed exactly | TDD, security, compliance |
| **Workflow** | Step-by-step approach to tasks | Brainstorming, debugging, review |
| **Technique** | Best practices, optional patterns | Caching, optimization |
| **Reference** | Information retrieval | API docs, examples |

## How Hard Should the Description Push

The description's job is discovery: helping a session find this skill
when it is the right one, and skip it when it is not. That is a
matching problem, and it is solved by accurate triggers rather than by
pressure.

This section used to prescribe four intensity tiers, escalating to
"YOU MUST", "NON-NEGOTIABLE", "NEVER skip", "No exceptions" for the
top one. The workflow tier told the reader: "If you think this doesn't
apply, reconsider - it probably does."

That instruction is the problem in one line. It tells a session to
distrust its own read of the situation in favour of an author who
never saw the situation. When the author was right, it adds nothing
that accurate triggers would not have. When the author was wrong, it
is the only thing standing between the session and the correct call.

Write the description to be accurate about fit:

```yaml
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.
```

If a skill is being passed over where it genuinely applies, the fix is
in the triggers: the words are wrong, too generic, or absent. Pressure
language papers over a discovery bug and leaves it in place.

### Where a Line Genuinely Has to Hold

A few skills guard something unrecoverable: a trust boundary, a
destructive command, a safety-critical contract. Those say so plainly,
once, in the body, naming what is behind the line:

```markdown
Never pass unvalidated input to this API. It reaches the query
planner directly, and `tests/security/test_injection.py` is what
catches a regression here.
```

Plain, specific, and checkable beats emphatic. Note the difference
from the tiers above: this constrains one concrete action and says
why, rather than instructing a reader not to trust their own judgment
in general. `Skill(pensive:safety-critical-patterns)` is the
documented case where defense in depth is required by design, and it
is deliberately exempt from this guidance.

## 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

```yaml
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

| Your Skill Domain | Common Overlaps | Resolution |
|------------------|-----------------|------------|
| Skill creation | Skill evaluation | modular-skills vs skills-eval |
| Debugging | Code review | systematic-debugging vs code-review |
| Planning | Brainstorming | writing-plans vs brainstorming |
| Testing | Security | TDD vs security-review |

## 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:

```bash
# Check trigger isolation compliance
python plugins/abstract/scripts/compliance_checker.py path/to/skill
```

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

## Related Resources

- [Trigger Patterns](../../../shared-modules/trigger-patterns.md) - Description field templates
- [Instruction Strength](../../skill-authoring/modules/persuasion-principles.md) - How much to push, and when
- [Trigger Isolation Analysis](../../skills-eval/modules/trigger-isolation-analysis.md) - Evaluation criteria

---
name: implementation-patterns
description: Implementation patterns and best practices for building modular skills with consistent architecture and maintainable code
category: implementation
tags: [implementation-patterns, modular-skills, best-practices, code-organization, development]
dependencies: [modular-skills]
tools: []
complexity: intermediate
estimated_tokens: 900
---

# 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.

    ```yaml
    ---
    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.

```bash
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

| Strategy | Impact | When to Use |
|----------|--------|-------------|
| **Externalize Python modules** | 60-70% reduction | Heavy implementations (>20 lines) |
| **Consolidate similar functions** | 15-20% reduction | Repeated patterns with minor variations |
| **Replace code with structured data** | 10-15% reduction | Configuration-driven logic |
| **Progressive loading patterns** | 5-10% reduction | Multi-stage workflows |

## 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

---
name: troubleshooting
description: Common issues and solutions for modular skills development with diagnostic tools and debugging strategies
category: troubleshooting
tags: [troubleshooting, debugging, modular-skills, diagnostics, common-issues]
dependencies: [modular-skills]
tools: [module_validator]
complexity: intermediate
estimated_tokens: 600
---

# Modular Skills Troubleshooting

## Common Issues and Solutions

### Module Validation Failures

**Issue**: `module_validator` reports structural violations or compliance issues

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:
```bash
scripts/skill-analyzer --verbose --path skill.md
```

### Help System
All tools support `--help` for usage guidance:
```bash
scripts/module_validator --help
scripts/token-estimator --help
```

### Custom Thresholds
Adjust analysis parameters with `--threshold`:
```bash
scripts/skill-analyzer --threshold 100 --path skill.md
```

### Batch Analysis
Process multiple skills with directory paths:
```bash
scripts/skill-analyzer --path path/to/skills/
scripts/token-estimator -d path/to/skills/
```

### Validation Scripts
Use `--fail-on-warnings` for strict checking:
```bash
scripts/module_validator --fail-on-warnings -s skill.md
```