Project Sync Workflow: End-to-End Artifact Management¶

SkillMeat manages your Claude Code artifacts across projects through a four-phase lifecycle:

Bootstrap — Connect your project and register existing artifacts
Grow — Add new artifacts to your collection
Deploy — Push collection artifacts to projects
Sync — Keep everything aligned as artifacts evolve

This guide walks you through the complete end-to-end workflow, covering both local and enterprise editions.

Walkthrough available

See the Existing Project Migrant Walkthrough for a real-world example of this complete workflow.

The Dual-Stack Architecture¶

SkillMeat uses two parallel storage systems:

System	Owner	Role	Location
Filesystem	CLI source of truth	Primary artifact storage	`~/.skillmeat/collection/` and `./.claude/`
Database Cache	Web source of truth	Indexed view for fast web queries	PostgreSQL (enterprise) or SQLite (local)
`.skillmeat-deployed.toml`	Deployment manifest	Tracks what's deployed where	Project `./.skillmeat-deployed.toml`

When you make changes: - CLI operations read/write the filesystem first, then sync to the DB cache - Web UI operations write to the DB first, then sync back to the filesystem - .skillmeat-deployed.toml acts as a deployment receipt — never edit manually

About the dual-stack

This design ensures that both CLI and web workflows can coexist. The filesystem is always the authoritative source for CLI users, while the database cache provides fast queries for the web UI.

Prerequisites¶

Before starting, confirm you have:

SkillMeat installed — Run skillmeat --version to verify
Collection initialized — Run skillmeat init if you haven't already (see Quickstart Guide)
For enterprise — Authenticate with skillmeat auth login --enterprise <url> if using enterprise edition
For Git deployment — GitHub personal access token (optional, for Git PR deployment)

Phase 1: Bootstrap Your Project (Local Edition)¶

Bootstrapping discovers and registers existing artifacts in your .claude/ directory. This is the fastest way to get an existing project under SkillMeat management.

Step 1: Scan for Existing Artifacts¶

Scan your project's .claude/ directory to discover all skills, commands, agents, hooks, and MCP servers:

cd /path/to/your/project
skillmeat sync-pull . --dry-run

This shows what artifacts exist without making changes. Example output:

Scanning .claude/ directory...

Found artifacts:
  Skills:    3 (my-skill-1, my-skill-2, feature-analyzer)
  Commands:  2 (review-command, deploy-command)
  Agents:    1 (code-reviewer)
  Hooks:     1 (pre-commit-hook)
  MCP:       0

Total: 7 artifacts

Auto-linkable (SHA matches collection): 2
Import queue (new to collection): 5

Recursive artifact discovery

The scanner recursively discovers nested file-based artifacts at any directory depth. Artifact names are derived from the filename stem (not the directory path). For example, .claude/agents/ai/agent-expert.md is discovered as the agent agent-expert, and .claude/commands/analyze/check-architecture.md is discovered as the command check-architecture. Common directories like __pycache__, node_modules, _meta, .DS_Store, and .git are automatically skipped.

Discovering Nested Artifacts¶

The scanner automatically discovers file-based artifacts regardless of nesting depth. This means you can organize your artifacts in subdirectories for better project structure:

.claude/
├── agents/
│   ├── ai/
│   │   ├── agent-expert.md          # discovered as agent: agent-expert
│   │   └── agent-reviewer.md        # discovered as agent: agent-reviewer
│   └── dev/
│       └── phase-owner.md           # discovered as agent: phase-owner
├── commands/
│   ├── analyze/
│   │   └── check-architecture.md    # discovered as command: check-architecture
│   └── deploy/
│       └── trigger-build.md         # discovered as command: trigger-build
├── skills/
│   ├── python/
│   │   └── test-generator.md        # discovered as skill: test-generator
│   └── web/
│       └── ui-auditor.md            # discovered as skill: ui-auditor
└── mcp/
    └── integrations/
        └── github-client.md         # discovered as MCP server: github-client

When you run sync-pull . --auto-link, all of these nested artifacts are discovered automatically. The artifact name comes from the filename stem, not the directory path, so you can organize them hierarchically without affecting their identity.

Step 2: Auto-Link and Queue for Import¶

Run the actual scan-and-import flow:

skillmeat sync-pull . --auto-link --non-interactive

