Skip to content

SkillMeat Quickstart Guide

Get started with SkillMeat in 5 minutes. This guide covers the essentials to create your first collection and deploy artifacts.

This guide uses zero-auth local mode — the default with no authentication required. For team or production deployments, see Authentication Setup and Server Setup after completing this quickstart.

Collection Scope

By default, SkillMeat operates in personal scope — all artifacts you create and manage belong to your personal collection. This is a security boundary, not a convenience feature.

If your instance has team or enterprise features enabled, you can switch scopes using:

# View your current scope
skillmeat collection scope show

# Switch to a team collection (if you have access)
skillmeat collection scope use team:<team-name>

# Note: Personal scope (the default) sends no extra parameters — 
# it's zero behavior change for existing users

For most users, personal scope is all you need. A dedicated collection-scope guide does not exist yet.

Installation

pip install skillmeat

Via uv (Fast)

uv tool install skillmeat

Via pipx

pipx install skillmeat

Using a virtual environment avoids permission issues and keeps your system Python clean:

python3 -m venv ~/.skillmeat-venv
source ~/.skillmeat-venv/bin/activate
pip install skillmeat

Add activation to your shell profile to persist across sessions:

echo 'source ~/.skillmeat-venv/bin/activate' >> ~/.bashrc  # or ~/.zshrc

From Source (Development)

git clone https://github.com/miethe/skillmeat.git
cd skillmeat
pip install -e ".[dev]"

First Steps

1. Initialize Your Collection

Create a default collection to store your Claude artifacts:

skillmeat init

This creates ~/.skillmeat/collections/default/ with an empty collection.

Output: 

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

2. Add Your First Artifact

Add a skill from GitHub using the add skill subcommand:

skillmeat add skill anthropics/skills/canvas

You'll be prompted with a security warning. Review and confirm to proceed.

Output: 

Fetching from GitHub: anthropics/skills/canvas...
Added skill: canvas

3. View Your Collection

List all artifacts in your collection:

skillmeat list

Output: 

Artifacts (1)
┌────────┬────────┬────────┐
│ Name   │ Type   │ Origin │
├────────┼────────┼────────┤
│ canvas │ skill  │ github │
└────────┴────────┴────────┘

4. Deploy to a Project

Deploy artifacts to your current project:

cd /path/to/your/project
skillmeat deploy canvas

Output: 

Deploying 1 artifact(s)...
Deployed 1 artifact(s)
  canvas -> .claude/skills/canvas/

The artifact is now available in your project's .claude/ directory!

Common Workflows

Add from Local Path

Add a custom artifact you've created:

skillmeat add skill ./my-custom-skill

Add Multiple Artifacts

skillmeat add skill anthropics/skills/python
skillmeat add command user/repo/commands/review
skillmeat add agent user/repo/agents/code-reviewer

Note: Use the skill, command, and agent subcommands to specify artifact type.

Deploy Multiple Artifacts

skillmeat deploy canvas python review

Check for Updates

skillmeat status

Create a Backup

Before making changes, create a snapshot:

skillmeat snapshot "Before cleanup"

Keeping Deployed Artifacts Current

Deploying copies an artifact from your collection into a project. That copy can drift — either because you changed the artifact in your collection, or because the project's copy was edited locally. Drift is detected, not silent: SkillMeat compares the deployed copy against your collection and reports the difference rather than overwriting either side.

You don't need to manage this during the quickstart — just know that if a deployed artifact and your collection disagree later, that's expected and there's a workflow for it:

Next Steps

Configuration

Set GitHub Token (for private repos)

skillmeat config set github-token ghp_your_token_here

Set Default Collection

skillmeat config set default-collection work

View All Settings

skillmeat config list

Directory Structure

After following this quickstart, you'll have:

~/.skillmeat/
├── config.toml              # Global configuration
└── collections/
    └── default/
        ├── collection.toml  # Collection manifest
        ├── collection.lock  # Version lock file
        ├── skills/
        │   └── canvas/      # Installed skill
        │       └── SKILL.md
        ├── commands/        # Command artifacts (if added)
        └── agents/          # Agent artifacts (if added)

/path/to/your/project/
└── .claude/
    ├── .skillmeat-deployed.toml  # Deployment tracking
    └── skills/
        └── canvas/               # Deployed skill
            └── SKILL.md

Collections organize artifacts by type into separate directories (skills, commands, agents).

Getting Help

  • View command help: skillmeat --help
  • View specific command help: skillmeat deploy --help
  • Check version: skillmeat --version

Troubleshooting

Collection already exists

# List collections
skillmeat collection list

# Use existing collection
skillmeat collection use default

GitHub rate limits

Set a GitHub token to increase rate limits:

skillmeat config set github-token ghp_your_token

Artifact not found

Make sure you're using the correct GitHub path format:

username/repo/path/to/artifact[@version]

Examples: - anthropics/skills/canvas (latest) - user/repo/skill@v1.0.0 (specific version) - user/repo/path/to/skill@abc123 (specific commit)

Web Interface (Optional)

Manage your collection visually with the web UI.

Prerequisites: Node.js 18+ must be installed on the system.

# Install frontend dependencies (first time only)
WEB_DIR=$(python -c "from pathlib import Path; import skillmeat; print(Path(skillmeat.__file__).parent / 'web')")
cd "$WEB_DIR" && npx pnpm@8.15.0 install --frozen-lockfile && cd -

# Start both servers
skillmeat web dev

This starts both the FastAPI backend and Next.js frontend on:

  • Frontend: http://localhost:3000
  • Backend API: http://localhost:8080

For more options (custom ports, hosts, etc.), see the CLI Reference.

Other web commands:

  • skillmeat web build - Build for production
  • skillmeat web start - Start production servers
  • skillmeat web doctor - Diagnose environment issues

What's Next?

You now know how to: - Initialize a collection - Add artifacts from GitHub and local paths - Deploy artifacts to projects - View and manage your collection - Create snapshots for backup - Access the web UI for visual management

Continue Learning