SkillStore Architecture

Overview

SkillStore is a commercial platform that sells skill packages for Claude Code. Skill packages give Claude Code domain-specific knowledge and structured processes, turning it into a specialized assistant for software project lifecycle tasks. The first product line is DevFlow, covering presale, agile delivery, post-project, documentation processing, and project bootstrapping.

The platform consists of a CLI tool (skillstore), a local registry of packages, a shared framework of free skills and automation hooks, and the commercial packages themselves. Packages install into a project's .claude/ directory, integrating directly with Claude Code's native skill and command system.

Directory Structure

SkillStore/
├── cli/                # CLI tool — @skillstore/cli (Commander.js + TypeScript)
├── packages/           # Commercial skill packages (devflow-presale, devflow-agile, etc.)
├── shared/             # Shared templates, free framework skills, quality checks
├── registry/           # Package index (packages.json) and category definitions
├── bundles/            # Bundle definitions combining multiple packages at a discount
└── docs/               # Project documentation

cli/

The skillstore CLI built with Commander.js, chalk, ora, and fuse.js. Source lives in cli/src/ with these modules:

packages/

Each subdirectory is a self-contained skill package. Current packages:

• devflow-presale — RFP analysis, proposals, estimation, risk, solution design, pricing (6 skills)
• devflow-agile — 10 role-based skills covering PM, Scrum Master, BA, architect, tech lead, team lead, developer, QA, UI/UX, DevOps
• devflow-postproject — Handover, maintenance/support, retrospective, client feedback (4 skills)
• devflow-docs — PDF processing, Excel analysis, document generation, presentation review (4 skills)
• devflow-bootstrap — Project scaffolding, CI/CD setup, environment config, code standards init (4 skills)

shared/

Contains two major sections:

• skill-template/ — The canonical SKILL.md template that all skills must follow.
• quality-checks/ — Skill quality checklist for validation.
• framework/ — The shared framework installed in template mode (see below).

registry/

• packages.json — Array of all packages with metadata: name, description, version, skill list, free skills, pricing.
• categories.json — Category definitions (currently: "devflow").

bundles/

• devflow-complete.json — Bundles all 5 DevFlow packages (28 skills total) at a discounted price ($99 vs. individual pricing).

Package Anatomy

Every package follows this structure:

packages/<package-name>/
├── manifest.json          # Package metadata: name, version, skills, freeSkills, commands, modes
├── package.json           # Node.js package metadata
├── plugin/                # Content installed in plugin mode
│   ├── skills/            # Skill directories (SKILL.md + references/ + assets/)
│   └── commands/          # Slash command definitions (.md files)
└── template/              # Additional content installed in template mode
    ├── agents/            # Agent definitions (orchestrators with personas)
    └── workflows/         # Workflow definitions (multi-step processes)

manifest.json declares the package contract:

• skills — All skills in the package
• freeSkills — Skills available without a license (one per package)
• commands — Slash commands the package provides
• modes — Supported install modes (["plugin", "template"])

Shared Framework

The shared/framework/ directory contains free, package-agnostic components that are installed alongside commercial packages in template mode:

shared/framework/
├── skills/        # Free development skills (frontend, backend, databases, mobile, security, etc.)
├── agents/        # Reusable agents (code-reviewer, debugger, planner, tester, docs-manager, etc.)
├── protocols/     # Orchestration protocol, error recovery protocol
├── quality/       # Review protocol, verification protocol
├── rules/         # Development rules
├── workflows/     # Primary workflow, documentation management
├── config/        # skillstore.config.json, settings.json, CLAUDE.md.template
├── hooks/         # Automation hooks (quality-gate, scout-block, modularization, notifications)
└── commands/      # Shared commands (cook, fix, git/cm, git/pr)

The framework skills (frontend-development, backend-development, databases, mobile-development, debugging-investigation, codebase-analysis, security-audit, ui-generation) are free for all users and provide foundational development knowledge.

Data Flow

Installation Pipeline

1. CLI reads registry/packages.json
2. User searches or browses available packages
3. User selects a package to install
4. CLI checks license (free skills always pass, paid skills need activation)
5. CLI installs to project's .claude/ directory:

   Plugin mode:                        Template mode:
   ├── .claude/skills/  ← plugin/skills    ├── .claude/skills/     ← plugin/skills + framework/skills
   └── .claude/commands/ ← plugin/commands  ├── .claude/commands/   ← plugin/commands + framework/commands
                                            ├── .claude/agents/     ← template/agents + framework/agents
                                            ├── .claude/workflows/  ← template/workflows + framework/workflows
                                            ├── .claude/config/     ← framework/config
                                            ├── .claude/rules/      ← framework/rules
                                            ├── .claude/hooks/      ← framework/hooks
                                            ├── .claude/protocols/  ← framework/protocols
                                            └── .claude/quality/    ← framework/quality

