modular-skills

## Table of Contents

- [Overview](#overview)
- [Quick Start](#quick-start)
- [Workflow and Tasks](#workflow-and-tasks)
- [Quality Checks](#quality-checks)
- [Resources](#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.

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