@skillsmith/cli

@skillsmith/cli

Important: The bare skillsmith package on npm is not this project. Install @skillsmith/cli for the CLI or configure @skillsmith/mcp-server for MCP integration.

Command-line interface for Skillsmith — publish, manage, and author agent skills.

Part of Skillsmith: a lifecycle layer for agent skills across teams.

Contents

• What's New
• Installation
• Commands
  • inventory
• Configuration
• Examples
• Privacy & Data Handling

What's New in v0.8.5

• Multi-client targeting fixed across the board: install, list, remove, update, sync, and search -i's install action now all honor SKILLSMITH_CLIENT/--client consistently — previously several of these silently acted on the Claude Code directory regardless of the flag or env var.
• update no longer fails after a fresh install: now resolves the installed skill's registry source from the manifest install already writes, instead of a dead-code path that could never find it.
• New skillsmith registry install <skillId>: pulls a skill previously published to your team's Enterprise private registry and installs it locally.
• New security-acceptance workflow: sklx audit security --accept/--revoke/--candidates/--list-accepted lets you mark a reviewed false-positive as accepted so it stops re-surfacing, without affecting rug-pull/hostile-update detection.
• recommend --installed actually used now: an explicit --installed list is fed into the recommendation query instead of being silently ignored on an empty-derived-stack workspace.
• Security-status coloring corrected: a borderline-safe scan result no longer renders identically bright-green to a comfortably-safe one.

See CHANGELOG.md for previous releases.