Plugin mode is minimal: it copies only skills and commands, suitable for users who want specific capabilities without the full framework.

Template mode is comprehensive: it copies everything including agents, workflows, hooks, configuration, and the full shared framework. This gives users a complete Claude Code development environment.

Agent-Skill-Command Relationship

Commands (user-facing entry points)
  │
  ├── /presale → Routes to appropriate skill based on task
  ├── /presale:estimate → Directly activates estimation skill
  └── /presale:analyze → Directly activates requirement-analysis skill
  │
  ▼
Agents (orchestrators with personas and judgment)
  │
  ├── presale-lead → Coordinates full presale cycle
  │     Activates skills in sequence: requirement-analysis → solution-design
  │     + estimation (parallel) → risk-assessment → proposal-writer → pricing-strategy
  │
  └── agile-coach, bootstrap-specialist, docs-specialist, etc.
  │
  ▼
Skills (atomic knowledge units)
  │
  ├── SKILL.md → Process overview + triggers
  ├── references/ → Detailed frameworks, checklists, techniques
  └── assets/ → Sample outputs, templates

• Commands are user-facing entry points. A user types /presale or /presale:estimate and the command routes to the right skill or agent. Commands are Markdown files with YAML frontmatter (description, argument-hint).
• Agents are autonomous orchestrators with defined personas (e.g., "Senior Presale Lead with 15+ years of experience"). They coordinate multiple skills in sequence or parallel, handle errors, and produce comprehensive deliverables. Agents declare their tools, follow retry policies, and use checkpoint protocols for resumability.
• Skills contain the actual domain knowledge. Each skill is a self-contained folder with a concise SKILL.md (under 100 lines) that defines triggers, process steps, and output requirements. Detailed knowledge lives in references; example deliverables live in assets.

Configuration Hierarchy

Configuration flows from general to specific, with later layers overriding earlier ones:

1. skillstore.config.json (shared/framework/config/)
   ├── models: primary (sonnet), lightweight (haiku), fallback (haiku)
   ├── thresholds: maxFileLines (200), maxRetries (3), agentTimeoutMs (180000)
   ├── strictness: "balanced"
   ├── team: mode, roles
   └── hooks: qualityGate, docsSync, notifications (discord, telegram)

2. settings.json (shared/framework/config/)
   └── Hook definitions: PreToolUse, PostToolUse, Stop handlers

3. Package-level config
   └── manifest.json per package (skills, freeSkills, commands, modes)

4. User overrides
   └── ~/.skillstore/config.json (user-level preferences)

Hooks System

Hooks automate quality and safety checks by intercepting Claude Code tool usage. They are defined in settings.json and run as shell/node commands:

PreToolUse Hooks

Executed before a tool runs. Can block the operation (exit code 2).

• scout-block.js — Blocks Bash commands that access restricted directories (node_modules, .git, dist, build, __pycache__). Whitelists safe commands (git, pnpm, npm). Fail-open design: errors allow the command through.

PostToolUse Hooks

Executed after a tool completes. Non-blocking (always exit 0), but inject warnings as additional context.

• quality-gate.js — Checks files after Write/Edit: warns on files exceeding maxFileLines, TODO/FIXME/HACK comments, and potential secrets/credentials.
• modularization-hook.js — Enforces modular file structure after write operations.

Stop Hooks

Executed when Claude Code completes a conversation turn.

• discord-notify.sh — Sends Discord notification (if configured).
• telegram-notify.sh — Sends Telegram notification (if configured).

License System

Format

License keys follow the pattern: SS-{tier}-{packageHash}-{timestamp}-{hmacSignature}

• SS — Static prefix identifying SkillStore licenses
• tier — FREE, SINGLE, or BUNDLE
• packageHash — First 8 hex chars of HMAC-SHA256(packageName)
• timestamp — Base-36 encoded Unix timestamp
• signature — First 16 hex chars of HMAC-SHA256(payload)

Validation

All validation is offline using HMAC-SHA256. No network calls, no license server. The CLI recomputes the HMAC signature from the payload and compares it against the signature in the key.

Access Tiers

License data is stored at ~/.skillstore/license.json. The skillstore activate command validates and persists license keys.