Skip to content

Adding Artifacts to Your Collection

Learn how to add artifacts from three sources: the SkillMeat marketplace, GitHub repositories, or your local filesystem. This guide covers the complete workflow for each source, from discovery through verification.

Walkthroughs available

See the New Project Developer Walkthrough for onboarding or the ML Engineer Walkthrough for advanced artifact import workflows.

Overview

SkillMeat's artifact sources give you flexibility in how you build your collection:

Source Best For Authentication
Marketplace Published, tested artifacts with governance None required (optional token for publishing)
GitHub Custom artifacts, private repositories, specific versions GitHub token for private repos
Local Artifacts you've created locally, path-based sources None

The entire process is accessible via both CLI and Web UI. Choose whichever fits your workflow.

Prerequisites

Before adding artifacts, you need:

  1. SkillMeat installed — See Quickstart Guide
  2. Collection initialized — Run skillmeat init or use the Web UI setup. See Collection Initialization & Configuration
  3. Optional: GitHub token — Required only for private repositories. See Authentication Setup for details

To verify your collection is ready:

skillmeat list

You should see a collection listing, even if empty: 

Artifacts (0)
No artifacts in your collection yet.

  1. Open the Web UI (typically http://localhost:8000)
  2. Navigate to the Collection tab
  3. You should see an empty collection or existing artifacts

Add from the Marketplace

The SkillMeat marketplace contains pre-built, tested artifacts published by the community and Anthropic.

Using the CLI

Add a marketplace artifact by name:

skillmeat add marketplace:skill:canvas-design

Or use the shorthand (marketplace is default):

skillmeat add skill:canvas-design

Finding marketplace artifacts

Use skillmeat search to find available artifacts: 

skillmeat search canvas
skillmeat search --type skill
skillmeat search --tag design

Using the Web UI

  1. Open the Web UI
  2. Navigate to Collection → Add Artifact
  3. Select Marketplace tab
  4. Search for artifacts by name, type, or tag
  5. Select an artifact to view details
  6. Review permissions and dependencies (displayed in modal)
  7. Confirm to add to your collection

The artifact is now added and ready to deploy.

Verify Installation

skillmeat list --type skill

Your new artifact appears in the list.

Navigate to Collection → Artifacts. Your new artifact appears in the grid with a "Marketplace" badge.

For more details on marketplace features, version pinning, and publishing, see Marketplace Full Guide.

Add from a GitHub Repository

Add artifacts directly from a GitHub repository. You can specify versions, paths to nested artifacts, and use either public or private repositories.

GitHub Source Format

The standard format for GitHub sources is:

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

Components: - username — GitHub username (or organization) - repo — Repository name - path/to/artifact — Path within the repository (often .claude/skills/skill-name, etc.) - @version — Optional version specifier

Version options: - @latest — Latest release or main branch (default if omitted) - @v1.2.0 — Specific version tag - @abc1234 — Specific commit SHA (7 digits or more)

Examples

# Latest version of a public artifact
skillmeat add anthropics/skills/canvas-design

# Specific version (tag)
skillmeat add user/repo/path/to/skill@v2.0.0

# Specific commit
skillmeat add user/repo/path/to/agent@abc1234

# Nested path
skillmeat add org/repo/.claude/agents/code-reviewer

Using the CLI

Add an artifact from GitHub:

skillmeat add anthropics/skills/canvas-design

You'll see a permissions prompt. Review the artifact details:

Fetching from GitHub: anthropics/skills/canvas-design...
Artifact: canvas-design
Type: skill
Size: 156 KB
Dependencies: None
Permissions: Modify filesystem
[y/n] Continue?

Review the warnings and confirm with y to add.

Private repositories

If adding from a private repository, ensure you have a GitHub token configured: 

skillmeat config set github-token YOUR_TOKEN
See Authentication Setup for full details.

Using the Web UI

  1. Open the Web UI
  2. Navigate to Collection → Add Artifact
  3. Select GitHub tab
  4. Enter the GitHub source:
  5. Enter in the format username/repo/path[@version]
  6. Or use the Repository Browser to navigate
  7. Select the artifact
  8. Review permissions (displayed in modal)
  9. Confirm to add to your collection

Verify Installation

skillmeat list

Look for an artifact with origin github: 

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

Navigate to Collection → Artifacts. Your new artifact shows with a "GitHub" origin badge and version information.

For advanced GitHub features and private repository handling, see Authentication Setup.

Add from a Local Source

Add artifacts you've created locally or downloaded manually to your collection.

Using the CLI

Add an artifact from a local path:

skillmeat add ./path/to/my-skill

Or from an absolute path:

skillmeat add /Users/username/.claude/skills/my-custom-skill

The system validates the artifact structure and adds it with a local source designation.

Local artifact requirements

Your artifact directory must contain: - Valid frontmatter in a .md file (for metadata) - Code files (.py, .ts, .js, etc.) - Optional: dependencies.txt or package.json for dependencies

Using the Web UI

  1. Open the Web UI
  2. Navigate to Collection → Add Artifact
  3. Select Local tab
  4. Choose method:
  5. Browse — Select folder from your system
  6. Paste path — Enter the full path to your artifact
  7. Confirm the artifact details
  8. Review permissions in the modal
  9. Confirm to add to your collection

Verify Installation

skillmeat list --origin local

Your artifact appears with origin local: 

Artifacts (1)
┌─────────────┬────────┬────────┐
│ Name        │ Type   │ Origin │
├─────────────┼────────┼────────┤
│ my-skill    │ skill  │ local  │
└─────────────┴────────┴────────┘

Navigate to Collection → Artifacts. Your new artifact shows with a "Local" origin badge.

Sometimes you've written or heavily customized a skill — maybe you forked an upstream skill and made it your own — and you want both things to be true at once:

  • Your version is the canonical content in your collection and projects.
  • The GitHub upstream is recorded as the origin so SkillMeat can show you diffs, track provenance, and let you compare against the original.

This is the "link without losing my version" pattern. It takes a few extra steps because there is no single command that sets both the upstream link and installs your content in one shot — you need to thread them together using add (to establish the link) and sync-pull --strategy overwrite (to flow your content in while keeping the link intact).

Why you can't just re-add from your local directory

Running skillmeat add skill ./my-skill --name skill-seekers --force after a GitHub import resets the origin to local and removes the upstream link entirely. The add command treats local paths as local-origin artifacts unconditionally. update --strategy local is not a workaround — it means "skip this artifact during updates," not "install from a local path."

Prerequisites

  • A GitHub repository containing the upstream version of the skill. You need the path in the format user/repo/path/to/skill.
  • Your customized version of the skill's files available locally.
  • A spare directory to use as a staging project (a temporary local folder — it doesn't have to be a real project).

Worked Example: skill_seekers

Suppose you have a customized version of skill_seekers (originally from yusufkaraaslan/Skill_Seekers) and you want your collection to show:

  • Origin: github
  • Upstream source: yusufkaraaslan/Skill_Seekers/skills/skill-seekers
  • Content: your version (v2.0, with expanded tools and updated instructions)

Here is the complete command sequence.

Step 1: Snapshot your collection (safety)

skillmeat snapshot -m "pre-relink skill_seekers"

Also copy your skill files to a safe location outside your collection, in case you need them:

cp -r ~/.skillmeat/collection/skills/skill_seekers/ ~/Desktop/skill_seekers_backup/

skillmeat add skill yusufkaraaslan/Skill_Seekers/skills/skill-seekers \
  --name skill_seekers \
  --force \
  --dangerously-skip-permissions
  • --force overwrites any existing skill_seekers entry in your collection.
  • The import sets origin=github, records the upstream URL, and pins the resolved commit SHA.
  • The content in your collection is now the upstream baseline — not your version yet.

No @ref needed for the default branch

If you omit @ref, SkillMeat resolves the repository's actual default branch automatically. If the upstream repo uses development instead of main as its default branch, that is what gets resolved.

Step 3: Deploy the upstream baseline to a staging project

Create an empty directory to use as a throwaway staging area:

mkdir -p /tmp/sm-staging
skillmeat deploy skill_seekers --project /tmp/sm-staging --overwrite --no-recipe-preview

This creates /tmp/sm-staging/.claude/skills/skill_seekers/ with the upstream baseline content.

Step 4: Replace the staging content with your version

Copy your customized files over the baseline:

cp -rf ~/Desktop/skill_seekers_backup/. /tmp/sm-staging/.claude/skills/skill_seekers/

Your files are now in the staging project. The upstream link in the collection is still intact.

Step 5: Flow your version back into the collection

skillmeat sync-pull /tmp/sm-staging \
  --strategy overwrite \
  --artifacts skill_seekers \
  --no-interactive

This copies your content into the collection and updates the lock hash. It does not rewrite the manifest, so origin, upstream, and resolved_sha remain exactly as they were set in Step 2.

Step 6: Deploy to your real project

skillmeat deploy skill_seekers --project /path/to/your/project --overwrite --no-recipe-preview

Step 7: Verify

# Check origin is still github
skillmeat show skill_seekers

# Confirm no drift (content hash matches)
skillmeat sync-check /path/to/your/project

skill_seekers should be absent from the drift list, meaning the deployed content hash matches the collection. The show output should display origin: github and the upstream URL.

What to Expect Afterward

Upstream diffs are available. Because resolved_sha is pinned to the GitHub commit you imported in Step 2, SkillMeat can diff your content against that baseline. Use the Sync tab in the web UI or skillmeat diff skill_seekers --upstream to see what you changed relative to the upstream.

Auto-update is pinned by default. The artifact's version is pinned to the SHA resolved during the import. Running skillmeat update --strategy upstream would pull the upstream's current HEAD over your content. That is intentional — you are in control of when (and whether) to pick up upstream changes. If you do want to pull an upstream update later, run skillmeat update skill_seekers and then re-apply your customizations.

Displayed description may be stale. The skillmeat show and skillmeat list output (and the web UI metadata card) display the description and name extracted from the upstream's frontmatter at import time. They will not automatically update to reflect your version's frontmatter until a future refresh-metadata capability is added. The content is correct — only the displayed description metadata lags. Treat the content hash match from sync-check as the real success signal.

History is not populated. The local edition of SkillMeat does not yet generate history events for add, sync-pull, or deploy operations. Provenance lives in resolved_sha and the content hash recorded in the lock file, not in a visible history log.

Verify Your Collection

After adding artifacts, verify they're properly stored:

Quick Count

skillmeat list

Open Collection → Artifacts. Verify the count and artifact cards appear.

Check Artifact Details

skillmeat info artifact-name

View metadata, version, dependencies, and installation status.

Click on any artifact card to view: - Full metadata and description - Version history - Dependencies - Origin and source information - Deployment status across projects

Troubleshooting

"Authentication failed" (Private GitHub Repo)

Problem: Error when adding from a private GitHub repository.

Solution: 1. Verify your GitHub token is set: 

skillmeat config show | grep github-token
2. If missing, set it: 
skillmeat config set github-token YOUR_GITHUB_TOKEN
3. Try adding again

See Authentication Setup for full token setup.

"Artifact not found" (GitHub Path)

Problem: The path user/repo/path doesn't exist or is spelled incorrectly.

Solution: 1. Verify the path exists in GitHub: - Visit https://github.com/user/repo/tree/main/path/to/artifact - Ensure the file structure is correct 2. Check the artifact source format: username/repo/path/to/artifact[@version] 3. Try the full path without abbreviations

"Version not found" (GitHub Version)

Problem: The version @v1.2.0 doesn't exist.

Solution: 1. Check available versions on GitHub: - Visit the Releases page in the repository - Confirm the version tag exists 2. Use @latest to get the default branch version 3. Or use a commit SHA: @abc1234 (7+ characters)

"Permission denied" (Local Path)

Problem: Cannot add artifact from local path due to permissions.

Solution: 1. Verify the directory exists and is readable: 

ls -la /path/to/artifact
2. Ensure you have read access: 
chmod +r -R /path/to/artifact
3. Try adding again

"Already in collection" (Duplicate)

Problem: Attempting to add an artifact that's already imported.

Solution: - This is normal. You can: - Skip the duplicate - Update the existing artifact to a newer version (see Sync, Version Management & Rollback) - Remove and re-add if needed

Next Steps

After adding artifacts to your collection:

  1. Deploy to a project — Make artifacts available in your .claude/ directory. See Deploying Artifacts
  2. Explore marketplace — Browse more artifacts and learn about governance. See Marketplace Full Guide
  3. Manage versions — Pin versions, sync updates, and rollback if needed. See Sync, Version Management & Rollback
  4. Link a custom skill to its GitHub origin — Keep your version canonical while tracking upstream. See Link Your Custom Skill to a GitHub Upstream above
  5. Organize your collection — Use tags, groups, and snapshots for better organization