Skip to content

Advanced CLI Workflows Guide

Build on your SkillMeat fundamentals with powerful workflows for searching, multi-project management, deployment profiles, versioning, and team collaboration.

Searching and Discovery

Basic Search Operations

Find artifacts quickly using flexible search modes:

# Search metadata (names, descriptions, tags)
skillmeat search "authentication"

# Search file contents using ripgrep
skillmeat search "def authenticate" --search-type content

# Search both metadata and content combined
skillmeat search "api" --search-type both

Filtering Search Results

Narrow results to specific artifact types or tags:

# Find only skills
skillmeat search "handler" --type skill

# Find only commands with specific tags
skillmeat search "review" --type command --tags code-quality

# Find within a specific collection
skillmeat search "parser" --collection work

Semantic Matching with Confidence Scoring

Use semantic matching to find artifacts even with different names:

# Rank results by semantic similarity
skillmeat match "authentication system"

# View confidence scores for each match
skillmeat match "api client" --verbose

# Require high confidence matches only
skillmeat match "database handler" --min-confidence 75

Cross-Project Discovery

Search across multiple projects simultaneously to find where artifacts are deployed:

# Search two specific projects
skillmeat search "canvas" \
  --projects ~/projects/app1 ~/projects/app2

# Auto-discover and search all Claude projects
skillmeat search "authentication" --discover

# Configure search roots for discovery
skillmeat config set search-roots /home/user/projects /home/user/work

# Search with fresh results (bypass cache)
skillmeat search "handler" --discover --no-cache

Cross-Project Tip

Use --discover to find all projects containing an artifact without manually listing them. Perfect for auditing deployments or identifying code reuse across teams.

Managing Multiple Collections

Creating and Switching Collections

Organize artifacts by context (work, personal, experimental):

# Create a new named collection
skillmeat init --name work
skillmeat init --name personal

# List all collections
skillmeat collection list

# Switch to a different collection
skillmeat collection use work

# See your current active collection
skillmeat active-collection

Working with Collections

Add and manage artifacts in specific collections:

# Add to current collection
skillmeat add skill anthropics/skills/canvas

# Add to specific collection
skillmeat add skill ./my-skill --collection personal

# List artifacts in specific collection
skillmeat list --collection work

# Set default collection
skillmeat config set default-collection work

Collection Organization

Use separate collections for: - Work: Production and team-shared artifacts - Personal: Experimental and one-off utilities - External: Third-party or marketplace artifacts - Templates: Reusable project templates

Collection Operations

Manage collection-level operations:

# Refresh artifact metadata from GitHub
skillmeat collection refresh --dry-run
skillmeat collection refresh

# Export collection for backup
skillmeat export --collection work

# Check collection health
skillmeat collection status

Project Registration and Deployment Profiles

Registering Projects

Register a project to enable artifact deployment:

# Register current directory as a project
cd /path/to/your/project
skillmeat init

# Register a specific project directory
skillmeat init --path ~/my-project

Deployment Profiles

Deploy artifacts to different platforms with profile-specific configurations:

# Scaffold project for Claude Code (default)
skillmeat init --profile claude_code

# Scaffold for other platforms
skillmeat init --profile codex
skillmeat init --profile gemini
skillmeat init --profile cursor

# Scaffold for all platforms at once
skillmeat init --all-profiles

Deploying to Multiple Profiles

Deploy the same artifact across different platforms:

# Deploy to active profile
skillmeat deploy my-skill

# Deploy to specific profile
skillmeat deploy my-skill --profile codex

# Deploy to all profiles
skillmeat deploy my-skill --all-profiles

Managing Composite Deployments

Deploy skills with their member artifacts:

# Deploy skill with embedded members
skillmeat deploy my-composite-skill --members

# Deploy only the primary skill (skip members)
skillmeat deploy my-skill --no-members

# Deploy all profiles with member management
skillmeat deploy my-skill --all-profiles --members

Composite Artifacts

When deploying composites with --members, ensure all member artifacts are also in your collection. Use --dry-run to preview what will be deployed.

Context Entity Management

Context entities (CLAUDE.md, specs, rules, context docs) guide AI agents in your projects.

Adding Context Entities

# Add project configuration
skillmeat context add ./CLAUDE.md --type project_config

# Add specification file
skillmeat context add .claude/specs/api-patterns.md --type spec_file

# Add rule file
skillmeat context add .claude/rules/api/routers.md --type rule_file

# Add context file
skillmeat context add .claude/context/architecture.md --type context_file

Browsing Context Entities

