/publish-to-nextclaw-marketplace

name: publish-to-nextclaw-marketplace
description: Use when the user wants to publish or update a local skill in the NextClaw marketplace, especially when they need clear guidance for version readiness, platform login, username setup, scoped package naming, and post-publish verification.

Publish To NextClaw Marketplace

Overview

Use this skill when the user wants to publish a local skill to the NextClaw marketplace or update an existing listing.

This skill owns the full publishing loop:

• check that the local `nextclaw` version is new enough,
• verify platform identity and username readiness,
• choose the correct package scope,
• run `publish` or `update`,
• then verify the listing and install path.

Do not pretend the account is ready when it is not. If the user is logged in but still has no platform username, stop and ask them to set it first.

Hard Requirement

This workflow requires **NextClaw `v0.17.6` or later**.

Why:

• `v0.17.6+` is the baseline that supports scoped marketplace package names such as `@nextclaw/my-skill` and `@alice/my-skill`.
• It also supports the clearer `--scope` and `--package-name` publish parameters.
• Personal publishing now depends on the platform `username` model added in the same release line.

Always verify first:

nextclaw --version

If the version is lower than `0.17.6`, do not continue with a fallback flow. Tell the user to upgrade NextClaw first.

Marketplace Identity Model

Treat these fields differently:

• `slug`: the local skill directory name and the skill name segment
• `package name`: the canonical marketplace identifier, shaped like `@scope/skill-name`

Publishing scopes:

• official scope: `@nextclaw/<skill-name>`
• personal scope: `@<username>/<skill-name>`

Rules:

• `@nextclaw/*` publishing requires admin permission or `NEXTCLAW_MARKETPLACE_ADMIN_TOKEN`
• personal publishing requires an active platform login
• personal publishing also requires a platform username
• the personal scope must exactly match the current username

Do not blur official and personal publishing together.

Readiness Checklist

Before publishing, check these in order.

1. CLI version

nextclaw --version

Must be `0.17.6` or later.

2. Platform login

For normal user publishing, log in first:

nextclaw login --api-base https://ai-gateway-api.nextclaw.io/v1

For official `@nextclaw/*` publishing, an admin token may also be used through:

NEXTCLAW_MARKETPLACE_ADMIN_TOKEN=...

3. Platform username

If the user wants personal publishing, make sure the platform account already has a username.

Important:

• login alone is not enough
• the username must already exist on the NextClaw platform account
• the canonical web page is `https://platform.nextclaw.io/account`
• the CLI fallback is `nextclaw account set-username <username>`
• if it is missing, direct the user to one of those two concrete paths before publishing

4. Local skill files

The local skill directory should contain at least:

• `SKILL.md`
• `marketplace.json`

The marketplace metadata should be complete and explicit. At minimum, verify:

• `slug`
• `name`
• `summary`
• `summaryI18n.en`
• `summaryI18n.zh`
• `description`
• `descriptionI18n.en`
• `descriptionI18n.zh`
• `author`
• `tags`

Do not publish with half-complete bilingual metadata.

Publish Flow

Use the official marketplace API domain:

https://marketplace-api.nextclaw.io

Do not use a `workers.dev` endpoint as the default public publishing target.

Publish a new personal skill

nextclaw skills publish ./my-skill \
  --meta ./my-skill/marketplace.json \
  --scope alice \
  --api-base https://marketplace-api.nextclaw.io

Equivalent explicit package name form:

nextclaw skills publish ./my-skill \
  --meta ./my-skill/marketplace.json \
  --package-name @alice/my-skill \
  --api-base https://marketplace-api.nextclaw.io

Publish an official NextClaw skill

nextclaw skills publish ./my-skill \
  --meta ./my-skill/marketplace.json \
  --scope nextclaw \
  --api-base https://marketplace-api.nextclaw.io

Only do this when admin permission is actually present.

Update an existing skill

nextclaw skills update ./my-skill \
  --meta ./my-skill/marketplace.json \
  --package-name @alice/my-skill \
  --api-base https://marketplace-api.nextclaw.io

Default decision rule:

• if the marketplace item does not exist yet, use `publish`
• if it already exists, use `update`

Post-Publish Verification

After publishing, verify the remote item directly.

Example:

curl -sS https://marketplace-api.nextclaw.io/api/v1/skills/items/%40alice%2Fmy-skill

Check for:

• HTTP `200`
• correct canonical `packageName`
• expected `slug`
• complete bilingual summary and description
• install kind is marketplace

Then do an install smoke in a temporary directory outside the repo or target workspace:

tmp_dir="$(mktemp -d)"
nextclaw skills install @alice/my-skill --api-base https://marketplace-api.nextclaw.io --workdir "$tmp_dir"
find "$tmp_dir" -maxdepth 3 -type f | sort
rm -rf "$tmp_dir"

The point is to verify real installability without polluting the current repo.

Failure Modes

Version too old

• Symptom: scoped publish flags or username-aware flow are missing
• Action: upgrade to NextClaw `v0.17.6` or later

Not logged in

• Symptom: publish rejects because there is no active platform identity
• Action: run `nextclaw login --api-base https://ai-gateway-api.nextclaw.io/v1`

Username missing

• Symptom: personal publish fails because the platform account has no username
• Action: open `https://platform.nextclaw.io/account` or run `nextclaw account set-username <username>`, then retry

Scope mismatch

• Symptom: publish rejects `@scope/name` because the scope does not match the current username
• Action: publish under `@<your-username>/<skill-name>` instead

Insufficient p