Local-first by design. Skillsmith caches the registry in a local SQLite database at ~/.skillsmith/skills.db, shared across the MCP server, the CLI, and the VS Code extension. Search is FTS5 (SQLite's built-in keyword search) by default; semantic search is opt-in (SKILLSMITH_USE_HNSW=true) and runs over local ONNX embeddings (an open ML model format that runs on CPU — no API call). Inside the Local Skill Database walks through the schema, the FTS5 / HNSW search paths, and how sync keeps the cache fresh.

Installation

npm install -g @skillsmith/cli

Or use directly with npx:

npx @skillsmith/cli search "testing"

Updating the CLI

Check your current version:

skillsmith --version

Update to the latest version:

# If installed globally
npm update -g @skillsmith/cli

# Or reinstall to specific version
npm install -g @skillsmith/cli@latest

# Using npx always gets the latest
npx @skillsmith/cli@latest sync

Command Alias

The CLI provides two command names:

• skillsmith - Full command name
• sklx - Short alias for faster typing

Both commands are identical:

# These are equivalent
skillsmith search "testing"
sklx search "testing"

Commands

search

Search for skills with optional interactive mode.

# Basic search
skillsmith search "git commit"

# With filters
skillsmith search "testing" --category testing --trust verified

# Interactive mode
skillsmith search --interactive

Options:

• -c, --category <category> - Filter by category
• -t, --trust <tier> - Filter by trust tier (verified, community, experimental)
• -l, --limit <n> - Maximum results (default: 10)
• -i, --interactive - Interactive selection mode

list

List installed skills.

skillsmith list

# With details
skillsmith list --verbose

Options:

• -v, --verbose - Show detailed information

install

Install a skill (alias for MCP server's install_skill).

skillsmith install author/skill-name

remove

Remove an installed skill.

skillsmith remove author/skill-name

# Skip confirmation
skillsmith remove author/skill-name --force

Options:

• -f, --force - Skip confirmation prompt

update

Update installed skills. Requires an explicit selector — a skill name, several names, or --all — bare skillsmith update with none of those prints usage guidance instead of updating anything.

# Update all skills
skillsmith update --all

# Update one skill
skillsmith update skill-name

# Update a specific set of skills
skillsmith update skill-name another-skill

# Preview changes without applying them
skillsmith update skill-name --dry-run

Options:

• -a, --all - Update all installed skills
• -n, --dry-run - Show what would update without installing
• -d, --db <path> - Database file path

inventory

Cross-machine skill inventory for viewing which agent skills are installed across your machines and harnesses. Requires skillsmith login and opt-in via the Cross-machine skill inventory toggle at skillsmith.app/account/telemetry (off by default). Once enabled, view your inventory at skillsmith.app/account/skills.

Privacy: Only skill IDs, versions, content hashes, declared SKILL.md front-matter fields (author, license, repository), and device platform metadata are uploaded. File contents, paths, and your raw hostname are never transmitted. Set SKILLSMITH_INVENTORY_DISABLE=1 to hard-disable, or run skillsmith inventory purge to delete everything already stored.

inventory push

Push this device's installed-skill snapshot to your Skillsmith account.

skillsmith inventory push

Requires:

• Active authentication via skillsmith login
• "Cross-machine skill inventory" toggle enabled at skillsmith.app/account/telemetry

inventory status

Show local device inventory status (read-only, no network call).

skillsmith inventory status

# Verbose output
skillsmith inventory status --verbose

Options:

• --verbose - List the individual skill IDs found under each harness

inventory forget-device

Clear the local device registration; the next push creates a fresh device ID and registers as a new machine.

skillsmith inventory forget-device

inventory purge

Permanently delete this account's entire stored cross-machine inventory from Skillsmith's servers (all devices and their skill rows). Irreversible. Prompts for confirmation unless --yes is passed.

skillsmith inventory purge
skillsmith inventory purge --yes

Options:

• -y, --yes - Skip the confirmation prompt (for scripts)

See Cross-machine skill inventory for details.

init

Initialize a new skill project.

# Interactive mode
skillsmith init

# With name
skillsmith init my-skill

# In specific directory
skillsmith init my-skill --path ./skills/my-skill

Options:

• -p, --path <path> - Directory to create skill in
• --template <template> - Skill template (basic, advanced)

create

Scaffold a new agent skill at ~/.claude/skills/<name>/.

# Interactive mode
skillsmith create

# With name
skillsmith create my-skill

# Non-interactive
skillsmith create my-skill --description "Git workflow helper" --author myuser --type basic

# Preview without writing
skillsmith create my-skill --dry-run

Options:

• -o, --output <dir> - Output directory (default: ~/.claude/skills)
• --type <type> - Skill type: basic, intermediate, advanced
• --behavior <behavior> - Behavioral classification: autonomous, guided, interactive, configurable
• -d, --description <description> - Skill description (skips prompt)
• -a, --author <author> - Author GitHub username (skips prompt)
• -c, --category <category> - Category: development, productivity, communication, data, security, other
• --scripts - Include a scripts/ directory
• -y, --yes - Auto-confirm overwrite if skill directory exists
• --dry-run - Preview scaffold output without writing files

Generated Structure:

~/.claude/skills/my-skill/
├── SKILL.md           # Skill definition
├── README.md          # Documentation
├── CHANGELOG.md       # Version history
├── .gitignore
└── resources/         # Supporting files

validate

Validate a skill's SKILL.md file.

# Validate current directory
skillsmith validate

# Validate specific path
skillsmith validate ./path/to/skill

# Strict mode (warnings as errors)
skillsmith validate --strict

Options:

• -s, --strict - Treat warnings as errors

publish

Prepare a skill for publishing/sharing.

skillsmith publish

# Dry run (no changes)
skillsmith publish --dry-run

Options:

• -d, --dry-run - Preview without making changes

author subagent

Generate a companion specialist agent for parallel skill execution.

# Generate subagent for current directory
skillsmith author subagent

# Generate for specific skill
skillsmith author subagent ./my-skill

# Override detected tools
skillsmith author subagent --tools "Read,Write,Bash"

# Use different model
skillsmith author subagent --model haiku

Options:

• -o, --output <path> - Output directory (default: ~/.claude/agents)
• --tools <tools> - Override detected tools (comma-separated)
• --model <model> - Model: sonnet, opus, haiku (default: sonnet)
• --skip-claude-md - Skip CLAUDE.md snippet generation
• --force - Overwrite existing subagent

Output:

• Creates ~/.claude/agents/[skill-name]-specialist.md
• Displays CLAUDE.md integration snippet

author transform

Upgrade existing skills with subagent configuration (non-destructive).

# Preview what would be generated
skillsmith author transform ./my-skill --dry-run

# Generate subagent for existing skill
skillsmith author transform ./my-skill

# Process multiple skills at once
skillsmith author transform ~/.claude/skills --batch

Options:

• --dry-run - Preview without creating files
• --force - Overwrite existing subagent
• --batch - Process directory of skills
• --tools <tools> - Override detected tools
• --model <model> - Model: sonnet, opus, haiku (default: sonnet)

author mcp-init

Scaffold a new MCP server project with TypeScript and stdio transport.

# Interactive mode
skillsmith author mcp-init

# With name
skillsmith author mcp-init my-mcp-server

# With pre-defined tools
skillsmith author mcp-init my-server --tools "greet,search,process"

# Custom output directory
skillsmith author mcp-init my-server --output ./servers

Options:

• -o, --output <path> - Output directory (default: current directory)
• --tools <tools> - Initial tool names (comma-separated)
• --force - Overwrite existing directory

Generated Structure:

my-mcp-server/
├── package.json         # npm package with MCP SDK
├── tsconfig.json        # TypeScript configuration
├── src/
│   ├── index.ts         # Entry point (npx-ready)
│   ├── server.ts        # MCP server setup
│   └── tools/
│       ├── index.ts     # Tool definitions
│       └── example.ts   # Example tool implementation
├── README.md            # Usage documentation
└── .gitignore

After Generation:

cd my-mcp-server
npm install
npm run dev  # Start in development mode

Configure in your MCP client settings (~/.claude/settings.json):

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/my-mcp-server/src/index.ts"]
    }
  }
}

