Standalone Marketplace Mode¶

Standalone marketplace mode lets you deploy the SkillMeat web front-end as a marketplace-only application that connects to any SkillMeat API instance. It is controlled by the build-time flag NEXT_PUBLIC_STANDALONE_MARKETPLACE.

What it does¶

When NEXT_PUBLIC_STANDALONE_MARKETPLACE=true:

Root URL (/) redirects to /marketplace immediately (server-side, no flash of content).
Navigation sidebar shows only the Marketplace section and (for signed-in users) workspace options. Library, Projects, Workflows, Integrations, and all other collection-centric sections are hidden because they require a locally-managed SkillMeat collection.
Non-marketplace routes (/artifacts, /projects, /workflows, etc.) are redirected to /marketplace at the Edge middleware layer before any page code runs.

Users see a curated marketplace experience optimized for discovering, installing, and managing artifacts. The v1 standalone marketplace includes full-text search, type/tag filtering, grouped views, curated collections, a streamlined install workflow with per-target commands and pack downloads, import with dry-run preview, and a workspace for managing local installs.

What's New in v1¶

The standalone marketplace now includes:

Browse & Collections: Discover artifacts through the marketplace home, featuring trending artifacts and your personal collections surfaced as a placeholder (curated collections are planned for v2)
Collection Detail Pages: Explore curated collections with artifact filters, trust indicators, and one-click install
Install Workflow: Choose your target environment (Claude Code, Cursor, or Generic), copy the install command, or download a pack file (.skillmeat-pack, .zip, or .tar.gz)
Import Wizard: Three-step stepper (Select Source → Scan & Review → Confirm Import Plan) with dry-run preview showing confidence levels and conflict detection before any changes
My Installs Workspace: Signed-in users can track installed artifacts, check for updates, sync lockfiles, and manage local packs
Trust & Supply Chain Signals: Every artifact displays verification status, content hashes, and SkillBOM attestation

The following paths are always allowed through in standalone mode:

Prefix	Purpose
`/marketplace`	Marketplace browse, collections, item pages, sources
`/marketplace/collections/[slug]`	Curated collection detail pages
`/marketplace/installs`	My Installs workspace (signed-in only)
`/auth`	Login / signup (auth follows the target instance)
`/api`	API proxy routes
`/settings`	Settings page (API keys, general preferences)

Browse & Discover¶

Homepage¶

The marketplace homepage displays:

Global Search: Full-text search with ⌘K keyboard shortcut
Categories & Browse Options: Discover by type (Skills, Agents, Commands, MCP Servers, Bundles, Context Packs, Templates)
Featured Collections: Curated collections of related artifacts
Popular & Trending Artifacts: Grid or list view with filtering and sorting

Collection Detail Pages¶

Navigate to /marketplace/collections/[slug] to explore a curated collection:

Collection Header: Icon, title, description, trust status
Statistics: Artifact count, version, installation count, maintainer info
Faceted Browse: Filter by artifact type, category, or tag
One-Click Install: Install the entire collection or individual artifacts
Links: Documentation, GitHub repository, changelog

Filtering & Search¶

On any browse page, use the filter bar to narrow results by:

Type: Skill, Agent, Command, MCP Server, Bundle, Context Pack, Template
Source: GitHub, Curated, or other sources
Trust Level: Verified, Trusted, or Community
Tags: Custom tags for organization
Status: (in My Installs) Up to date, Updates available, Local pack

Install Workflow¶

Step 1: Choose Your Target¶

When viewing an artifact, click Install to open the install workflow.

A modal appears with three target options:

Claude Code: Install to your Claude Code collection
Cursor: Install to Cursor's artifacts directory
Generic Project: Install to any project directory

Step 2: Copy the Install Command¶

The workflow displays a ready-to-copy shell command:

skillmeat install artifact-name --target claude

or

skillmeat install artifact-name --target cursor

Click Copy to copy the command to your clipboard, then paste and run it in your terminal.

Note on Version Pinning: The command displays the current version (e.g., @1.2.3), but CLI warnings will alert you if a newer version is available. Version pinning is shown for reference but not enforced at install time — you can always update to the latest version using the --upgrade flag.

Step 3: Download a Pack (Optional)¶