This command: - Scans .claude/ for artifacts - Computes SHA-256 hashes of artifact content - Auto-links: Artifacts matching collection contents are linked immediately - Queues for approval: New artifacts are added to the import queue

Example output:

Syncing project...

Auto-linked (matched collection):
  ✓ canvas (skill)                  # Already in collection, linked
  ✓ python-review (command)         # Already in collection, linked

Queued for import (new artifacts):
  ⧖ my-custom-skill (skill)
  ⧖ deployment-agent (agent)
  ⧖ github-hook (hook)

Import queue: 3 items pending review
Run: skillmeat import list

Step 3: Review and Approve Imports¶

List the queued artifacts:

skillmeat import list

Example output:

Pending imports (3):

1. my-custom-skill
   Type: skill
   Size: 12 KB
   Description: (from SKILL.md if available)
   Status: pending

2. deployment-agent
   Type: agent
   Size: 8 KB
   ...

3. github-hook
   Type: hook
   ...

Reject artifacts that are not Claude Code artifacts (e.g., __pycache__, .DS_Store, build artifacts):

skillmeat import reject __pycache__
skillmeat import reject .DS_Store

Approve valid artifacts one at a time:

skillmeat import approve my-custom-skill
skillmeat import approve deployment-agent
skillmeat import approve github-hook

Or approve all at once with a script:

skillmeat import list --json | jq -r '.[] | select(.status=="pending") | .name' | \
  while read name; do
    skillmeat import approve "$name"
  done

Step 4: Verify Bootstrap Success¶

Check that artifacts were registered:

# View deployed artifacts in this project
skillmeat list --project .

# View the deployment manifest
cat .skillmeat-deployed.toml

Expected .skillmeat-deployed.toml structure:

[project]
initialized = true
version = "0.50.0"
initialized_at = "2026-05-23T10:30:00Z"

[[deployments]]
name = "canvas"
type = "skill"
scope = "collection"
deployed_at = "2026-05-23T10:30:00Z"
version = "2.1.0"
source = "anthropics/skills/canvas"

[[deployments]]
name = "my-custom-skill"
type = "skill"
scope = "local"
deployed_at = "2026-05-23T10:35:00Z"
version = "1.0.0"
source = "local:my-custom-skill"

Never edit .skillmeat-deployed.toml manually

This file is managed by SkillMeat. Always use CLI commands (deploy, undeploy, sync-pull) to update it.

Phase 1: Bootstrap Your Project (Enterprise Edition)¶

For enterprise, the bootstrap flow is extended to include organization-level federation.

Step 1: Authenticate to Enterprise¶

Sign in to your enterprise instance:

skillmeat auth login --enterprise https://your-enterprise.skillmeat.io

You'll be prompted for credentials (Clerk SSO or local credentials, depending on your admin's configuration). Example:

Logging in to enterprise...
Visit: https://your-enterprise.skillmeat.io/auth/login
Paste code: ABC123
✓ Authenticated as alice@company.com
✓ Token saved securely

Verify authentication:

skillmeat auth status

Step 2: Import Your Local Collection to Enterprise¶

If you have a local collection that you want to migrate to enterprise:

skillmeat enterprise import --from-collection

This uploads all artifacts from your local ~/.skillmeat/collection/ to your enterprise organization. Example output:

Importing local collection to enterprise...

Uploading artifacts:
  ✓ canvas (skill)              v2.1.0
  ✓ python-review (command)     v1.3.2
  ✓ my-custom-skill (skill)     v1.0.0
  ... (more artifacts)

Uploaded: 23 artifacts
✓ Collection imported successfully

Step 3: Pull Enterprise Deployments to Your Project¶

Your admin may have created artifact bundles or deployment sets for your team. Pull them to your local project:

skillmeat enterprise deploy pull

This fetches pending deployments for your project. Example output:

Pulling pending enterprise deployments...

New deployments available:
  ✓ team-starter-bundle (composite)  - deploys 5 artifacts
  ✓ frontend-stack (deployment-set)  - includes React components

Deploy? (y/n): y

Deploying team-starter-bundle...
  ✓ canvas (skill)
  ✓ code-review (command)
  ✓ ui-components (context-module)
  ... (more artifacts)

✓ 5 artifacts deployed