import

Import skills from GitHub (for populating local database).

# Import from default topic
skillsmith import

# Custom topic and limits
skillsmith import --topic claude-skill --max 500

Options:

• -t, --topic <topic> - GitHub topic to search (default: claude-skill)
• -m, --max <n> - Maximum skills to import
• -d, --db <path> - Database path
• -v, --verbose - Verbose output

sync

Synchronize your local skill database with the live Skillsmith registry.

# Sync skills from registry (differential - only changes)
skillsmith sync

# Force full sync (ignore last sync time)
skillsmith sync --force

# Preview what would be synced
skillsmith sync --dry-run

Options:

• -f, --force - Force full sync, ignore last sync timestamp
• --dry-run - Preview changes without writing to database
• -d, --db <path> - Database path
• --json - Output results as JSON

sync status

Show sync status and statistics.

skillsmith sync status

Output includes:

• Auto-sync enabled/disabled
• Sync frequency (daily/weekly)
• Last sync time
• Next scheduled sync
• Last run statistics

sync history

View sync operation history.

# Show recent sync history
skillsmith sync history

# Show more entries
skillsmith sync history --limit 20

Options:

• -l, --limit <n> - Number of history entries (default: 10)

sync config

Configure automatic sync settings.

# Show current configuration
skillsmith sync config --show

# Enable automatic background sync
skillsmith sync config --enable

# Disable automatic sync
skillsmith sync config --disable

# Set sync frequency
skillsmith sync config --frequency daily
skillsmith sync config --frequency weekly

# Combine options
skillsmith sync config --enable --frequency weekly

Options:

• --show - Display current configuration
• --enable - Enable automatic background sync
• --disable - Disable automatic sync
• --frequency <freq> - Set frequency: daily or weekly

audit

audit advisories

Check installed skills against known security advisories (Team+ tier). Use --fix to attempt updating skills with available patches.

# Check all installed skills
skillsmith audit advisories

# Output as JSON
skillsmith audit advisories --json

# Auto-update skills with patches
skillsmith audit advisories --fix

Options:

• --json - Emit results as JSON
• --fix - Attempt skillsmith update for each advisory with a patch available

audit collisions

Audit installed skills for namespace collisions — duplicate tool names across multiple skills that could cause invocation conflicts (Community+).

# Interactive audit (prompts for each collision)
skillsmith audit collisions

# Include semantic-overlap detector pass
skillsmith audit collisions --deep

# Output raw JSON (no prompts, no file writes)
skillsmith audit collisions --json

# Accept every suggestion automatically (requires typing APPLY ALL)
skillsmith audit collisions --apply-all

# Write report only, no interactive prompts
skillsmith audit collisions --report-only

