Skip to content

Scan & Import Existing Artifacts

Found artifacts scattered across your .claude/ directories? SkillMeat can automatically discover and import them into your collection in one workflow. This guide covers scanning, importing, organizing, and verifying artifacts.

Walkthrough available

See the Existing Project Migrant Walkthrough for a complete migration journey.

When to use this guide

Use this guide when you have an existing .claude/ directory with skills, commands, agents, hooks, or MCP servers that you want to bring into your SkillMeat collection.

For step-by-step scanning and import mechanics, see Discovery & Import Quick Guide.

Why Scan & Import?

Discovery saves time and reduces manual work:

Scenario Benefit
Artifact Audit Understand what artifacts you've created locally and their current state
Migration Move all local artifacts from .claude/ into your managed collection
Deduplication Identify duplicate artifacts and consolidate them
Organization Establish a single source of truth with tags, metadata, and aliases

Prerequisites

Before scanning, ensure:

  • SkillMeat initialized — Your collection exists at ~/.skillmeat/collection/
  • If not: Run skillmeat init (see Quickstart)
  • Target .claude/ directory identified — The project directory containing artifacts to scan
  • Web UI running (for Web UI workflow) — Optional but recommended for visual organization
  • Start with: skillmeat web dev

Workflow Overview

The complete scan-to-organization workflow has 5 steps:

  1. Scan for artifacts — Discover what exists
  2. Review results — Understand what was found
  3. Import artifacts — Add to your collection
  4. Organize & tag — Add metadata for future discovery
  5. Verify & deploy — Confirm success and deploy to projects

Scan for Artifacts

CLI Scan

Scan a specific directory for artifacts:

# Scan current project directory
skillmeat scan .

# Scan specific path
skillmeat scan /path/to/project

# Scan and show detailed output
skillmeat scan . --verbose

Expected output: 

Scanning for artifacts...

Found:
  Skills: 3
  Commands: 2
  Agents: 1
  Hooks: 1
  MCP Servers: 0

Total artifacts: 7

Details:
  .claude/skills/my-skill/SKILL.md
  .claude/commands/review-command/COMMAND.md
  .claude/agents/analyzer/AGENT.md
  ... (more details with --verbose)

  1. Navigate to Artifacts page
  2. Click Discover button (top of artifact list)
  3. The system auto-scans your project's .claude/ directory
  4. Review artifacts in the modal that appears

Understanding Scan Results

The scan returns artifacts grouped by type with status:

Field Meaning
Status: New Artifact not in collection; ready to import
Status: Exists Artifact already in collection (can skip or re-import)
Status: Conflict Same artifact name exists in collection with different content
Status: Error Artifact missing required metadata files (fix manually or skip)

Common scan results

  • Most artifacts show Status: New — they're fresh, ready to import
  • Re-running scan after import shows Status: Exists — normal, expected
  • Conflicts are rare; they indicate duplicate names with different content (decide which to keep)

Review Scan Results

Via CLI

List scan results with filters:

# Show all found artifacts
skillmeat scan . --list

# Show only new artifacts (ready to import)
skillmeat scan . --filter=new

# Show conflicts
skillmeat scan . --filter=conflict

# Export results to file for review
skillmeat scan . --output results.json

The Discovery Modal shows all results with:

  • Artifact name and type (skill, command, agent, etc.)
  • Description (from metadata)
  • Tags (if present in artifact)
  • Status badge (New, Exists, Conflict, Error)
  • Checkbox for selective import

Filtering in modal: - Click Type dropdown to filter by artifact type - Use Search box to find specific artifacts by name - Click Status to focus on New, Exists, or Conflict

Review Checklist

Before importing, scan the results for:

  • [ ] Artifacts you recognize — Most scanned artifacts should be yours
  • [ ] Unexpected artifacts — Any files that don't look like artifacts? Check them manually
  • [ ] Duplicates — Same artifact name in multiple locations? (rare, but possible)
  • [ ] Errors — Any artifacts with Status: Error? (usually missing metadata, safe to skip)

