@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 - discover, manage, and author agent skills.

Contents

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

What's New in v0.8.0

• sklx agent install / uninstall: New command group installs a portable agent pack (SKILL.md + shims + hooks) to detected harnesses with per-harness MCP registration.
• Per-user inventory purge: New hard-delete path for clearing a user's full skill inventory.
• sklx audit collisions / audit advisories: Namespace-collision and legacy security-advisory audit subcommands, plus sklx config set audit_mode <preventative|power_user|governance|off>.
• Remote-default search + provenance: search now defaults to the remote registry with safety filters, and install provenance is reported as Local / source-identified / Pending.

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