Skip to content

Collection Init & Configuration

Get your SkillMeat collection set up and configured for your needs. This guide covers initializing a new collection, configuring settings, and verifying your setup works properly.

Overview

A SkillMeat Collection is your personal library of artifacts—skills, commands, agents, MCP servers, and other Claude Code tools. Collections:

  • Store your artifacts locally on your machine
  • Sync with GitHub sources for version control
  • Deploy artifacts to your projects (.claude/ directories)
  • Support both single-user and team deployments

When to initialize: - First time installing SkillMeat - Creating a new collection for a different use case (e.g., work vs. personal) - Setting up SkillMeat on a new machine

Configuration includes: - GitHub authentication for private repos and higher rate limits - Default collection selection - Web UI preferences - Collection refresh and sync settings

Prerequisites

Required: - SkillMeat installed via pip, uv, or pipx (see Quickstart Guide) - Python 3.9+

Optional but recommended: - GitHub account with a personal access token (for private repos and higher rate limits) - Node.js 18+ if you plan to use the web UI

Zero-Auth Local Mode

SkillMeat runs in zero-auth local mode by default — no authentication required. For team or production setups, see Authentication Setup.

Walkthrough available

See the New Project Developer Walkthrough for a complete setup journey using this guide.

Initialize Your Collection

A collection is initialized with default settings and an empty artifact store. Choose the method that matches your workflow.

Create Default Collection

Initialize a collection named default:

skillmeat init

Output: 

Collection 'default' initialized
  Location: /home/user/.skillmeat/collections/default
  Artifacts: 0

Automatic Activation

The collection is now ready to use. Your first collection is automatically set as active.

Create Named Collection

Initialize a collection with a custom name:

skillmeat init --name work

Output: 

Collection 'work' initialized
  Location: /home/user/.skillmeat/collections/work
  Artifacts: 0

Use custom collections for different contexts (work, personal, experiments, etc.).

Specify Custom Location

Store the collection in a non-default directory:

skillmeat init --path /custom/path/my-collection

Useful if you: - Share a machine and want isolated collections - Store collections on a mounted network drive - Use a specific backup location

Create with GitHub Configuration

Initialize and configure GitHub auth at the same time:

skillmeat init --github-token ghp_your_token_here

See GitHub Authentication Guide for how to create a token.

Start the Web Server

Launch the SkillMeat web interface:

skillmeat web dev

Output: 

Starting frontend on http://localhost:3000
Starting backend on http://localhost:8080

Open http://localhost:3000 in your browser.

Initialization Flow

  1. Landing page — If no collection exists, you'll see the initialization prompt
  2. Create collection — Click "Create Collection" and enter:
  3. Collection name (default: default)
  4. Location (auto-calculated, but you can customize)
  5. Configure GitHub (optional) — Provide GitHub token if you plan to import from private repos
  6. Complete — Collection is created and you're redirected to the dashboard

Managing Collections in Web UI

  1. Open Settings → Collections
  2. View all your collections with their artifact counts
  3. Click + Create New to create additional collections
  4. Use the collection dropdown to switch active collections

Configure Your Collection

After initialization, configure settings for your workflow.

Set GitHub Token

Enable private repository access and increase rate limits:

skillmeat config set github-token ghp_your_token_here

To create a token: 1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) 2. Click "Generate new token" 3. Select scopes: repo (full control of private repos), read:user, read:org 4. Click "Generate token" and copy it immediately 5. Run the command above

Verify: 

skillmeat config get github-token
# Output: ghp_xxxx...xxxx (last 4 chars shown)

Set Default Collection

Choose which collection is active when you run commands:

skillmeat config set default-collection work

Now commands default to your work collection unless you specify otherwise:

skillmeat list
# Lists artifacts from 'work' collection

skillmeat list --collection personal
# Override with different collection

Verify: 

skillmeat config get default-collection
# Output: work

Set Collection Paths

Configure where SkillMeat stores collections:

skillmeat config set collection-path /home/user/my-artifacts

New collections will be created in this directory. Existing collections remain in their current location.

View All Configuration

List all your settings:

skillmeat config list

Output: 

Configuration Settings
Key                    Value
─────────────────────────────────────────
github-token           ghp_xxxx...xxxx
default-collection     work
collection-path        /home/user/.skillmeat
cache-enabled          true
sync-on-startup        true

Get Single Setting

Check a specific configuration value:

skillmeat config get github-token