Step 4: Check Enterprise Deployment Status¶

View what's been deployed:

skillmeat enterprise deploy status

Example output:

Deployment Status

Materialized (active in your project):
  ✓ canvas                 v2.1.0  deployed by alice@company.com on 2026-05-23
  ✓ code-review            v1.3.2  deployed by alice@company.com on 2026-05-23
  ✓ team-starter-bundle    v1.0.0  deployed by team-admin on 2026-05-22

Pending (awaiting your pull):
  ⧖ governance-agent       v1.1.0  created by admin on 2026-05-22
  ⧖ compliance-check       v1.0.0  created by admin on 2026-05-21

Run: skillmeat enterprise deploy pull

Step 5: Complete Local Bootstrap¶

After enterprise setup, run the local bootstrap flow to register any additional project-specific artifacts:

cd /path/to/your/project
skillmeat sync-pull . --auto-link --non-interactive
skillmeat import list
# ... approve/reject as per Local Edition Step 3 ...

Phase 2: Growing Your Collection¶

Once bootstrapped, you add new artifacts to your collection. This happens through three main workflows.

Adding Artifacts from Your Project¶

When you create new artifacts locally:

# Add a new skill to the collection
skillmeat add skill ./.claude/skills/my-new-skill/

# Add a command
skillmeat add command ./.claude/commands/my-command/

# Add an agent
skillmeat add agent ./.claude/agents/my-agent/

The artifact is registered in your ~/.skillmeat/collection/ and becomes available for deployment to other projects.

Finding Artifacts in the Marketplace¶

Search for published artifacts from Anthropic or your organization:

# Search by keyword
skillmeat search "python testing"

# Search by intent
skillmeat discover "automated code review"

# List all available artifacts
skillmeat list --all

Adding from a GitHub Source¶

Import artifacts directly from GitHub repositories:

# Add from an organization's repo
skillmeat add skill anthropics/skills/canvas-design

# Add a specific version
skillmeat add skill anthropics/skills/canvas-design@v1.2.0

# Add from a nested path
skillmeat add skill owner/repo/path/to/skill@latest

Phase 3: Deploying Artifacts¶

Once you have artifacts in your collection, deploy them to projects.

Local Deployment¶

Deploy directly to your project's .claude/ directory:

# Deploy a single artifact
skillmeat deploy canvas --to /path/to/project

# Deploy multiple artifacts
skillmeat deploy canvas python-review my-custom-skill --to /path/to/project

# Deploy from current directory
cd /path/to/project
skillmeat deploy canvas

Verification:

# List deployed artifacts
skillmeat list --project /path/to/project

# Check files exist
ls -la /path/to/project/.claude/skills/canvas/

Deployment via Git Pull Request¶

Deploy through a GitHub pull request for team review and approval:

# Step 1: Set up a Git connection (one time)
skillmeat connection create \
  --repo https://github.com/team/my-project \
  --token ghp_your_github_pat \
  --branch main

# Step 2: Link connection to project (one time)
skillmeat project link-connection \
  --project /path/to/project \
  --connection https://github.com/team/my-project

# Step 3: Deploy via PR
skillmeat deploy canvas python-review \
  --to /path/to/project \
  --via-pr \
  --branch "chore/add-artifacts" \
  --title "Add canvas and python-review skills" \
  --description "Adding reusable Claude artifacts" \
  --reviewers alice,bob

This creates a pull request. Your team reviews the files, and you merge to deploy.

GitHub Personal Access Token

Create a PAT at GitHub Settings → Developer Settings → Personal Access Tokens. Use scope: repo (full control of private repositories). Store securely — treat it like a password.

Web UI Deployment¶

Use the web interface for guided deployment:

Navigate to Projects page
Open your target project and go to Artifacts tab
Click Add Artifacts or the Plus button
Search for and select artifacts
Click Deploy

Artifacts are immediately available in .claude/ after deployment.

Phase 4: Keeping Everything in Sync¶

Ongoing maintenance ensures your project stays aligned with your collection as artifacts evolve.

Detecting Drift¶

Check if your project's artifacts match your collection:

# Dry-run to see what would change
skillmeat sync-pull . --dry-run

Output shows three comparison scopes:

Comparing scopes:

SOURCE vs COLLECTION:
  No changes — collection is up-to-date with upstream

COLLECTION vs PROJECT:
  ⧖ python-review: newer version available (1.3.2 → 1.4.0)
  ⧖ canvas: local changes detected (modified locally)

SOURCE vs PROJECT:
  ⧖ python-review: 1 version behind upstream
  ⧖ my-custom-skill: collection has version; project missing

Pulling Collection Updates¶

Sync your project with the latest collection versions:

skillmeat sync-pull .

This updates artifacts in your project to match your collection's versions. Example output:

Syncing project with collection...

Updated:
  ✓ python-review     1.3.2 → 1.4.0
  ✓ canvas            2.0.1 → 2.1.0

Unchanged:
  ✓ my-custom-skill   1.0.0

Conflicts (manual merge needed):
  ⚠ code-review       (local modifications present)

✓ Sync complete (2 updated, 1 skipped, 1 conflict)

Local modifications

If you've customized an artifact locally, SkillMeat flags it as a conflict. You decide whether to keep the local version or update to the collection version.

Pushing Local Changes to Collection¶

When you modify an artifact in a project and want to update the collection:

skillmeat add skill /path/to/project/.claude/skills/my-skill/

This updates the collection version. If the artifact already exists, you're prompted to confirm the update:

Updating my-skill in collection...
  Version: 1.0.0 → 1.0.1
  Changes: 3 files modified
Confirm? (y/n): y
✓ my-skill updated in collection

Using the Web UI Sync Tab¶

The web UI provides visual sync management across all three comparison scopes:

Open your project and go to the Sync tab
Select a comparison scope (source-vs-collection, collection-vs-project, or source-vs-project)
Visual diff viewer shows line-by-line changes
Click Pull to accept upstream changes, or Keep to stay local
Merge button for complex conflicts with 3-way merge interface

The sync tab is useful for: - Visual inspection: See exactly what changed - Selective sync: Update specific artifacts, skip others - Conflict resolution: 3-way merge for modified artifacts - Version tracking: History of all syncs and changes

Version Management and Rollback¶

If you deploy an artifact and need to revert:

# View version history
skillmeat version list my-skill

# Restore a previous version
skillmeat version restore my-skill v1.0.0

Example output:

Version history for my-skill:

  v1.0.2  2026-05-23  current
  v1.0.1  2026-05-22
  v1.0.0  2026-05-20

Restoring v1.0.0...
✓ my-skill restored to v1.0.0

Or use the web UI:

Open the artifact's detail view
Go to the Versions tab
Select a previous version
Click Restore and confirm

Enterprise Federation Sync¶

If you're using SkillMeat Enterprise, additional features enable organization-wide artifact sharing.

Understanding Federation¶

Federation allows your organization to:

Cross-team sharing: Artifacts can be promoted from team collection to organization-wide marketplace
Approval workflows: Publishing shared artifacts may require governance approval
Data regions: Configure GDPR-compliant data storage (EU, US, etc.)
Access control: RBAC (Reader, Contributor, Maintainer, Admin) controls who can access what

Publishing Artifacts to Your Organization¶

Promote team artifacts to your organization's marketplace:

# Publish a skill for organization-wide use
skillmeat publish skill my-custom-skill \
  --org \
  --title "Custom Code Analysis Skill" \
  --description "Analyzes code patterns and suggests optimizations" \
  --tags "analysis,code-quality"

Your admin may require approval before artifacts go live (depends on governance settings). Check status:

skillmeat publish status my-custom-skill

Discovering Organization Artifacts¶

Find artifacts shared across your organization:

# Search organization marketplace
skillmeat search "python testing" --org

# Search by tag
skillmeat search --org --tag "automation"

# List all org artifacts
skillmeat list --org

Data Region Compliance¶

Your admin configures data regions for GDPR and regional compliance. When creating or syncing artifacts:

# Check current data region
skillmeat config get data-region

# Deploy to a specific region
skillmeat deploy my-skill --to /project --region eu

Example output:

Data Region Configuration

Current region: EU
  ✓ GDPR compliant
  ✓ Data stored in Frankfurt

Available regions:
  - eu (GDPR compliant, Frankfurt)
  - us (US data center, Virginia)
  - apac (Asia-Pacific, Singapore)

To change region, contact your admin.