# Clear the namespace-override ledger (requires typing RESET LEDGER)
skillsmith audit collisions --reset-ledger

Options:

• --deep - Enable semantic-overlap detector pass
• --json - Emit RunInventoryAuditResult as JSON; bypasses prompts and file mutation
• --apply-all - Accept every rename suggestion; requires typing APPLY ALL to confirm
• --report-only - Write audit report without prompts or apply
• --reset-ledger - Clear ~/.skillsmith/namespace-overrides.json (backs up first); requires typing RESET LEDGER

config

Get or set Skillsmith configuration values in ~/.skillsmith/config.json.

config get

Print the resolved value of a configuration key.

skillsmith config get audit_mode

Supported keys: audit_mode

The resolved value reflects the config-file entry when set, else the tier default:

• community / individual → preventative
• team → power_user
• enterprise → governance

config set

Write a configuration value. Tier-revalidated on write — community and individual users cannot select power_user or governance.

skillsmith config set audit_mode preventative
skillsmith config set audit_mode power_user    # team/enterprise only
skillsmith config set audit_mode governance    # enterprise only
skillsmith config set audit_mode off

Valid values for audit_mode: preventative, power_user, governance, off

Error codes (stderr, exit 1):

• audit.mode.invalid_value — value not in the supported set
• audit.mode.tier_ineligible — your tier cannot select the requested mode

login

Authenticate the Skillsmith CLI with your API key. Opens your browser to skillsmith.app/account/cli-token, where you generate and copy a key, then paste it into the terminal prompt.

skillsmith login

Opening https://skillsmith.app/account/cli-token in your browser...

After authenticating, copy the API key shown and paste it below.
? Paste your API key: [input is masked]

✓ Logged in successfully.
  Note: your API key may still be in your clipboard. Clear it when done.

Options:

• --no-browser — Print the URL instead of opening a browser (for headless/CI/SSH environments)

Headless/CI environments: Use SKILLSMITH_API_KEY as an environment variable — no browser needed.

Key storage: Keys are stored in your OS keyring (macOS Keychain, GNOME Keyring, Windows Credential Store) when available, with ~/.skillsmith/config.json as fallback.

logout

Remove the stored API key.

skillsmith logout

? Log out and remove stored API key? (y/N) y
✓ Logged out. Key removed from OS keyring.

whoami

Show current authentication status.

skillsmith whoami

Skillsmith CLI
  Key:    sk_live_xxxx...
  Source: OS keyring
  Format: valid

Source indicates where the active key was read from:

• OS keyring — stored by skillsmith login (most secure)
• config file (~/.skillsmith/config.json) — file-based fallback
• environment variable (SKILLSMITH_API_KEY) — injected at runtime

Configuration

Environment Variables

Variable	Description	Default
SKILLSMITH_API_KEY	API key for authenticated requests (alternative to skillsmith login)	-
SKILLSMITH_DB_PATH	Database file location	~/.skillsmith/skills.db
SKILLSMITH_IMPORT_DELAY_MS	Delay between GitHub API calls during import	150
GITHUB_TOKEN	GitHub token for imports	-

Database Location

By default, the CLI uses ~/.skillsmith/skills.db. Override with:

SKILLSMITH_DB_PATH=/custom/path/skills.db skillsmith search "testing"

Error Logging

Structured error logs are automatically persisted to disk for debugging and diagnostics.

Log Location: ~/.skillsmith/logs/skillsmith-cli-<YYYY-MM-DD>.jsonl

Log Format: One JSON-line record per error, with fields:

• ts — ISO 8601 timestamp
• level — log level (debug, info, warn, error)
• surface — invocation surface (cli, mcp, or vscode)
• event — short machine-readable category tag
• msg — human-readable message (redacted)
• err — normalized error object with name, message, and first 20 stack frames (all redacted)
• correlationId — trace ID linking related log entries and telemetry events
• toolOrCommand — CLI command name or MCP tool name
• skillId — skill ID when applicable
• version — package version
• pid — process ID
• details — additional structured context beyond the fields above, when provided (redacted)