Unset Configuration

Remove a setting to use defaults:

skillmeat config unset github-token

Access Settings

  1. Click Settings in the top navigation bar
  2. Select Collection Configuration

GitHub Token

  1. Under "GitHub Authentication", click Add Token
  2. Paste your personal access token
  3. Click Save

The UI will verify the token and show: - ✓ Token valid - Your GitHub username - Current rate limit status

To remove the token: - Click Remove next to the token entry

Set Default Collection

  1. Under "Active Collection", select your collection from the dropdown
  2. Changes save automatically
  3. This collection is used for all web operations

Collection Details

View information about each collection:

  1. Go to Collections tab
  2. Each collection card shows:
  3. Collection name
  4. Location on disk
  5. Total artifact count
  6. Last modified date
  7. Click a collection to see detailed settings

Sync & Refresh Settings

  1. Under "Advanced Options", configure:
  2. Auto-refresh on startup — Check for upstream changes
  3. Sync interval — How often to check for updates
  4. Dry-run mode — Preview changes before applying
  5. Click Save to apply

Preferences

Customize your collection experience:

  • Artifact sorting — By name, type, date, or custom
  • Default view — List, grid, or tree view
  • Notifications — Alert on update available or conflicts

Verify Your Setup

After initialization and configuration, verify everything works correctly.

List Your Collection

View what's in your collection:

skillmeat list

Output (empty collection): 

Artifacts (0)
No artifacts in your collection yet.
Run 'skillmeat add <source>' to add one.

Output (populated collection): 

Artifacts (3)
┌──────────────┬──────────┬────────┐
│ Name         │ Type     │ Origin │
├──────────────┼──────────┼────────┤
│ canvas       │ skill    │ github │
│ python-tools │ command  │ github │
│ code-review  │ agent    │ local  │
└──────────────┴──────────┴────────┘

Check GitHub Configuration

Verify your GitHub token is valid and working:

skillmeat config get github-token

Should show a masked token like: ghp_xxxx...xxxx

Test by adding an artifact from GitHub:

skillmeat add skill anthropics/skills/canvas --dry-run

If the token is valid, this shows what would be added without error.

View Collection Info

Get detailed information about your active collection:

skillmeat collection info

Output: 

Collection: default
Location: /home/user/.skillmeat/collections/default
Total artifacts: 3
Total size: 2.4 MB

Last modified: 2026-04-20 10:30:00
Last synced: 2026-04-20 10:15:00

Test Web Interface (Optional)

Start the web UI to verify everything connects:

skillmeat web dev

Visit http://localhost:3000 and verify: - Dashboard loads without errors - Your collection appears in the sidebar - Artifact list matches CLI output

Keyboard shortcut to stop: - Press Ctrl+C in the terminal

  1. Open http://localhost:3000 (if not already running, start with skillmeat web dev)
  2. You'll land on the Dashboard
  3. The left sidebar shows your active collection name

View Your Artifacts

  1. Click Artifacts in the left navigation
  2. Browse your collection:
  3. Search bar at top to find artifacts
  4. Filter by type (skill, command, agent, etc.)
  5. Sort by name, date created, or date modified
  6. Click any artifact to view details

Test GitHub Configuration

  1. Go to Settings → GitHub Authentication
  2. Verify token is configured:
  3. ✓ Token valid (green checkmark)
  4. Username displayed
  5. Rate limit shown
  6. If not configured or invalid, reconfigure following the Web UI section above

Verify Settings

  1. Go to Settings → Collection Configuration
  2. Check that:
  3. Active collection is set correctly
  4. All preferences are as expected
  5. GitHub token is configured (if needed)
  6. Click Test Connection if available to verify setup

Inspect a Snapshot

Collections automatically create snapshots. To verify this is working:

  1. Go to Settings → Snapshots
  2. You should see at least one snapshot (from initialization)
  3. Each snapshot shows:
  4. Timestamp created
  5. Artifact count at that time
  6. Custom message (if provided)

Common Configuration Scenarios

Scenario 1: Single User, Local Development

Goal: Set up SkillMeat for personal use on one machine

# Initialize with defaults
skillmeat init

# Set GitHub token for importing private skills
skillmeat config set github-token ghp_your_token

# Verify
skillmeat list
skillmeat config get github-token

Result: Ready to add artifacts from GitHub and your projects

Scenario 2: Multiple Collections for Different Contexts

Goal: Separate work artifacts from personal experiments