Agent Integration (Automated Workflows)¶

For automated artifact management within Claude Code sessions, agents can invoke SkillMeat commands programmatically.

Loading the SkillMeat CLI Skill¶

Agents can access artifact management capabilities by loading the skill:

Skill("skillmeat-cli")

Use the skillmeat-cli skill to:
1. Search for Python testing artifacts
2. Deploy the best match to ./.claude/
3. Capture a memory of the deployment

Common Agent Workflows¶

Agents can:

Discover and deploy: Search for needed artifacts and deploy them mid-task
Capture memories: Record learnings (gotchas, decisions, patterns) for future agents
Batch operations: Deploy multiple artifacts, scaffold from bundles, manage versions
Non-interactive mode: Run batch operations with --non-interactive for unattended automation

See Using the SkillMeat CLI Skill for detailed agent integration patterns.

Best Practices¶

Bootstrap early — Run sync-pull when starting a new project to establish tracking
Commit .skillmeat-deployed.toml — Track deployment state in git for reproducibility
Use dry-run before sync — Always check with --dry-run before pulling updates
Organize with tags — Use tags and metadata to improve discoverability for future use
Group related artifacts — Create bundles for artifact sets that work together (see Bundle & Composite Authoring)
Review before deploying — Use the web UI to inspect diffs before merging changes
Automate with agents — Let agents discover and deploy needed artifacts during work
Regular syncs — Run sync-pull periodically to stay aligned with collection updates

Troubleshooting¶

"0 auto-linkable artifacts"¶

Problem: Running sync-pull --auto-link shows no auto-links, all artifacts queued for import.

Solution: This is normal for locally-authored artifacts. The auto-link feature matches SHA-256 hashes against your collection. Locally-created artifacts are new and won't match. Approve them manually using the import flow (Step 3 in Phase 1).

"Artifact not discovered despite being in .claude/"¶

Problem: An artifact file exists in your .claude/ directory but isn't discovered by the scanner.

Solution: 1. Verify the artifact is in a valid directory type: .claude/skills/, .claude/commands/, .claude/agents/, .claude/hooks/, or .claude/mcp/ 2. Check that the filename has the correct extension (.md, .yaml, or .yml for file-based artifacts) 3. Ensure the parent directory isn't in the skip list: __pycache__, node_modules, _meta, .DS_Store, .git 4. Run sync-pull --dry-run to see all discovered artifacts and debug which ones were skipped 5. If the artifact is in a deeply nested path (e.g., .claude/skills/subdirectory/deep-nested/my-skill.md), the scanner will find it — artifact names come from the filename stem, not the directory path

"Stale web UI data"¶

Problem: Web UI shows outdated artifact versions or deployment status.

Solution: Refresh the cache:

curl -X POST http://localhost:8080/api/v1/cache/refresh

For enterprise, contact your admin if cache refresh doesn't resolve the issue.

"Sync shows conflicts"¶

Problem: sync-pull reports conflicts when you've modified artifacts locally.

Solution: You have two options:

Keep local version: Do nothing and run skillmeat sync-pull . --skip-conflicts
Update to collection version: Run skillmeat sync-pull . --force-update
Merge manually: Use web UI sync tab for 3-way merge

"Enterprise auth fails"¶

Problem: skillmeat auth login --enterprise fails or times out.

Solution: 1. Verify the enterprise URL is correct 2. Check your internet connection 3. Ensure your account exists on the enterprise instance (ask your admin) 4. Try re-authenticating: skillmeat auth logout && skillmeat auth login --enterprise <url>

"Deployment creates empty files"¶

Problem: Deployed artifacts have empty or truncated content.

Solution: 1. Verify artifact integrity: skillmeat show <artifact-name> 2. Check artifact size: skillmeat show <artifact-name> --verbose 3. If artifact is corrupted, re-add it: skillmeat add <type> <path>

Next Steps¶

Scan & Import Existing Artifacts — Detailed scanner mechanics and organization
Deploying Artifacts — Advanced deployment strategies
Syncing Changes Guide — Detailed sync workflows and conflict resolution
Bundle & Composite Authoring — Group artifacts into deployable bundles
Enterprise Admin Workflow — For admins setting up enterprise
Using the SkillMeat CLI Skill — Agent integration and automation