Related Pages

Related topics: System Architecture and Core Pipeline (scan → match → rank → apply), Catalog Schema, Domains, and Three-Tier Coverage

Overview and Getting Started

Loadout (claude-loadout on npm) is a catalog and discovery tool for Claude Code plugins, agents, and skills. It bundles a hand-picked set of extensions, indexes Anthropic's official plugin marketplace, and can surface community-contributed skills through a non-destructive discovery mode. The package is published to npm and ships its own Claude plugin manifest so it can be loaded directly by Claude Code clients. Source: package.json().

Purpose and Scope

The project solves a recurring problem for Claude Code users: there is no single, trustworthy place to find well-maintained plugins, and community skills are easy to miss or apply by accident. Loadout organizes the available surface area into three clearly labeled tiers so users can decide how much risk to take on. The curated tier is small and vetted; the official tier is mirrored from Anthropic; and the community tier is opt-in and never applied automatically. Source: CHANGELOG.md().

The scope is intentionally narrow. Loadout is a curator and a CLI front-end, not a plugin runtime. It does not replace Claude Code's plugin loader; it complements it by helping users decide what to load. The self-hosted plugin entry under plugins/loadout/.claude-plugin/plugin.json shows that the tool itself follows the same manifest convention it consumes, which keeps the on-disk layout predictable. Source: plugins/loadout/.claude-plugin/plugin.json().

Installation and First Run

The package is distributed through npm under the name claude-loadout, which is the conventional install path for Node-based Claude tooling. After a global install, the loadout command is available on the user's PATH and can be invoked from any project directory. The README documents the install command, the basic invocation, and the most common flags. A Korean translation is maintained alongside the English documentation, indicating that the project aims to serve a bilingual audience. Source: README.md() and README.ko.md().

For a first run, the recommended workflow is to invoke Loadout with no arguments to see the curated catalog, then re-run it with the discovery flag to inspect the broader pool of community skills. Because the community tier is labeled and never auto-applied, a new user can browse it without changing their active plugin set. Source: CHANGELOG.md().

The Three-Tier Coverage Model

The defining feature of the current release is its three-tier model for plugin coverage. Each tier represents a different trust profile and a different discovery path.

The curated tier is the default and is safe to apply wholesale. The official tier is ingested from Anthropic's marketplace and surfaced only when a plugin matches the user's declared stack, which keeps the listing focused. The community tier is the largest source of variance and is hidden behind --discover; results are explicitly labeled as unverified so users can audit them before applying. Source: CHANGELOG.md().

The catalog size of 279 items in v0.3.0 reflects the sum of these three tiers and is the headline number users cite when comparing Loadout to ad-hoc plugin hunting. Source: CHANGELOG.md().

How Loadout Fits Into a Claude Code Workflow

A typical session starts with Claude Code running as usual. When the user wants to extend it, they run Loadout, review the catalog, and apply either the curated list or a selected subset. The self-hosted plugin manifest at plugins/loadout/.claude-plugin/plugin.json is what allows Loadout to be loaded by Claude Code itself, which means the catalog and the runtime share the same configuration format. This is a deliberate design choice: it removes a class of format-conversion bugs and makes it straightforward to copy a plugin definition between Loadout's catalog and a user's project. Source: plugins/loadout/.claude-plugin/plugin.json().

The README is the primary user-facing entry point and is mirrored in Korean for accessibility. Both files describe the same commands and flags, so the workflow documented in English is identical to the one documented in Korean. Source: README.md() and README.ko.md().

Next Steps

After the initial install and listing, users typically:

1. Pin a known-good curated set as the baseline.
2. Enable the official tier for plugins that match their stack.
3. Use --discover to audit community skills before promoting any of them to the baseline.

The CHANGELOG.md file is the authoritative source for what changed between releases, including tier counts, new flags, and deprecations. Users upgrading from an earlier version should consult it first, because tier semantics and catalog totals have shifted across releases. Source: CHANGELOG.md().

Related Pages

Related topics: Overview and Getting Started, Catalog Schema, Domains, and Three-Tier Coverage, Multi-Agent Targets, Team Loadouts, Doctor, and Operations

System Architecture and Core Pipeline (scan → match → rank → apply)

Loadout is a CLI utility that detects a project's stack and recommends Claude-compatible skills, plugins, and community-built utilities. Internally it runs a strict four-stage pipeline — scan → match → rank → apply — each time the user invokes the tool. The pipeline is wired together by cli/index.js and delegates work to dedicated modules under cli/lib/.

Architecture Overview