Resolving errors

If an artifact shows Status: Error, it's missing required files like SKILL.md or COMMAND.md.

Options: - Fix it manually — Add the missing metadata file, then re-scan - Skip it — Proceed without importing; you can import it later - Investigate — Check if the directory really is an artifact or just a regular folder

Import Artifacts

Import All Found Artifacts

# Import all artifacts from scan
skillmeat import --all

# Confirm when prompted
Import 7 artifacts? (y/n) y

Importing...
✓ my-skill (skill)
✓ review-command (command)
✓ analyzer (agent)
✓ ... (remaining)

Imported 7 artifacts
  1. In the Discovery Modal, all artifacts are pre-selected by default
  2. Click Import All (or Confirm Import)
  3. Progress bar shows import status
  4. Success message lists imported artifacts

Import Selected Artifacts

# Import specific artifact by name
skillmeat import my-skill

# Import multiple by name
skillmeat import my-skill review-command analyzer

# Import by type
skillmeat import --type=skill
skillmeat import --type=command --type=agent
  1. In the Discovery Modal, uncheck artifacts you don't want
  2. Check only the artifacts you want to import
  3. Click Import Selected
  4. Progress bar shows which artifacts succeeded

Import is deployable

When you import an artifact from your own .claude/ directory, SkillMeat: - Adds it to your collection - Automatically deploys it back to the project - This means no separate deploy step is needed — it's ready to use immediately

Handling Import Conflicts

If an artifact exists with the same name but different content:

# View conflict details
skillmeat import --show-conflicts

# Force import (overwrites collection version)
skillmeat import my-skill --force

# Interactive mode (choose per-artifact)
skillmeat import --interactive
  1. Look for artifacts with Status: Conflict badge
  2. Click the conflict badge to see details:
  3. What's in your collection now
  4. What's being scanned
  5. Choose:
  6. Keep Collection Version — Skip this import
  7. Replace with Scanned Version — Use the scanned artifact
  8. Proceed with import

Resolving conflicts

Conflicts usually mean you've updated an artifact since last import. Review both versions in the modal and decide which is more current.

Post-Import Organization

After importing, organize your artifacts with tags, aliases, and groupings for easy discovery later.

Tagging Imported Artifacts

# Add tags to imported artifact
skillmeat tag my-skill --add python,productivity

# View current tags
skillmeat info my-skill --tags

# Remove a tag
skillmeat tag my-skill --remove python

# Bulk tag multiple artifacts
skillmeat tag my-skill review-command --add imported
  1. Navigate to Artifacts
  2. Search for or scroll to the imported artifact
  3. Click the artifact to open details
  4. Click Tags section
  5. Add tags separated by commas (e.g., imported, python, productivity)
  6. Save

Using Aliases for Quick Access

# Set an alias (short name for quick reference)
skillmeat alias my-skill skill-name-is-too-long

# List all aliases
skillmeat alias --list

# Remove an alias
skillmeat alias my-skill --remove
  1. Open artifact details (search for artifact, click it)
  2. Look for Aliases field
  3. Enter comma-separated short names (e.g., skill, my-skill)
  4. Save

Grouping into Bundles (Optional)

Bundles group related artifacts for collective deployment:

# Create a bundle
skillmeat bundle create --name my-toolkit --description "Collection of my tools"

# Add imported artifacts to bundle
skillmeat bundle add my-toolkit my-skill review-command analyzer

# View bundle contents
skillmeat bundle show my-toolkit
  1. Navigate to Collections or Bundles section
  2. Click New Bundle
  3. Name: My Toolkit | Description: Collection of my tools
  4. Click Create
  5. Click Add Artifacts
  6. Search for and select the imported artifacts
  7. Save

When to use bundles

Bundles are useful when: - You have 3+ related artifacts that are always deployed together - You want to share a curated set with teammates - You need version control for a cohesive toolset