Instead of using the CLI command, you can download the artifact as a standalone pack file:

.skillmeat-pack (Recommended): Optimized binary format with metadata and integrity verification
.zip: Standard ZIP archive for universal compatibility
.tar.gz: Compressed TAR archive for Unix-like systems

Download a pack file, extract it, and follow the included instructions to integrate it into your project.

Import Workflow: Dry-Run Preview¶

The import workflow (under Marketplace → Sources) guides you through a three-step stepper to safely preview and confirm imports:

Step 1: Add Source¶

Select or create a marketplace source (GitHub repository, local directory, or URL).

Configure: - Repository URL: The GitHub repository containing artifacts - Branch/Tag/SHA: Which version to scan (default: main branch) - Root Directory (optional): Scan a specific subdirectory (useful for monorepos)

Click Next to proceed to scanning.

Step 2: Scan & Select Artifacts¶

The system scans the source and displays detected artifacts.

For each artifact, review:

Artifact Name & Description: What will be imported
Type: Skill, Agent, Command, etc.
Detected Path: Where it was found in the repository
Confidence: High/Medium confidence indicator
Dedupe Outcome: Whether it's new, a new version, or a duplicate
Warnings: Break changes or name conflicts

Use checkboxes to select which artifacts to import. Click Next to review the import plan.

Step 3: Review Import Plan¶

Before any changes are made, review the complete import plan:

Import Summary: Count of new artifacts, new versions, conflicts, and duplicates detected
Warnings Section: Any detected conflicts or breaking changes
Target Collection: Where artifacts will be imported
Trust & Governance: Shows how the artifacts will be trusted/verified

Click Confirm Import to proceed. The system will execute exactly the plan shown — no surprises.

Canceling or Saving¶

Save for Later: Bookmark the import plan to complete later
Cancel Import: Exit without making any changes

Why Dry-Run Matters: This preview step prevents accidental overwrites, conflicts, or unexpected changes. You see exactly what will happen before it happens.

My Installs Workspace¶

Signed-in users can access their local install management at /marketplace/installs.

Overview Stats¶

At the top of the workspace, four stat cards show:

Installed: Total count of installed artifacts
Up to Date: How many are running the latest version
Updates Available: How many have newer versions
Local Packs: Offline artifact packs in your environment

Installs Table¶

View and manage all installed artifacts in a table:

Column	Purpose
Artifact	Name, description, and type badge
Type	Skill, Agent, Command, etc.
Source	Where it was installed from
Location	Which environment (Claude Code, Cursor, etc.)
Current Version	Version you have installed
Latest Version	Most recent available version
Status	Up to date, Update available, or Local pack
Last Synced	When the artifact's status was last checked
Actions	Update, View, Reinstall, or more (…)

Local Environment¶

On the right side, a panel shows:

Default Profile: Your active installation profile
Lockfile Status: Whether your lockfile is up to date
SkillBOM Verification: Supply chain verification status
Registry Connectivity: Whether the marketplace is reachable

Quick Actions¶

Sync All: Check for updates across all installed artifacts
Rebuild Lockfile (Disabled in v1): This feature will be available in a future release. For now, use the CLI: skillmeat manifest lock --rebuild
Export SkillBOM: Generate a supply-chain attestation file

Build and Run Recipe¶

Local Development¶

Against a remote instance¶

# From skillmeat/web/
NEXT_PUBLIC_STANDALONE_MARKETPLACE=true \
NEXT_PUBLIC_API_URL=https://your-skillmeat-instance.example.com \
pnpm dev

Or add the vars to skillmeat/web/.env.local:

NEXT_PUBLIC_STANDALONE_MARKETPLACE=true
NEXT_PUBLIC_API_URL=https://your-skillmeat-instance.example.com

Against your local API¶

NEXT_PUBLIC_STANDALONE_MARKETPLACE=true \
pnpm dev

The app will proxy API calls to http://localhost:8000 (default).

Production Build¶

cd skillmeat/web
NEXT_PUBLIC_STANDALONE_MARKETPLACE=true \
NEXT_PUBLIC_API_URL=https://your-skillmeat-instance.example.com \
pnpm build

The flags are compiled into the bundle at build time. The resulting .next/ output is a marketplace-only application.

