Skip to main content

​
Overview

Install the publisher helper skill or open its listing: This guide covers the end-to-end CLI workflow to authenticate, package, verify, and publish a skill release.

​
How to publish

​
Required Inputs

Collect these values before running commands:
  • BASE_URL (default https://api.skilldock.io)
  • OPENAPI_URL (default https://api.skilldock.io/openapi.json)
  • NAMESPACE (publisher namespace, for example myorg)
  • SLUG (skill id, for example my-skill)
  • VERSION (release version, for example 1.2.3)
  • SKILL_PATH (local folder containing SKILL.md)

​
Auth once, then use a token

Browser auth: 
skilldock auth login
For headless environments: 
skilldock auth login --no-open
Create and save a long-lived token (avoids repeated OAuth): 
skilldock tokens create --save
Check active credential: 
skilldock auth status
Manage tokens: 
skilldock tokens list
skilldock tokens revoke <ID>
Tags:
  • skilldock
  • cli
  • auth
  • oauth
  • publishing
  • releases
  • tokens
  • verification
  • troubleshooting
  • rate-limits
Listing / Home:

​
1) Install CLI via pip

Use Python 3.10+. 
python3 -m pip install --upgrade skilldock
skilldock --version
If multiple Python interpreters exist, use: 
python3 -m pip show skilldock

​
2) Configure API endpoint (if non-default)

skilldock config set --base-url "$BASE_URL" --openapi-url "$OPENAPI_URL"
skilldock config show

​
3) Authenticate with Google OAuth

Run browser login: 
skilldock auth login
Behavior:
  • The CLI creates an auth session.
  • The CLI prints an auth_url and opens the browser (or prints a .../auth/google/start?session_id=... link when --no-open is used).
  • After Google approval, the CLI polls until a token is issued.
  • The CLI stores the token in local SkillDock config.
Validate auth: 
skilldock auth status
skilldock auth inspect
If browser auto-open fails or you are on a headless box: 
skilldock auth login --no-open
# Copy the printed https://api.skilldock.io/auth/google/start?session_id=... URL
# Open it in a browser to approve, then wait for CLI to finish
If you hit HTTP 429 (rate limit is approximately 5 attempts/minute), wait a full minute before retrying.

​
4) Create and manage API tokens

Create a long-lived token and save it as default: 
skilldock tokens create --save
Create a scoped/expiring token: 
skilldock tokens create --scope skills:write --scope skills:read --expires-in-days 90 --save
List tokens: 
skilldock tokens list
Revoke a token (delete token credential): 
skilldock tokens revoke <TOKEN_ID>

​
5) Create a new local skill (manual scaffold)

SkillDock currently packages existing folders. It does not provide a dedicated scaffold command. Create the folder: 
mkdir -p "$SKILL_PATH"
Create the required SKILL.md file at the skill root: 
---
name: my-skill
description: Clear trigger-oriented description of what this skill does and when to use it.
---

# My Skill

## What It Does
- Describe concrete behavior.

## Inputs
- List required inputs.

## Workflow
1. Step one.
2. Step two.
3. Step three.
Optional files:
  • requirements.txt
  • Scripts used by the skill
  • references/ or assets

​
6) Format a good skill

Follow these rules:
  • Keep frontmatter minimal: name and description
  • Use a specific description that includes trigger conditions
  • Keep instructions procedural and command-first
  • Include required inputs and expected outputs
  • Keep runnable commands copy-paste safe
  • Keep the folder clean; avoid virtualenvs, build folders, and git metadata in the published artifact
Packaging constraints enforced by the CLI packager:
  • SKILL.md must exist at skill root
  • Symbolic links are skipped
  • Common junk folders are excluded (.git, .venv, venv, node_modules, dist, build, caches)
  • Zip files larger than 10 MiB emit a warning

​
7) Verify before publish

Run package verification: 
skilldock skill verify "$SKILL_PATH"
Use a dry-run upload to validate the publish payload without a network write: 
skilldock skill upload \
  --namespace "$NAMESPACE" \
  --slug "$SLUG" \
  --version "$VERSION" \
  --path "$SKILL_PATH" \
  --dry-run

​
8) Publish new skill or release version

