Architecture Overview

Documentation > Architecture > Architecture Overview

gsd-skill-creator is a bounded learning system for Claude Code with 50+ subsystems organized into a strict 6-layer dependency hierarchy. The system manages skill creation, observation, detection, composition, and application — all within a controlled token budget of 2–5% of Claude’s context window.

This documentation covers the internal architecture for contributors working on the codebase and library consumers building integrations.

System Architecture Diagram

+============================================================================+
|  Layer 6: Entry Points                                                     |
|  cli/  hooks/  mcp/  launcher/  terminal/  console/                        |
+============================================================================+
         |                         |
         v                         v
+============================================================================+
|  Layer 5: Orchestration                                                    |
|  workflows/  skill-workflows/  orchestrator/  initialization/              |
+============================================================================+
         |                         |
         v                         v
+============================================================================+
|  Layer 4: Core Processing                                                  |
|  application/    simulation/    learning/    calibration/                   |
|  [6-stage pipeline: Score → Resolve → ModelFilter → CacheOrder → Budget → Load] |
+============================================================================+
         |                         |
         v                         v
+============================================================================+
|  Layer 3: Analysis                                                         |
|  observation/  detection/  activation/  conflicts/  composition/            |
|  agents/  teams/  discovery/  brainstorm/  evaluator/  retrieval/           |
+============================================================================+
         |                         |
         v                         v
+============================================================================+
|  Layer 2: Infrastructure                                                   |
|  storage/  validation/  embeddings/  testing/  safety/  disclosure/         |
+============================================================================+
         |                         |
         v                         v
+============================================================================+
|  Layer 1: Foundation                                                       |
|  types/  identifiers/  portability/  events/  roles/  capabilities/         |
+============================================================================+

Layered Design Philosophy

Dependencies flow downward only. Lower layers (types, storage) have no dependencies on higher layers (CLI, workflows). This enables:

Testability: Each layer can be tested in isolation
Reusability: Core modules work independently of the CLI
Maintainability: Changes in one layer do not ripple upward
Composability: The pipeline architecture allows stages to be inserted, replaced, or extended

The 6-Stage Skill Loading Pipeline

The central architectural concept is the 6-stage skill application pipeline defined in src/application/. Every session activation flows through these stages in order:

// src/application/skill-pipeline.ts
export interface PipelineStage {
  readonly name: string;
  process(context: PipelineContext): Promise<PipelineContext>;
}

export class SkillPipeline {
  private stages: PipelineStage[] = [];

  addStage(stage: PipelineStage): void;
  insertBefore(targetName: string, stage: PipelineStage): void;
  insertAfter(targetName: string, stage: PipelineStage): void;
  async process(context: PipelineContext): Promise<PipelineContext>;
}

Stage	Module	Responsibility
1. Score	`stages/score-stage.ts`	Match intent via TF-IDF or embedding similarity, score relevance
2. Resolve	`stages/resolve-stage.ts`	Resolve inheritance chains, detect conflicts
3. ModelFilter	`stages/model-filter-stage.ts`	Filter by quality/balanced/budget model profiles
4. CacheOrder	`stages/cache-order-stage.ts`	Reorder skills to maximize cache hits
5. Budget	`stages/budget-stage.ts`	Enforce 2–5% context window budget with tiered priority
6. Load	`stages/load-stage.ts`	Inject selected skills into the session context

Token Budget Architecture

Skills consume 2–5% of Claude’s context window (4,000–10,000 tokens out of 200K). The BudgetStage partitions skills into three priority tiers:

Critical: Load even past the standard budget, up to a hard ceiling
Standard: Load within the normal budget allocation
Optional: First to be skipped when budget is tight

// src/application/stages/budget-stage.ts
export class BudgetStage implements PipelineStage {
  readonly name = 'budget';

  constructor(
    private tokenCounter: TokenCounter,
    private profile: BudgetProfile,
    private skillStore: SkillStore,
    private contextWindowSize: number = 200_000
  ) {}
}

Ecosystem Scale

gsd-skill-creator is part of a larger system:

Subsystem	Scale	Description
Brainstorm	8 agents	Multi-agent ideation with structured debate and synthesis
Electronics Pack	5 engines, 77 labs	Hardware simulation with chip-level accuracy
MCP	Gateway + Bridge	Model Context Protocol integration layer
Cloud Ops	31 agents, 3 crews	Infrastructure management and deployment orchestration
Skill Core	50+ modules	The bounded learning system documented here

Quick Navigation

Document	Purpose
System Layers	All 50+ modules with real TypeScript interfaces and dependency matrix
Data Flows	Three core pipelines: Skill Creation, Session Activation, Pattern-to-Agent Composition
Extending the System	Extension points with working code examples for custom validators, storage backends, and conflict detectors
Storage	File-based storage architecture, SKILL.md format, scope resolution