Container Build¶

Pass the flags as Docker build args. The Dockerfile exposes them via ARG / ENV pairs (see deploy/CLAUDE.md for the container build conventions):

docker build \
  --build-arg NEXT_PUBLIC_STANDALONE_MARKETPLACE=true \
  --build-arg NEXT_PUBLIC_API_URL=https://your-instance.example.com \
  -t skillmeat-marketplace:latest \
  -f skillmeat/web/Dockerfile .

For Compose-based deployments, supply the build args in the relevant service block in your compose.override.yml.

Configuration¶

Pointing at a Remote Instance¶

Set NEXT_PUBLIC_API_URL to the base URL of the target SkillMeat API instance. The Next.js API proxy is configured to forward /api/... requests to that origin.

# No trailing slash
NEXT_PUBLIC_API_URL=https://skillmeat.yourorg.example.com

When NEXT_PUBLIC_API_URL is empty the front-end uses relative /api/... URLs (default Next.js proxy mode). This is appropriate when the web container and API container share a reverse proxy or are co-located.

Authentication¶

Auth follows the target instance's configuration:

If the instance uses Clerk: Set NEXT_PUBLIC_AUTH_ENABLED=true and NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY to match the instance's Clerk application.
If the instance uses local (no-auth) mode: Leave NEXT_PUBLIC_AUTH_ENABLED=false. The marketplace and My Installs workspace will be available without requiring a login screen (the system authenticates you as the local admin internally).

Other Environment Variables¶

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: Clerk auth key (if using Clerk)
NEXT_PUBLIC_AUTH_ENABLED: Set to true to enable authentication

Limitations¶

Auth follows the target instance. If the target instance requires Clerk authentication, configure the Clerk keys. If the instance uses local (no-auth) mode, leave auth disabled.
Non-marketplace routes redirect. Any attempt to navigate to a collection-centric URL (e.g. /artifacts, /projects) will be redirected to /marketplace. This redirect happens at the Edge and is not configurable at runtime — the flag is baked into the build.
NEXT_PUBLIC_STANDALONE_MARKETPLACE is build-time only. You cannot toggle standalone mode at runtime without rebuilding the application. Standard (full-featured) builds and standalone builds are separate images.
Collection management is unavailable. Adding artifacts to a personal collection, managing tags, and deploying artifacts all require a locally authenticated collection. These features are not accessible in standalone mode.
Rebuild Lockfile quick action is disabled in v1. Use the CLI instead:
```
skillmeat manifest lock --rebuild
```
This feature will be enabled in a future release.
Artifact version pinning is displayed but not enforced. The install command shows the current version (e.g., @1.2.3), and the CLI will warn about newer versions. However, it will not prevent installation. Use the --upgrade flag to explicitly update to the latest version.
Local (no-auth) mode has no login requirement. When configured with NEXT_PUBLIC_AUTH_ENABLED=false, the marketplace operates in zero-auth mode where all users are authenticated as the local admin internally. This is not a public trust boundary in v1 (enterprise deployments with real authentication boundaries are the recommended model for shared/public access; planned as a future capability).

Troubleshooting¶

"API connection failed" or "Could not reach instance"¶

Verify NEXT_PUBLIC_API_URL is correct and includes the protocol (https://)
Check that the API instance is running and reachable from your network
For local development, ensure the API is running on port 8000 or update the proxy target
Check browser console (F12) for CORS or network errors

If the target API requires authentication, set NEXT_PUBLIC_AUTH_ENABLED=true
Configure the correct Clerk public key if using Clerk authentication
For local-auth instances, no additional config is needed

Make sure you're signed in (check the avatar icon in the top nav)
If not authenticated, My Installs will not be available
Verify the API instance is configured to allow authenticated requests

Install command not copying to clipboard¶

Try copying manually from the code block
Check browser permissions for clipboard access (some browsers require user approval)
Try a different browser if issues persist

Next Steps¶

Getting Started: See Marketplace Consumer Guide for detailed feature walkthroughs
Full Application: To use SkillMeat's collection management, artifact authoring, and deployment features, switch to a standard (non-standalone) build
CLI Reference: Run skillmeat install --help for complete install command options