Create the namespace if needed: 
skilldock namespaces create "$NAMESPACE"
skilldock namespaces list
Publish a release: 
skilldock skill upload \
  --namespace "$NAMESPACE" \
  --slug "$SLUG" \
  --version "$VERSION" \
  --path "$SKILL_PATH" \
  [--homepage-url https://example.com]
Publish a private release: 
skilldock skill upload \
  --namespace "$NAMESPACE" \
  --slug "$SLUG" \
  --version "$VERSION" \
  --path "$SKILL_PATH" \
  --visibility private \
  [--homepage-url https://example.com]
Publish a new version: 
VERSION=1.2.4
skilldock skill upload \
  --namespace "$NAMESPACE" \
  --slug "$SLUG" \
  --version "$VERSION" \
  --path "$SKILL_PATH" \
  [--homepage-url https://example.com]
Homepage URL notes:
  • Optional; sent as a query param
  • Backend precedence: query > multipart > SKILL.md > existing DB
  • Validation: http/https only; length <= 2048
  • Leave blank to keep the existing value unchanged
Dependencies:
  • Declare in SKILL.md frontmatter under dependencies: using semver ranges (for example >=0.1.0 <0.2.0)
  • Or pass repeatable --dependency "namespace/skill@<range>" flags on upload
  • API precedence merges frontmatter + CLI flags; invalid or missing dependency skills fail upload
  • Self-dependency is rejected
Examples: 
# Frontmatter example
dependencies:
  - namespace: core
    skill: base-utils
    version_requirement: ">=1.2.0 <2.0.0"

# CLI flag example
skilldock skill upload \
  --namespace "$NAMESPACE" \
  --slug "$SLUG" \
  --path "$SKILL_PATH" \
  --dependency "core/base-utils@>=1.2.0 <2.0.0" \
  --dependency "tools/lint@~2.0.0"

​
9) Search existing skills

Free-text search: 
skilldock skills search "docker"
Filter by namespace or tag: 
skilldock skills search --namespace "$NAMESPACE" --tag "python"
Machine-readable output: 
skilldock skills search "docker" --json

​
10) Download and install skills locally

Install the latest version: 
skilldock install acme/my-skill
Install an exact version: 
skilldock install acme/my-skill --version 1.2.3
Install to a custom directory (for example Codex home skills): 
skilldock install acme/my-skill --skills-dir "$CODEX_HOME/skills"
Notes:
  • The install command downloads the release archive and resolves dependencies recursively
  • The CLI writes local manifest and lock files (.skilldock.json, .skilldock.lock.json)

​
11) Delete workflows

Use the right delete path for the target object. Delete a local installed skill: 
skilldock uninstall acme/my-skill
Delete an API token: 
skilldock tokens list
skilldock tokens revoke <TOKEN_ID>
Delete a remote release or remote skill: There is no dedicated high-level skilldock skill delete command. Use one of these patterns. Discover the delete operation from OpenAPI and call it by operationId: 
skilldock ops
# Identify the delete operation id for releases/skills, then:
skilldock call <DeleteOperationId> --param namespace="$NAMESPACE" --param slug="$SLUG" --param version="$VERSION"
Use a low-level HTTP request when the API path is known: 
skilldock request DELETE "/v1/skills/$NAMESPACE/$SLUG/releases/$VERSION"
If the API does not support that delete route, expect 404 or 405.

​
12) Quick troubleshooting

  • 401 Unauthorized: Run skilldock auth login or set a valid token
  • 403 Forbidden: Token is valid but missing permission
  • 404 Not Found: Wrong namespace/slug/version, or object is not visible
  • Token expired: Run skilldock auth login again
Check active configuration: 
skilldock config path
skilldock config show

​
Revenue model

For sold skills, SkillDock commission is 50% of the sale price.
  • Provider share: 50%
  • SkillDock commission: 50%
Read the Terms of Service for current legal and commercial terms: For commercial listing details, see Commission model.

​
API

The publish workflow can be automated with the SkillDock API. OpenAPI specification: See the dedicated API guide for examples and integration patterns: API.

​
Verification process

Verification is an automatic background process that runs security and quality checks. These checks may run for:
  • Public skills
  • Private skills
  • Free skills
  • Paid/selling skills
The purpose of verification is to reduce the risk of:
  • Illegal or policy-breaking content/behavior
  • Malicious behavior
  • Vulnerable or unsafe behavior
  • Quality issues that can harm users or integrations
If suspicious or unsafe behavior is detected, a skill may be:
  • Frozen and made unavailable for installation
  • Removed from listings
  • Permanently deleted
These actions may be applied without notification. If you believe an action was triggered by an error, contact support: