Skip to content

Existing Project Migrant Walkthrough

You have an existing .claude/ directory with manually created skills, commands, agents, and other artifacts. You want to bring them into SkillMeat to benefit from centralized management, versioning, and team sharing.

This walkthrough guides you through discovering what you have, reviewing your artifacts, importing them into a collection, organizing them with tags and groups, syncing with source control, and verifying your setup.

Prerequisites

Before you start, you need:

  • An existing .claude/ directory in a project with artifacts (skills, commands, agents, hooks, MCP servers, or workflows)
  • SkillMeat installed (see Quickstart Guide for installation)
  • The SkillMeat web UI running (skillmeat web dev)
  • Git repository for your project (optional, but recommended for sync and version tracking)

Phase 1: Initialize Your Collection

If you don't have a collection yet, create one. Skip this if you already have a collection.

# Initialize a default collection
skillmeat init

Output: 

Collection 'default' initialized
  Location: ~/.skillmeat/collection/
  Artifacts: 0

  1. Open http://localhost:8080 (after running skillmeat web dev)
  2. Click Create Collection on the home page
  3. Choose a name for your collection (e.g., "my-project-artifacts")
  4. Click Initialize

Verification: Your collection exists and shows 0 artifacts. You're ready to scan.

Phase 2: Scan Your Existing .claude/ Directory

Scanning discovers all artifacts in your project's .claude/ directory and identifies which ones match artifacts already in your collection (by SHA). Unmatched artifacts are queued for your manual approval.

# Preview what would be scanned and linked (dry-run first)
skillmeat sync-pull . --auto-link --dry-run

Output example: 

Scanning ./.claude/ for artifacts...
Found 12 artifacts to review:

Auto-Matched & Linked (SHA match):
  ✓ canvas-design (skill) — matched to collection version
  ✓ document-tools (skill) — matched to collection version
  ✓ research-assistant (skill) — matched to collection version

Queued for Manual Review:
  • github-helper (command) — no matching collection artifact
  • deploy-script (command) — no matching collection artifact
  • code-reviewer (agent) — no matching collection artifact
  • ci-integration (workflow) — no matching collection artifact

Run 'skillmeat sync-pull . --auto-link' to apply, then 'skillmeat import list' to review queued artifacts.

Once you're satisfied with the dry-run results, perform the actual scan and auto-link:

skillmeat sync-pull . --auto-link

Then check what's queued for review:

skillmeat import list
  1. Open the Artifacts page
  2. Click the Discovery tab
  3. Click Scan Project to start scanning ./.claude/
  4. SkillMeat scans your .claude/ directory and automatically links any artifacts that match by SHA
  5. Review the summary showing auto-matched artifacts and queued artifacts

Verification: Scan completes and displays auto-matched and queued artifacts. Note the queued count — you'll approve or reject these in Phase 3.

Phase 3: Import Unmatched Artifacts to Collection

After scanning, you have two options for artifacts that didn't auto-match: approve them via the queue, or import them directly to your collection. The direct import path is recommended for fastest migration.

Import unmatched artifacts directly to your collection in a single step:

# Run sync-pull again with --import-to-collection to bypass the approval queue
skillmeat sync-pull . --auto-link --import-to-collection

Output example: 

Scanning ./.claude/ for artifacts...
Auto-Matched & Linked (SHA match):
  ✓ canvas-design (skill) — matched to collection version

Importing to Collection (bypassing queue):
  ✓ github-helper (command) — imported to collection
  ✓ deploy-script (command) — imported to collection
  ✓ code-reviewer (agent) — imported to collection

Summary: Imported: 3 | Linked: 1 | Skipped: 0

This option imports unmatched artifacts directly to your collection without manual approval steps.

  1. Open the Artifacts page
  2. Find an artifact in your project that hasn't been imported yet
  3. Click the artifact to open its detail panel
  4. Go to the Collection tab
  5. Click Import to Collection to add it directly to your collection, or
  6. Click Link to Existing to find a matching artifact in your collection and link to it

If you prefer to review each artifact before importing, use the approval queue:

# Show all queued artifacts waiting for your decision
skillmeat import list

Output example: 

Pending imports (5 artifacts):

[1] github-helper (command)
    Path: ./.claude/commands/github-helper.yaml
    Status: pending_approval