# List all context entities
skillmeat context list

# Filter by type
skillmeat context list --type spec_file

# View entity details
skillmeat context show api-patterns

# Search entities
skillmeat context search "API"

Deploying Context Entities

# Deploy entity to another project
skillmeat context deploy api-patterns --to-project ~/other-project

# Deploy multiple entities
skillmeat context deploy api-patterns debugging-rule --to-project ~/other-project

# Deploy all specs to project
skillmeat context deploy --type spec_file --to-project ~/other-project

Syncing Context Between Projects

Keep context in sync as you make changes:

# Check sync status
skillmeat project sync-context ~/my-project --status

# Pull changes from project back to collection
skillmeat project sync-context ~/my-project --pull

# Push collection updates to project
skillmeat project sync-context ~/my-project --push

# Resolve sync conflicts
skillmeat project sync-context ~/my-project --resolve \
  --entity spec_file:api-patterns \
  --strategy keep_local

Context Management

Use context entities to centralize project knowledge. Deploy them to multiple projects to ensure consistent patterns across your team.

Artifact Versioning and Sync

Version Pinning

Control which versions of artifacts get installed:

# Add latest version (default)
skillmeat add skill anthropics/skills/canvas

# Pin to specific version tag
skillmeat add skill anthropics/skills/canvas@v1.0.0

# Pin to specific commit SHA
skillmeat add skill anthropics/skills/canvas@abc1234567

# Show current version
skillmeat show canvas

Checking for Updates

# Check what artifacts have updates available
skillmeat status

# Check for version updates only (fast)
skillmeat collection refresh --check-only

# Get exit code for automation
# 0 = no updates, 2 = updates available, 1 = error
skillmeat collection refresh --check-only --quiet

Syncing and Refreshing

# Sync all artifacts with upstream sources
skillmeat sync

# Refresh metadata without updating versions
skillmeat collection refresh --dry-run
skillmeat collection refresh

# Refresh specific artifact types
skillmeat collection refresh --type skill
skillmeat collection refresh --type command

# Create safety snapshot before bulk operations
skillmeat snapshot "Before bulk updates"
skillmeat collection refresh

Safe Rollback

# View snapshot history
skillmeat history

# Rollback to previous snapshot
skillmeat rollback snapshot-id

# Confirm rollback when prompted

Bundles and Composites

Bundle Operations

Bundles are curated packages of multiple artifacts:

# List available bundles
skillmeat bundle list

# Search for bundles
skillmeat bundle search "full-stack"

# Show bundle details
skillmeat bundle show my-bundle

# Add entire bundle to collection
skillmeat bundle add anthropics/bundles/python-dev

Creating Composites

Composites are multi-artifact packages you manage together:

# Create a new composite
skillmeat composite create my-tools

# Add artifacts to composite
skillmeat composite add my-tools skill auth-handler
skillmeat composite add my-tools command code-reviewer

# List composite members
skillmeat composite list-members my-tools

# Deploy entire composite
skillmeat deploy my-tools

Scaffolding Projects from Bundles

Generate a new project from a bundle template:

# List available bundle templates
skillmeat scaffold list-bundles

# Scaffold new project from template
skillmeat scaffold my-new-project --bundle full-stack

# Show what bundle will scaffold
skillmeat scaffold --preview --bundle full-stack

MCP Server Management

Manage Claude MCP (Model Context Protocol) servers for enhanced capabilities:

# List MCP servers in collection
skillmeat mcp list

# Add MCP server from GitHub
skillmeat mcp add anthropics/mcp/sqlite

# Deploy MCP server to project
skillmeat mcp deploy sqlite-server --to ~/my-project

# Show MCP server configuration
skillmeat mcp show sqlite-server

# Check MCP server health
skillmeat mcp status

For detailed MCP configuration and integration, see MCP Servers Guide.

Analytics and Insights

Viewing Usage Analytics

# Show overall collection statistics
skillmeat analytics

# View most-used artifacts
skillmeat analytics top --limit 10

# Find unused artifacts
skillmeat analytics unused

# Show deployment history
skillmeat analytics deployments

Activity History

# View artifact activity history
skillmeat history

# Show history for specific artifact
skillmeat history canvas

# Filter by date range
skillmeat history --since "2026-01-01" --until "2026-02-01"

Rating Artifacts

Share feedback on artifacts:

# Rate an artifact (1-5 stars)
skillmeat rate canvas 5

# View ratings
skillmeat ratings canvas

# Find top-rated artifacts
skillmeat analytics top --sort rating

Configuration Reference