# Create work collection
skillmeat init --name work --github-token ghp_work_token

# Create personal collection
skillmeat init --name personal

# Switch between them
skillmeat config set default-collection work
skillmeat list  # Shows work artifacts

skillmeat config set default-collection personal
skillmeat list  # Shows personal artifacts

Result: Each collection maintains separate artifacts and settings

Scenario 3: Shared Machine with Isolated Collections

Goal: Each user on the machine has their own collection

# User Alice
skillmeat init --path /home/alice/.skillmeat/alice-collection --name alice

# User Bob
skillmeat init --path /home/bob/.skillmeat/bob-collection --name bob

# Each can configure independently without interfering

Result: Users don't see each other's artifacts

Scenario 4: Backup and Restore

Goal: Protect against accidental changes

# Create a snapshot before major changes
skillmeat snapshot "Before cleanup"

# If something goes wrong
skillmeat history  # List snapshots
skillmeat rollback <snapshot-id>  # Restore to snapshot

Result: Easy recovery from mistakes

Scenario 5: Team Deployment Setup

Goal: Set up for enterprise or team collaboration

# Initialize collection
skillmeat init

# Configure enterprise authentication
skillmeat config set enterprise-token <token>

# Configure team access
skillmeat config set team-id <team-id>

# Verify authentication works
skillmeat config get enterprise-token

Result: Ready for team deployments (see Server Setup for full enterprise configuration)

Troubleshooting

Collection already exists

Problem: Running skillmeat init fails with "Collection already exists"

Solution: 

# List your collections
skillmeat collection list

# Use existing collection
skillmeat config set default-collection <existing-name>

# Or delete old collection if you want fresh start (careful!)
skillmeat collection delete <old-name>

# Then initialize
skillmeat init

GitHub token not working

Problem: Getting rate limit errors or "authentication failed" when adding artifacts

Solution: 

# Verify token is set
skillmeat config get github-token

# Check token is valid by testing with explicit token
skillmeat add skill anthropics/skills/canvas --github-token ghp_newtoken

# If new token works, update config
skillmeat config set github-token ghp_newtoken

# If still failing, check token has right permissions:
# - Needs 'repo' scope (full control of private repos)
# - Needs 'read:user' and 'read:org' scopes

Also check: - Token hasn't expired (regenerate in GitHub settings) - Token hasn't been revoked - Repository still exists and is accessible - Rate limit hasn't been exceeded (check with skillmeat config get)

See GitHub Authentication Guide for detailed troubleshooting.

Web UI won't start

Problem: skillmeat web dev fails or UI doesn't load

Solution: 

# Check Node.js is installed
node --version  # Should be 18+

# Try starting with different ports
skillmeat web dev --port 4000

# Check if ports are in use
lsof -i :3000  # Check if 3000 in use
lsof -i :8080  # Check if 8080 in use

# Kill processes using those ports and retry

If still failing: 

# Run diagnostics
skillmeat web doctor

# This shows:
# - Node.js version
# - Python version
# - Available ports
# - Database connectivity
# - Git configuration

Collection path permission denied

Problem: Error when initializing at custom path (permission denied)

Solution: 

# Check directory permissions
ls -la /custom/path

# Ensure you own the directory
sudo chown -R $(whoami) /custom/path

# Or use a directory you definitely own
skillmeat init --path ~/my-collections/default

Settings not persisting

Problem: Configuration changes disappear after restart

Solution: 

# Verify settings are actually saved
skillmeat config list

# Check config file exists
cat ~/.skillmeat/config.toml

# If config.toml is empty or missing, reconfigure
skillmeat config set default-collection work
skillmeat config set github-token ghp_token

# Restart terminal/shell and verify
skillmeat config list

Next Steps

Now that your collection is initialized and configured:

  1. Adding Artifacts — Start importing artifacts from GitHub or local paths
  2. Deploying Artifacts — Deploy artifacts to your projects
  3. Web UI Guide — Learn the visual interface for managing collections
  4. Authentication Setup — Configure auth for team or production use
  5. GitHub Authentication Guide — Token setup and troubleshooting

For Team Deployments

If you're setting up for a team or organization:

  1. Server Setup Guide — Database configuration and production deployment
  2. Authentication Setup — Enable Clerk JWT or enterprise PAT
  3. Enterprise Admin Guide — Governance, bulk actions, activity monitoring
  4. Container Deployment — Deploy SkillMeat with Docker

See Also