flowchart LR
    A[CLI entry<br/>cli/index.js] --> B[scan.mjs<br/>detect stack]
    B --> C[recommend.mjs<br/>match catalog]
    C --> D[recommend.mjs<br/>rank candidates]
    D --> E[apply.mjs<br/>persist selection]
    E --> F[manifest.mjs<br/>write ledger]

The pipeline is idempotent: re-running with the same stack fingerprint and an unchanged catalog produces the same recommendations, and the manifest prevents accidental re-application of items the user already accepted or rejected. The shared filesystem conventions live in a single helper so no module embeds hard-coded directories.

Source: cli/index.js:1-80 Source: cli/lib/paths.mjs:1-60

Pipeline Stages

Stage 1 — Scan

cli/lib/scan.mjs walks the project tree (respecting .gitignore) and parses manifest files such as package.json, pyproject.toml, Cargo.toml, and go.mod. The output is a normalized stack fingerprint capturing language, framework, runtime version, and key dependencies.

cli/lib/paths.mjs centralizes filesystem conventions — locating the project root, the Claude configuration directory, and the local cache — so every downstream stage references the same absolute paths. The fingerprint becomes the input contract for the next stage.

Source: cli/lib/scan.mjs:1-120 Source: cli/lib/paths.mjs:1-60

Stage 2 — Match

cli/lib/recommend.mjs consumes the scan fingerprint and queries the unified catalog. As of v0.3.0, the catalog is composed of three tiers:

1. Curated core — 35 hand-reviewed skills and plugins maintained alongside the project.
2. Anthropic marketplace — roughly 240 official plugins, surfaced only when they match the detected stack.
3. Community skills — items surfaced through the --discover flag, explicitly labeled unverified and never auto-applied.

The match stage attaches the source tier to each candidate so downstream ranking can prioritize verified entries over community submissions.

Source: cli/lib/recommend.mjs:1-200

Stage 3 — Rank

Ranking also lives inside recommend.mjs and orders candidates by a combination of:

• Tier weight — curated > marketplace > community.
• Stack relevance score — produced during the match step from the scan fingerprint.
• Verification flag — unverified items are pushed toward the bottom of the list regardless of relevance.

The CLI surfaces the top-N results to the user. Items flagged unverified require explicit confirmation; this is the v0.3.0 safety guarantee that community skills are presented but never silently installed.

Source: cli/lib/recommend.mjs:200-360

Stage 4 — Apply

cli/lib/apply.mjs writes the approved selections into the user's Claude configuration and delegates ledger bookkeeping to cli/lib/manifest.mjs. The manifest records every applied change, including:

• Source tier and original URL.
• Resolved version at the time of application.
• Timestamp and stack fingerprint under which the item was selected.

The manifest is the single source of truth for what is installed. Because --discover-surfaced items are never auto-applied, the manifest only contains them after explicit user opt-in, preserving the boundary between "surfaced" and "applied".

Source: cli/lib/apply.mjs:1-150 Source: cli/lib/manifest.mjs:1-180

Modules and Operational Notes

Module responsibilities

• cli/index.js — CLI entry point; argument parsing and pipeline orchestration.
• cli/lib/scan.mjs — Stack detection and fingerprint generation.
• cli/lib/paths.mjs — Centralized filesystem path resolution shared by every stage.
• cli/lib/recommend.mjs — Catalog match and candidate ranking (stages 2 and 3).
• cli/lib/apply.mjs — Persistence of approved selections.
• cli/lib/manifest.mjs — Local ledger of applied items.

Source: cli/index.js:1-200

Operational guarantees

• --discover flag: triggers ingestion of the third (community) tier. Results are always labeled unverified and skipped during automatic application. This matches the v0.3.0 guarantee that community skills are surfaced but never silently installed. Source: cli/index.js:80-160
• Catalog size: 35 curated + ~240 marketplace + community skills = 279 catalog items in v0.3.0. Source: cli/lib/recommend.mjs:40-90
• Path resolution: every module imports from paths.mjs, eliminating duplicated string literals for cache and config directories. Source: cli/lib/paths.mjs:1-60

Together, these guarantees make the pipeline predictable: scan produces a stable fingerprint, match resolves against a known catalog, rank applies deterministic tier rules, and apply is gated by user intent recorded in the manifest.

Related Pages

Related topics: Overview and Getting Started, System Architecture and Core Pipeline (scan → match → rank → apply)

Catalog Schema, Domains, and Three-Tier Coverage

Purpose and Scope

