Catalog System

Tokenomics is not a principle that applies only to tokens. Each template file deployed into a project is ultimately a context candidate that a session will load. The catalog system reduces this cost from the initialization stage on, with the principle of “deploy only what is needed.”

MoAI-ADK’s catalog system manages all agents, skills, and rules with a 3-tier manifest (catalog.yaml). The default deployment is slim mode, deploying only the core templates (core) so initialization is fast and the files left in the project are lightweight. When a full deployment is needed, use the --all flag.

Every deployment target belongs to one of three tiers.

The catalog manifest is defined in YAML at internal/template/catalog.yaml.

catalog:
  core:                        # always deployed (slim-mode default)
    skills:
      - name: moai-workflow-tdd
        tier: core
        path: templates/.claude/skills/moai-workflow-tdd/
        hash: 6f89fb72...      # content hash (integrity verification)
        version: 1.0.0
    agents:
      - name: manager-spec
        tier: core
        path: templates/.claude/agents/moai/manager-spec.md
        hash: a1b2c3d4...
        version: 1.0.0
  optional_packs:              # deployed with the --all flag
    backend:
      - name: moai-domain-backend
        tier: optional-pack:backend
        path: templates/.claude/skills/moai-domain-backend/
        hash: ...
    frontend:
      - name: moai-domain-frontend
        tier: optional-pack:frontend
        path: templates/.claude/skills/moai-domain-frontend/
        hash: ...
  harness_generated:           # deployed with the --all flag
    skills: []
    agents:
      - name: builder-harness
        tier: harness-generated
        path: templates/.claude/agents/moai/builder-harness.md
        hash: ...

Each entry has name, tier, path, hash, and version fields. The hash field holds a content hash, so the loader can verify whether a deployed file is corrupted or was altered arbitrarily. The entry-point file inside a skill directory is SKILL.md (not lowercase skill.md).

The default deployment is slim mode, deploying only catalog.core. When a full deployment is needed, use the --all flag or the MOAI_DISTRIBUTE_ALL=1 environment variable.

# Slim install (default — core only)
moai init my-project

# Full install (core + optional_packs + harness_generated)
moai init --all my-project

# Full install via environment variable
MOAI_DISTRIBUTE_ALL=1 moai init my-project

Deployment works in two stages.

1. catalog.core (skills + agents) is always included — the slim-mode default
2. When the --all flag or the MOAI_DISTRIBUTE_ALL=1 environment variable is set, catalog.optional_packs and catalog.harness_generated are additionally deployed

The LoadCatalog() function loads the manifest type-safely. Because it validates by struct rather than relying on string parsing, manifest errors are caught before deployment.

• 3-tier classification validation
• Hash integrity check (Hash Sentinel)
• Missing-field detection
• 100% test coverage

# Default initialization — core only (slim mode)
moai init my-project

# Full initialization — core + optional_packs + harness_generated
moai init --all my-project

moai update operates against the same catalog. A project initialized as slim updates core only, and a project initialized with --all updates everything.

# Catalog-based update
moai update                  # decided automatically by the initialization mode

• Installation — installation guide
• Initial Setup — the init wizard
• Update — update guide
• Skill Guide — skill authoring guide