modular-skills

name	modular-skills
description	Build composable skill modules with hub-and-spoke loading. Use when token budget is tight.
alwaysApply	false
category	workflow-optimization
tags	["architecture","modularity","tokens","skills","design-patterns","skill-design","token-optimization"]
dependencies	[]
tools	[]
usage_patterns	["skill-design","architecture-review","token-optimization","refactoring-workflows"]
complexity	intermediate
model_hint	standard
estimated_tokens	1200
modules	["modules/antipatterns-and-migration.md","modules/core-workflow.md","modules/design-philosophy.md","modules/enforcement-patterns.md","modules/implementation-patterns.md","modules/optimization-techniques.md","modules/troubleshooting.md","modules/design-patterns.md"]

When NOT To Use

• A single-file skill already inside its token budget (use abstract:skill-authoring)
• The lazy-loading contract itself (use leyline:progressive-loading)

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.