For most users, tags are sufficient for organization. See Bundle & Composite Authoring Guide for full bundle workflow.

Updating Metadata

# Edit description
skillmeat edit my-skill --description "Updated description here"

# Edit metadata
skillmeat edit my-skill --owner "team-name" --version "1.0.1"

# View all metadata
skillmeat info my-skill
  1. Open artifact details
  2. Click Edit or pencil icon
  3. Update fields:
  4. Description
  5. Version
  6. Owner/Scope
  7. Tags
  8. Visibility
  9. Save

Verification

Verify imports succeeded and are ready to use:

CLI Verification

# List imported artifacts
skillmeat list --imported

# Count total artifacts in collection
skillmeat stats

# Search for specific imported artifact
skillmeat search my-skill

# View detailed info on imported artifact
skillmeat info my-skill --full
  1. Navigate to Artifacts page
  2. Filter by Source: Imported (if available)
  3. Search for imported artifacts by name or tag
  4. Click each artifact to verify:
  5. Description is present
  6. Tags are applied
  7. Metadata is complete

Deployment Verification

Imported artifacts are automatically deployed to the project. Verify they exist:

# Check what's deployed in current project
skillmeat status

# List deployed artifacts
skillmeat list --deployed
  1. Navigate to Project Details (for the project you scanned)
  2. Click Deployments or Deployed Artifacts
  3. Search for your imported artifacts
  4. Confirm they show Status: Deployed

Verification checklist

  • [ ] Artifacts appear in skillmeat list
  • [ ] Tags/metadata are applied
  • [ ] Artifacts are deployed to project (in .claude/ directory)
  • [ ] skillmeat search <name> finds them
  • [ ] Running skillmeat status shows them as deployed

Troubleshooting

Scan finds no artifacts

Problem: Directory scanned but no artifacts detected.

Causes & solutions: - Wrong directory — Scan the project directory, not .claude/ itself 

skillmeat scan /path/to/project  # ✓ Correct
skillmeat scan /path/to/project/.claude  # ✗ Wrong
- Missing metadata files — Artifacts need SKILL.md, COMMAND.md, etc. - Check directory for these files: ls -la .claude/skills/ - Nested directories not recognized — If artifacts are in custom subdirectories - Manually import using skillmeat add instead (see Adding Artifacts)

Import fails with "conflict"

Problem: Artifact import blocked due to name conflict.

Solution: - Review what's in your collection: skillmeat info <artifact-name> - Choose to keep or replace version (use --force flag to auto-replace) - Or rename the scanned artifact before importing

Tags don't persist

Problem: Tags added after import disappear on refresh.

Solution: - Tags must be added in your collection, not in source files - After import, use skillmeat tag to add collection-level tags - These persist across refreshes and updates

Artifacts not appearing in Web UI

Problem: Imported artifacts visible in CLI but not in Web UI.

Solution: - Refresh the browser page (hard refresh: Cmd+Shift+R or Ctrl+Shift+R) - Restart the web server: skillmeat web dev (stop and restart) - Check browser console for errors (F12 → Console tab)

Best Practices

Scan Regularly

  • After new feature work — Scan to capture new artifacts
  • Monthly — Routine audit of what exists locally
  • Before cleanup — Identify what can be safely archived

Use Consistent Tags

Establish a tagging scheme early and use it consistently:

# Good: Consistent, descriptive
skillmeat tag my-skill --add python,productivity,core

# Less useful: Vague or inconsistent
skillmeat tag my-skill --add thing,stuff

Document Metadata

When organizing imported artifacts, include: - Description — What the artifact does - Tags — Category, language, purpose - Owner — Who maintains it - Version — Current version number

This helps future discovery and team collaboration.

Create Snapshots Before Bulk Import

If importing many artifacts, create a backup first:

skillmeat snapshot "Before importing 10 artifacts from project X"

This lets you rollback if something unexpected happens.

Next Steps

Now that your artifacts are scanned, imported, and organized: