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

Contents

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

What's New in v0.5.0

• skillsmith create command: Scaffold a new Claude Code skill directly into ~/.claude/skills/<name>/ — interactive prompts or non-interactive flags (--description, --author, --type, --dry-run, --yes)
• Stricter name validation: author init and create share registry-safe validation (lowercase + hyphens only)

v0.5.1 is a version-bump-only release fixing an npm registry regression. No source changes.

See CHANGELOG.md for previous releases.

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.

# Update all skills
skillsmith update

# Update specific skill
skillsmith update author/skill-name

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 Claude Code 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

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"

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

# 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