[2] deploy-script (command)
    Path: ./.claude/commands/deploy-script.yaml
    Status: pending_approval

[3] code-reviewer (agent)
    Path: ./.claude/agents/code-reviewer.yaml
    Status: pending_approval

[4] ci-integration (workflow)
    Path: ./.claude/workflows/ci-integration.yaml
    Status: pending_approval

[5] experimental-tool (skill)
    Path: ./.claude/skills/experimental-tool.yaml
    Status: pending_approval

Inspect any artifact in detail before approving or rejecting:

skillmeat show github-helper

Verification: All unmatched artifacts are either imported to your collection or queued for review. You're ready to organize them in Phase 5.

Phase 4: Approve or Reject Queued Artifacts (Optional)

If you chose the queue-based import path in Phase 3, approve the artifacts you want to add to your collection, and reject any you don't need.

# Approve specific artifacts by name
skillmeat import approve github-helper
skillmeat import approve deploy-script

Output example: 

✓ github-helper (command) — approved and registered
✓ deploy-script (command) — approved and registered

Or reject artifacts you don't want:

skillmeat import reject experimental-tool

Output example: 

✓ experimental-tool (skill) — rejected and removed from queue

Approved artifacts are now part of your collection.

  1. In the Imports or Discovery tab, navigate through queued artifacts
  2. For each artifact:
  3. Click Approve to register it in your collection, or
  4. Click Reject to decline it without importing
  5. Review the summary showing approved and rejected counts
  6. Approved artifacts now appear in your Artifacts page

Note: Skip this phase if you used --import-to-collection in Phase 3 — those artifacts were imported directly and do not appear in the queue.

Verification: All queued artifacts (if any) have been either approved or rejected. Approved artifacts now appear in your collection and can be seen with skillmeat list or in the web UI Artifacts page.

Phase 5: Organize with Tags and Groups

Now that your artifacts are in the collection, organize them for easy discovery and sharing. Use tags to categorize by domain, purpose, or team. Use groups to create logical collections.

  1. Open the Artifacts page and find an artifact to organize
  2. Click the artifact to open its detail panel
  3. In the Tags section, click + Add tag and type tag names (e.g., "design", "ui", "research")
  4. Press Enter to save each tag
  5. To create a group:
  6. Click Groups in the left sidebar
  7. Click Create Group
  8. Enter a name and description (e.g., "Design Tools")
  9. Click Add Members and select artifacts to include

Tags and groups are currently managed through the web UI and API. To update tags via API:

# Find the artifact ID via API
ARTIFACT_ID=$(curl -s http://localhost:8080/api/v1/artifacts?search=canvas-design \
  | jq -r '.items[0].id')

# Update tags via API
curl -X PATCH http://localhost:8080/api/v1/artifacts/$ARTIFACT_ID \
  -H "Content-Type: application/json" \
  -d '{"tags": ["design", "ui", "frontend"]}'

Artifact details and tags can be viewed via CLI:

skillmeat show canvas-design

Verification: Your artifacts have tags assigned (visible in web UI and via skillmeat show). Groups are visible in the Groups section of the web UI.

Phase 6: Sync Your Project with Collection

Sync ensures your project artifacts stay in sync with your collection. The sync model is pull-based: you can pull changes from your project back to your collection, and check for drift between the two.

# Check the sync state between project and collection
skillmeat sync-state .

Output example: 

Sync status for ./.claude/:
  Last synced: 2026-05-24T14:32:00Z
  Artifacts in collection: 8
  Artifacts in project: 10
  Status: drift detected

Mismatches:
  • new-skill (project-only) — found in project but not in collection
  • old-command (collection-only) — in collection but not in project

Pull changes from your project back to your collection:

skillmeat sync-pull . --auto-link

Preview what would be synced without applying changes:

skillmeat sync-pull . --auto-link --dry-run

After syncing, commit collection changes:

git add ~/.skillmeat/collection/manifest.toml ~/.skillmeat/collection/lock.toml
git commit -m "chore: sync imported artifacts to collection"
git push
  1. Open Settings > Sync (if available) or Artifacts page
  2. Click Check Sync Status to view drift between project and collection
  3. Review any mismatches (project-only, collection-only, or version mismatches)
  4. Click Sync Project to pull changes from your project to collection
  5. Go to your Git repository and commit changes:
  6. git add ~/.skillmeat/collection/manifest.toml
  7. git commit -m "chore: sync imported artifacts"
  8. git push

