$ skill-engine
home / cli
Reference · skill v0.4.0

The skill CLI

Four commands cover the whole skill lifecycle: scaffold it, lint it, run it, ship it. The CLI embeds the same validation engine as the in-browser validator, so a green check here means a green check there.

#Install

One static binary, no runtime dependencies. macOS (arm64/x86_64), Linux (x86_64/arm64), and Windows via WSL.

install.sh — recommended
curl -fsSL https://anthropicskillengine.com/install.sh | sh

# the installer verifies a checksum, drops the binary in ~/.skill/bin,
# and appends it to your PATH. then:
skill --version
# skill 0.4.0

##Package managers

alternative installs
# Homebrew (macOS / Linux)
brew install anthropicskillengine/tap/skill

# npm (shim that fetches the platform binary on first run)
npm install -g @anthropicskillengine/cli

# verify any install the same way
skill --version
Updating. skill upgrade (alias: skill update) pulls the latest stable and re-verifies the checksum. Pin a version in CI with SKILL_VERSION=0.4.0 before running the install script.

#skill init — scaffold a skill

skill init [name] [flags]

Creates a project directory with a valid skill.json, a README stub, and an examples/ folder. The generated manifest passes validation out of the box — run skill validate right after to see a clean bill.

  • --template <t>Starter template: minimal (default), http (net.http + example), tool (exec scaffold).
  • --dir <path>Target directory. Defaults to ./<name>.
  • --license <spdx>License id baked into the manifest. Default: MIT.
  • --author <name>Author string. Defaults to your git config user.
  • --no-gitSkip git init in the new directory.
  • -y, --yesAccept all defaults non-interactively (for scripts).
example
$ skill init web-search --template http --license MIT
✓ created web-search/skill.json
✓ created web-search/README.md, web-search/examples/
$ cd web-search && skill validate
VALID — 0 errors, 0 warnings

#skill validate — lint a definition

skill validate [file] [flags]

Runs the full SDF rule set against a manifest: JSON syntax, required fields, semver, slug format, schema sanity, permissions, runtime, examples. Defaults to ./skill.json when no file is given.

  • --strictTreat warnings as errors. Exit non-zero if any warning fires. Use in CI.
  • --jsonMachine-readable output: { "valid": bool, "errors": […], "warnings": […] } on stdout.
  • --quietPrint only the verdict line. Combines with --json.
  • --sdf-version <v>Validate against a specific spec version (e.g. 1). Default: latest supported.
example — CI usage
# in CI: fail the build on warnings too
skill validate --strict --json > report.json

# pretty-print locally
$ skill validate
✗ INVALID — 2 errors must be fixed before publish
ERROR version — must be valid semver 2.0.0, got "v1.2"
ERROR inputs.required[1] — references "missing_field" not in properties

#skill test — run examples locally

skill test [file] [flags]

Executes the skill against every entry in examples[] inside a local sandbox honoring permissions and runtime, then diffs actual vs. expected output. This is the same harness marketplaces run at publish time — green here means green there.

  • --example <name>Run only the example with this name. Repeatable.
  • --updateRewrite expected outputs with actual results (use deliberately — it blesses behavior).
  • --timeout <ms>Override runtime.timeout_ms for this run.
  • --allow <perm>Grant an extra permission for this run only (repeatable). Never persisted to the manifest.
  • --jsonMachine-readable per-example results on stdout.
example
$ skill test
running 3 examples in sandbox (permissions: net.http) …
✓ basic query (812ms)
✓ empty query returns no results (640ms)
✗ limit respected — expected 3 results, got 5
2 passed, 1 failed

#skill publish — ship it

skill publish [file] [flags]

Validates, runs the test harness, packs the skill, and uploads it to the configured registry (default: the AgentSkills marketplace). Privileged permissions (exec, fs.write, env.write) route the submission to manual review automatically.

  • --dry-runValidate + test + pack without uploading. Always run this first.
  • --registry <url>Publish to a custom registry instead of the default marketplace.
  • --tag <t>Attach a release tag, e.g. stable, beta.
  • --preAllow publishing a pre-release version (required for x.y.z-*).
  • --changelog <file>Markdown changelog included in the release notes.
  • -y, --yesSkip the confirmation prompt (for CI).
example
$ skill publish --dry-run
✓ validate: 0 errors, 1 warning
✓ test: 3/3 examples passed
✓ pack: web-search-1.2.0.skill (18 KB)
dry run — nothing uploaded. re-run without --dry-run to ship.

$ skill publish --changelog CHANGELOG.md
✓ published acme/web-search@1.2.0 → https://marketplace/…/web-search
First publish? You'll be prompted to authenticate once via device flow (skill login); the token is stored in your OS keychain, never in the project directory. See the publishing checklist before you ship.

#Exit codes

CodeMeaningCommands
0Success (warnings allowed unless --strict)all
1Validation errors, test failures, or publish rejectionvalidate, test, publish
2Usage error: bad flags, missing file, unreadable JSONall
3Network/registry failure (retryable)publish

Global flags work on every command: --help, --version, --verbose, --no-color.