Modular Skills

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


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