Verification: Sync status shows all artifacts are in sync. Your repository has a new commit with the manifest and lock file updates (if there were changes).

Phase 7: Verify Versions and Understand Rollback

Verify that your artifacts have consistent versions recorded and understand how to roll back if needed.

# List all artifacts with version information
skillmeat list

Output example: 

Collection Artifacts:

Skills:
  • canvas-design (v1.0.0)
  • research-assistant (v2.1.0)
  • document-tools (v1.2.3)

Commands:
  • github-helper (v1.0.0)
  • deploy-script (v1.5.0)

Agents:
  • code-reviewer (v1.0.0)

To view version history and available snapshots:

skillmeat snapshot list

Output example: 

Available snapshots:

[1] snapshot-2026-05-24-143200
    Created: 2026-05-24 14:32:00 UTC
    Artifacts: 8
    Status: stable

[2] snapshot-2026-05-23-090000
    Created: 2026-05-23 09:00:00 UTC
    Artifacts: 7
    Status: stable

If you need to rollback to a previous snapshot:

skillmeat rollback snapshot-2026-05-23-090000
  1. Open Artifacts page to see all imported artifacts
  2. Click an artifact to view its Version field
  3. Under Settings > Snapshots (if available), view available rollback points
  4. Each snapshot shows:
  5. Creation timestamp
  6. Number of artifacts at that time
  7. Stability status
  8. To rollback:
  9. Click a snapshot
  10. Click Restore and confirm
  11. Your collection will revert to that snapshot's state

Verification: All artifacts show consistent version numbers. You've identified available snapshots for future recovery if needed. See Sync/Version/Rollback Guide for detailed version management procedures.

What You've Accomplished

✓ Scanned your existing .claude/ directory for artifacts
✓ Reviewed discovered artifacts and chose what to import
✓ Imported artifacts into a centralized SkillMeat collection
✓ Organized artifacts with tags and groups
✓ Synced your collection to version control
✓ Verified artifact versions and rollback options

Your artifacts are now centralized, versioned, and ready to share with your team.

Next Steps

  • Deploy artifacts to projects: Use Deploying Artifacts Guide to apply your artifacts to new or existing projects
  • Add new artifacts: Learn to add from marketplace sources with Adding Artifacts Guide
  • Deep dive on scanning and post-import organization: Read Scan & Import Guide for advanced options like filtering and bulk operations
  • Understand sync and rollback in detail: See Sync/Version/Rollback Guide for version pinning, breaking changes, and recovery (coming in v1 docs rollout)
  • Share with your team: Check Marketplace Guide to publish your artifacts for team reuse

Troubleshooting

Scan found 0 artifacts - Verify your .claude/ directory exists at the root of your project - Check that artifact files are in valid format (.yaml or .json) - Ensure the directory structure matches SkillMeat's expected layout (e.g., ./.claude/skills/, ./.claude/commands/) - Try a dry-run first: skillmeat sync-pull . --auto-link --dry-run to preview what would be found

No queued artifacts after scan - All discovered artifacts matched collection artifacts by SHA and were auto-linked - This is normal if you're re-scanning a project you've already synced - To see auto-linked artifacts in your collection: skillmeat list

Approval/rejection of queued artifacts failed - Check that the artifact name is correct: skillmeat import list shows exact names - Verify the artifact hasn't already been approved or rejected: skillmeat import list shows current status - See the error message for details on validation errors

Artifact not appearing after approval - Ensure approval completed successfully (check command output) - Refresh the web UI or run skillmeat list in CLI - Verify the artifact was approved, not rejected: skillmeat import list shows final status

Sync shows drift between project and collection - This is normal if you've made local changes to your project's .claude/ directory - Run skillmeat sync-pull . --auto-link --dry-run to preview changes before applying - Run skillmeat sync-pull . --auto-link to update your collection with project changes - Commit collection changes afterward: git add ~/.skillmeat/collection/ && git commit -m "chore: sync"

Cannot rollback to a snapshot - Verify the snapshot ID is correct: skillmeat snapshot list shows available IDs - Check that you have write permissions to your collection directory - See Sync/Version/Rollback Guide for detailed recovery procedures

Ready to dive deeper? Explore the User Guides section for task-oriented documentation on every SkillMeat feature.