Loadout (npm package claude-loadout) ships a static, JSON-only catalog that drives its plugin, skill, MCP-server, and hook recommendations for Claude Code. The catalog lives under plugins/loadout/catalog/ and totals 279 items in v0.3.0. Its role is to answer "what should I install for this stack?" deterministically at run time, without scraping or network calls.

The catalog is organized around two ideas: a domain routing table and three trust tiers (curated, official marketplace, community). Every entry shares the same JSON schema, and every recommendation flows through domains.json. Source: plugins/loadout/catalog/domains.json

Domain Routing Schema

domains.json is the single routing table that maps a project's detected stack to the catalog items Loadout should surface. Each entry pairs a stable identifier (e.g. typescript, python, kubernetes) with a human-readable label and a list of catalog-file references. Because it is pure data, contributors can add a new domain via PR without touching TypeScript.

Typical fields used downstream:

• id — stable machine identifier for matching against project detection results
• label — display name shown in --list output
• sources — file/key references to consult when the domain matches
• priority — optional hint used when ranking candidates

Domains are the only filter applied before the trust-tier logic, so a marketplace or community item is surfaced only when at least one of its declared domains matches the current project. Source: plugins/loadout/catalog/domains.json

Catalog Files and the Three Tiers

The catalog directory splits items by concern. All entries share the same record shape (id, name, domains, tier, install hint). The three tiers differ only in provenance, trust, and how they become visible. Source: plugins/loadout/catalog/ecosystem.json

Tier 1 — Curated (default)

ecosystem.json lists the ~35 items reviewed and versioned by the Loadout maintainers. They are treated as safe to recommend and, once a user accepts, safe to apply. They never carry the unverified label and appear whenever their domains match the detected stack. Source: plugins/loadout/catalog/ecosystem.json

Tier 2 — Official Marketplace (~240 items)

mcp.json, hooks.json, and skills.json mirror Anthropic's official plugin marketplace. The full set is roughly 240 entries, but Loadout does not show all of them: each entry is gated on a domain match, so a runtime whose domain is not detected is silently skipped. Because they originate from the official marketplace, they are not tagged unverified. Source: plugins/loadout/catalog/mcp.json Source: plugins/loadout/catalog/hooks.json Source: plugins/loadout/catalog/skills.json

Tier 3 — Community (opt-in via `--discover`)

community.json holds user-contributed items, with the caveman token-saver skill as a representative example. Community items are always labeled unverified and are only surfaced when the user explicitly passes --discover. They are never auto-applied: selecting one requires an additional confirmation step. Source: plugins/loadout/catalog/community.json

Discovery Flow

The end-to-end flow when a user invokes claude-loadout:

1. Detect project domains (TS, Python, K8s, etc.) from the working tree.
2. Resolve matching entries in domains.json.
3. Pull Tier 1 items from ecosystem.json whose domains match.
4. Append Tier 2 items from mcp.json, hooks.json, skills.json whose domains match.
5. If --discover is passed, append Tier 3 items from community.json, tagged unverified.
6. Rank, present, and let the user pick. Curated and marketplace items can be applied directly; community items require explicit opt-in regardless of --discover.

This pipeline keeps trust proportional to provenance: curated is on by default, marketplace is on by condition, community is opt-in and labeled. Source: plugins/loadout/catalog/domains.json Source: plugins/loadout/catalog/community.json

Related Pages

Related topics: System Architecture and Core Pipeline (scan → match → rank → apply), Catalog Schema, Domains, and Three-Tier Coverage

Multi-Agent Targets, Team Loadouts, Doctor, and Operations

Loadout (claude-loadout, v0.3.0) is an npm-distributed CLI for installing, sharing, and verifying plugin and skill bundles across several AI coding agents. This page documents the four operational pillars that keep the tool safe to use inside a team: target resolution, manifest-driven team loadouts, the doctor diagnostic command, and the broader operations layer that powers discovery.

Multi-Agent Target Resolution

Loadout does not hard-code a single host. Instead, every supported agent is described as a *target* in cli/lib/targets.mjs, which maps a logical agent id (claude-code, codex, cursor, aider, windsurf, etc.) to its on-disk configuration root and to the file layout it expects for skills, commands, and agents. Each target entry typically declares:

• A name and human-friendly label.
• A configDir resolver that delegates to cli/lib/paths.mjs for cross-platform path expansion.
• A list of supported *payload kinds* (skills, agents, commands, hooks).

When a user runs loadout install <id> or loadout sync, the targets module is consulted to decide *where* each payload is written. Source: cli/lib/targets.mjs:1-80. Path expansion (XDG, ~/.config, environment overrides) is centralized in cli/lib/paths.mjs so the same target can be exercised on macOS, Linux, and Windows without platform forks. Source: cli/lib/paths.mjs:1-60.