Redaction: Secrets, tokens, API keys, passwords, connection strings, and PEM keys are automatically redacted before any record is written to disk — this applies to the message, error stack, and any structured context. Redaction happens synchronously at the call site, so disk logs are already safe to inspect or share.

Rotation & Retention: Log files rotate daily (new file per UTC calendar date) and are capped at ~10MB with .1, .2 continuation files. Files older than 14 days are automatically deleted on startup (CLI or MCP server, whichever runs first).

Control Logging:

Variable	Default	Description
SKILLSMITH_ERROR_LOG_DISABLE	unset (logging ON)	Set to '1' or 'true' to disable error logging entirely
SKILLSMITH_LOG_LEVEL	warn	Filter log verbosity: debug, info, warn, or error

Examples:

# Turn off error logging
SKILLSMITH_ERROR_LOG_DISABLE=1 skillsmith search "testing"

# Enable debug-level verbosity (noisier, more detailed logs)
SKILLSMITH_LOG_LEVEL=debug skillsmith search "testing"

Inspect Logs: Run skillsmith diagnose to view a redacted summary of recent error records, or skillsmith logs --tail to follow logs in real-time. Both commands redact secrets inline, so output is always safe to paste in chat or share.

Privacy & Data Handling

Skillsmith is designed with privacy as a core principle.

What Stays on Your Computer (Never Transmitted)

Data	Location	Purpose
Skill usage history	~/.skillsmith/analytics.db	Personal ROI tracking
Time saved metrics	~/.skillsmith/analytics.db	Your productivity insights
Value calculations	Computed locally	ROI dashboard
Project context	Hashed locally	Anonymous grouping

The ROI Dashboard feature is 100% local. Your usage patterns, time saved, and value metrics never leave your computer. This data exists solely for your benefit.

What Is Transmitted (Required for Functionality)

Data	When	Why
Search queries	When you search	To return matching skills
Skill IDs	When viewing/installing	To fetch skill details

Optional Telemetry (Opt-In)

Anonymous product analytics (search counts, feature usage) are opt-in only. Telemetry is disabled by default and requires explicit configuration (SKILLSMITH_TELEMETRY_ENABLED=true).

To run fully offline: Set SKILLSMITH_OFFLINE_MODE=true to disable all network calls.

Examples

Discover and Install Skills

# Search for testing-related skills
skillsmith search "jest testing" --category testing

# Get more details on a skill
skillsmith search "jest-helper" --verbose

# Install a skill
skillsmith install community/jest-helper

# List installed skills
skillsmith list

Create a New Skill

# Scaffold with interactive prompts
skillsmith create my-awesome-skill

# Or fully non-interactive
skillsmith create my-awesome-skill \
  --description "Automates deployment checks" \
  --author myuser \
  --type intermediate \
  --behavior guided \
  --yes

Author a New Skill

# Initialize new skill
skillsmith init my-awesome-skill

# Edit the generated SKILL.md...

# Validate your skill
skillsmith validate ./my-awesome-skill

# Generate companion subagent for parallel execution
skillsmith author subagent ./my-awesome-skill

# Prepare for publishing
skillsmith publish ./my-awesome-skill

Upgrade Existing Skills with Subagents

# Preview subagent generation (dry run)
skillsmith author transform ~/.claude/skills/docker --dry-run

# Generate subagent for a skill
skillsmith author transform ~/.claude/skills/docker

# Batch upgrade all skills
skillsmith author transform ~/.claude/skills --batch --force

Create an MCP Server

# Scaffold a new MCP server
skillsmith author mcp-init my-slack-integration --tools "send_message,list_channels"

# Navigate and install dependencies
cd my-slack-integration
npm install

# Start development server
npm run dev

# Add to MCP client settings
# Edit ~/.claude/settings.json to include the server

Manage Skills

# Update all installed skills
skillsmith update --all

# Remove a skill
skillsmith remove community/old-skill

# Interactive search and install
skillsmith search --interactive

Keep Skills Up-to-Date

# Sync with the live registry
skillsmith sync

# Check sync status
skillsmith sync status

# Enable daily auto-sync
skillsmith sync config --enable --frequency daily

# View sync history
skillsmith sync history

License

Elastic License 2.0

Links

• GitHub
• Issues