GitHub Authentication

# Set GitHub token for increased rate limits
skillmeat config set github-token ghp_xxxxxxxxxxxx

# Check current rate limit
skillmeat config get github-rate-limit

# Clear token
skillmeat config unset github-token

Collection and Search Settings

# Set default collection
skillmeat config set default-collection work

# Configure search roots for auto-discovery
skillmeat config set search-roots /home/user/projects /home/user/work

# Set search type preference
skillmeat config set default-search-type both

Viewing Configuration

# List all configuration
skillmeat config list

# Get specific setting
skillmeat config get default-collection

# View config file location
skillmeat config --show-file

Cache Management

# Check cache status
skillmeat cache status

# Force refresh cache
skillmeat cache refresh

# Clear entire cache
skillmeat cache clear

# Clear specific artifact cache
skillmeat cache clear canvas

Environment Diagnostics

# Diagnose web environment setup
skillmeat web doctor

# Check overall system health
skillmeat health

# View detailed environment info
skillmeat debug info

Web Interface Integration

Launching the Web UI

# Start development servers (API + frontend)
skillmeat web dev

# Start only the API server
skillmeat web dev --api-only

# Start only the Next.js frontend
skillmeat web dev --web-only

# Custom ports
skillmeat web dev --api-port 9000 --web-port 4000

Production Deployment

# Build for production
skillmeat web build

# Start production servers
skillmeat web start

# Build and start in one command
skillmeat web build && skillmeat web start

What You Can Do in the Web UI

  • Browse and search artifacts visually
  • View detailed artifact metadata and content
  • Manage collections and deployments
  • View analytics and usage statistics
  • Deploy artifacts to projects
  • Manage context entities with visual editor
  • Track deployment history

See Web Interface Guide for visual browsing and management features.

Advanced Workflow Patterns

Automated Cross-Project Deployment

Deploy to multiple projects in sequence:

#!/bin/bash
# Deploy skill to all projects in directory

SKILL=$1
PROJECTS=$HOME/projects

for project in $PROJECTS/*; do
  if [ -d "$project/.claude" ]; then
    echo "Deploying $SKILL to $(basename $project)..."
    skillmeat deploy $SKILL --project "$project"
  fi
done

Bulk Collection Management

#!/bin/bash
# Refresh and verify collection

echo "Creating safety snapshot..."
skillmeat snapshot "Pre-bulk-refresh"

echo "Refreshing metadata..."
skillmeat collection refresh --dry-run
skillmeat collection refresh

echo "Verifying artifacts..."
skillmeat list
skillmeat analytics

Collection Export and Backup

# Export entire collection for backup
skillmeat export --output backup.tar.gz

# Export specific type
skillmeat export --type skill --output skills.tar.gz

# Share exported collection
tar -tzf backup.tar.gz | head -10

Finding Deployment Opportunities

# Find all artifacts not yet deployed
skillmeat search "*" --json | \
  jq '.artifacts[] | select(.deployment_count == 0)'

# Find unused artifacts across projects
skillmeat analytics unused --projects ~/projects/*

JSON Output for Automation

All major commands support JSON output for scripting:

# Get search results as JSON
skillmeat search "api" --json | jq '.artifacts'

# List artifacts as JSON
skillmeat list --json | jq '.artifacts[] | {name, type}'

# Get analytics as JSON
skillmeat analytics --json | jq '.top_artifacts'

# Parse and filter in scripts
skillmeat search "*" --type skill --json | \
  jq '.artifacts[] | select(.popularity > 50)'

Troubleshooting

"Collection not found" Error

# List available collections
skillmeat collection list

# Use correct collection name
skillmeat list --collection work

# Or switch to it first
skillmeat collection use work
skillmeat list

Search Returns No Results

# Verify artifacts exist
skillmeat list

# Try broader search term
skillmeat search "skill"

# Bypass cache
skillmeat search "handler" --no-cache

# Check with metadata search only
skillmeat search "pattern" --search-type metadata

Rate Limit Issues

# Check current rate limit
skillmeat config get github-rate-limit

# Set GitHub token
skillmeat config set github-token ghp_xxxxxxxxxxxx

# Refresh in batches instead of all at once
skillmeat collection refresh --type skill
sleep 60
skillmeat collection refresh --type command

Deployment Fails to Specific Project

# Verify project is registered
skillmeat project list

# Initialize if needed
cd /path/to/project
skillmeat init

# Deploy with verbose output
skillmeat deploy my-skill --verbose

# Check project structure
ls -la /path/to/project/.claude/

Next Steps