Because the marketplace catalog totals 279 items in v0.3.0 (35 curated + ~240 official + discovery-only community), target resolution is also used by the resolver to filter items that are *not compatible* with the host the user is targeting, surfacing only entries whose targets array includes the active agent. Source: .claude-plugin/marketplace.json:1-40.

Team Loadouts and Manifests

A *loadout* is the unit of sharing. It is a JSON manifest that names a set of catalog items, pins their versions, and assigns them to one or more targets. The parsing, validation, and serialization of these manifests is handled by cli/lib/manifest.mjs. The module is responsible for:

• Reading a loadout file from disk or remote URL.
• Resolving each entry against the bundled marketplace (.claude-plugin/marketplace.json) and any user-added sources.
• Expanding version ranges and reporting conflicts before any write happens.
• Producing a deterministic install plan grouped per target.

A typical team workflow is: maintain a team.loadout.json in version control, run loadout sync team.loadout.json on onboarding, and rely on the same plan to reproduce identical tooling across every teammate regardless of which IDE/agent they prefer. Source: cli/lib/manifest.mjs:1-120.

The browse skill, documented at plugins/loadout/skills/browse/SKILL.md, teaches the host agent how to query this same catalogue through the CLI, so teams can author manifests directly from a chat session without reading the source.

Doctor and Diagnostic Operations

loadout doctor is the safety net. Implemented in cli/lib/doctor.mjs, it is a read-only command that walks every active target and reports structural and version problems. The check list generally covers:

• Missing or unreadable config directories for each declared target.
• Stale symlinks or duplicate plugin installs caused by partial syncs.
• Manifest entries that no longer exist in the merged catalogue.
• Mismatches between the installed payload version and the version declared in the team manifest.
• Schema regressions introduced by a host agent upgrade.

The doctor is designed to be invoked in CI as a non-destructive gate before committing a loadout change. Source: cli/lib/doctor.mjs:1-140.

flowchart LR
  A[Loadout Manifest] --> B[Manifest Resolver]
  B --> C{Per-target Plan}
  C --> D[Target A: claude-code]
  C --> E[Target B: codex]
  C --> F[Target N: ...]
  D --> G[Doctor: verify]
  E --> G
  F --> G
  G -->|fail| H[Repair / re-sync]
  G -->|pass| I[Ready]

Operations and Discovery Layer

The operations layer ties targets, manifests, and doctor together. It exposes the --discover flag introduced in v0.3.0, which surfaces community-published skills (such as the caveman token-saver) without auto-applying them. Discovered items are always labeled *unverified* and require an explicit confirmation step before they enter the install plan. This three-tier coverage (curated → marketplace → community) lets teams adopt new skills safely while keeping the trusted set small. Source: .claude-plugin/marketplace.json:1-80.

Operational commands include status, diff, sync, and update. All four share a common contract: they consume a manifest plan, resolve it through the targets module, and then either write or report. None of them bypass the doctor checks at the end of a write phase, which means a successful sync is also a green doctor run by construction. Source: cli/lib/targets.mjs:80-160, Source: cli/lib/manifest.mjs:120-220.

Cross-cutting Concerns

A few invariants are enforced wherever these modules meet:

• Idempotence: re-running sync against the same manifest must be a no-op. Source: cli/lib/targets.mjs:160-220.
• Target-aware filtering: a manifest may declare items for *some* targets only; the resolver never installs a payload on a host that does not support it. Source: .claude-plugin/marketplace.json:1-80.
• Path hygiene: all file writes go through paths.mjs so symlinks, permissions, and OS-specific locations stay consistent. Source: cli/lib/paths.mjs:60-140.
• Skill-driven authoring: complex workflows (browsing, planning, debugging) are delegated to skills such as plugins/loadout/skills/browse/SKILL.md rather than hard-coded CLI subcommands.

Together, these modules turn Loadout from a single-agent installer into a team-scale operations surface: declare a loadout once, ship it through your normal review process, and let the CLI reproduce the exact same environment for every developer and every supported agent.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/sukoji/loadout

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/sukoji/loadout

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/sukoji/loadout

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/sukoji/loadout

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/sukoji/loadout

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/sukoji/loadout

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/sukoji/loadout

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using loadout with real data or production workflows.

• v0.3.0 — Loadout - github / github_release
• v0.2.1 — Loadout - github / github_release
• v0.2.0 — Loadout - github / github_release
• v0.1.0 — Loadout - github / github_release
• Configuration risk requires verification - GitHub / issue