Artifact Instance Scoping

When working in SkillMeat's enterprise edition, you can import and promote artifacts to multiple collection instances — your personal collection, team collections, or enterprise-wide collections — in a single operation.

This guide covers: - Understanding collection instances - Selecting target instances during import - Promoting artifacts to wider audiences - Understanding partial-success outcomes - DVCS branch limitations - Accessing the audit trail

What Are Collection Instances?

In SkillMeat's enterprise edition, collection instances form a three-tier governance hierarchy:

Tier	Instance Type	Scope	Visibility	Example
Personal	User instance	Only you	Only you	Your personal .skillmeat/collection/
Team	Team instance	Your team	Team members	"Platform Team" collection
Enterprise	Enterprise instance	Whole organization	All members	Organization-wide shared collection

Local edition: Only a personal instance exists (single-tenant).

Each instance has: - Independent artifact storage - Separate cache and version history - RBAC-controlled access (who can import) - Optional import governance policies

You typically have write access to your personal instance and may have write access to team or enterprise instances depending on your role.

Selecting Instances on Import

Web UI: Import Dialog

When importing artifacts via the marketplace, discovery, or manual create dialogs, you'll see an Instance Selector showing all instances you can write to:

Single instance (local edition):

Destination: My Collection (static label, no selector)

Multiple instances (enterprise):

Import to:
□ Personal (default)
☑ Platform Team
☑ Data Engineering

How to use: 1. In any import dialog, locate the "Import to" or "Destination" section 2. Check the boxes for all target instances (or leave unchecked to use your default) 3. On success, you'll see per-instance outcome badges: - Green badge: ✓ Success - Red badge with reason: ✗ Denied (permission or policy)

Web UI: Promotion

To promote an existing artifact to a wider audience:

1. Find the artifact in your collection
2. Open its context menu (three dots) on the artifact card
3. Click Promote
4. Select a single target instance (promotion is single-target in v1)
5. Optionally add promotion notes
6. Click Promote to confirm

Success is confirmed with a toast notification showing the lineage edge ID.

CLI: Multi-Instance Import Flags

All CLI import commands support --instance and --instances flags:

Repeat flag syntax (preferred):

skillmeat add https://github.com/user/repo/path/skill \
  --instance personal \
  --instance "Platform Team"

Comma-separated alias:

skillmeat add https://github.com/user/repo/path/skill \
  --instances "personal,Platform Team"

Default (no flag):

skillmeat add https://github.com/user/repo/path/skill
# Imports to your default instance only

Instance names are resolved automatically from your available targets.

CLI: Promotion Command

Promote an artifact to a wider audience:

# Basic promotion
skillmeat collection promote my-artifact --to "Platform Team"

# With optional notes
skillmeat collection promote my-artifact \
  --to "Platform Team" \
  --notes "Promoted from personal for team use"

# JSON output (for scripting)
skillmeat collection promote my-artifact \
  --to "Platform Team" \
  --output json

Output includes: - binding_id: The new collection binding ID - lineage_edge_id: Reference in the promotion history

CLI: Enterprise Commands

Extend multi-instance support to enterprise operations:

# Import from external source to multiple team collections
skillmeat enterprise import --from-collection /path/to/collection \
  --instance "Team A" \
  --instance "Team B"

# Deploy from personal to multiple enterprise instances
skillmeat enterprise deploy pull \
  --instance personal \
  --instance "Shared Deployments"

# Scan and auto-link artifacts across instances (discovers nested artifacts recursively)
skillmeat sync-pull --auto-link \
  --instance "Platform Team" \
  --instance "Shared Resources"

# Use --non-interactive for CI/CD (auto-approves all matched artifacts)
skillmeat sync-pull --auto-link \
  --instance "Platform Team" \
  --non-interactive

Auto-Link Recursive Discovery

The sync-pull --auto-link command automatically discovers and links artifacts at any depth in your project:

Supported artifact types discovered: - Skills (SKILL.md, SKILL.yaml) - Commands (COMMAND.md, COMMAND.yaml) - Agents (AGENT.md, AGENT.yaml) - Other artifact types (at any nesting level)

Discovery behavior: - Scans entire project directory recursively - Discovers artifacts in subdirectories (not just top-level) - Matches against collection artifacts by name and metadata - Creates collection links without requiring manual specification

Example discovery:

project/
  ├── .claude/
  │   ├── agents/
  │   │   ├── my-agent/       ← Discovered as "my-agent"
  │   │   │   └── AGENT.md
  │   │   └── team-agent/
  │   │       └── AGENT.md    ← Discovered as "team-agent"
  │   ├── skills/
  │   │   ├── core-skill/     ← Discovered as "core-skill"
  │   │   │   └── SKILL.md
  │   │   └── utils/
  │   │       ├── formatter/  ← Discovered as "formatter"
  │   │       │   └── SKILL.md
  │   │       └── validator/  ← Discovered as "validator"
  │   │           └── SKILL.md
  │   └── commands/           ← Discovered at any depth
  │       └── nested-cmd/
  │           └── COMMAND.md

Exit Codes & Output Formatting

When using multi-instance commands:

Exit Code	Meaning
0	All targets succeeded
2	Some targets succeeded, some denied or failed
1	All targets failed

Each command prints per-target output:

$ skillmeat add ./skill --instance personal --instance "Team A"
✓ personal: Bound skill-name (id: binding-123)
✗ Team A: Permission denied (requires team_admin role)

Exit: 2 (partial success)

Use --output json for programmatic parsing:

$ skillmeat add ./skill --instance personal --instance "Team A" --output json
[
  {
    "instance": "personal",
    "status": "success",
    "binding_id": "binding-123",
    "artifact_name": "skill-name"
  },
  {
    "instance": "Team A",
    "status": "denied",
    "reason": "Permission denied (requires team_admin role)"
  }
]

Understanding Partial-Success Outcomes

When importing to multiple instances, some may succeed and others may fail — this is called a partial-success outcome (HTTP 207 Multi-Status).

Common denial reasons:

Reason	Your Action
Permission denied (requires team_admin)	Ask a team admin to grant you import permission, or request they import on your behalf
Import policy: required-review	A team policy requires admin approval. Check the audit log for pending status.
Import policy: allow-all-members	Default permissive policy. You should have access; contact an admin if denied.

Web UI: Partial-Success Dialog

When a partial-success occurs, a dialog stays open showing:

Import Results
✓ Personal: 1 artifact imported
✗ Platform Team: Permission denied (requires team_admin)
✓ Data Engineering: 1 artifact imported

[View Details] [Try Again] [Close]

You can: - View Details to see which artifacts succeeded/failed - Try Again to retry denied instances (useful after gaining permission) - Close to dismiss

CLI: Partial-Success Handling

Exit code 2 indicates partial success. Use in scripts:

#!/bin/bash
skillmeat add ./skill --instance personal --instance "Team A"
EXIT_CODE=$?

case $EXIT_CODE in
  0)
    echo "All instances succeeded"
    ;;
  2)
    echo "Partial success. Check which instances failed and retry."
    ;;
  1)
    echo "All instances failed. Check permission and policies."
    exit 1
    ;;
esac

Promotion and DVCS: v1 Limitation

When you promote an artifact to a wider audience, the new binding always references the main branch of the source repository.

v1 behavior: - Promote from personal → Team instance - New binding in Team instance references ref: main - Even if personal binding references a feature branch, the team binding uses main

Why: In v1, artifact bindings don't record branch references. Future versions (v2+) will support promoting from the current branch.

Workaround: If you need to promote a feature-branch artifact: 1. Merge the feature branch to main 2. Wait for the main branch ref to resolve in your personal binding 3. Promote to the wider audience

Check your branch:

skillmeat collection list --include-refs
# Output includes: branch: main, branch: feature-x, etc.

Audit Trail

All imports and promotions are recorded in the instance import audit log, which begins on the date this feature ships.

Viewing the Audit Log (Admin)

Enterprise admins can query the audit log:

# List all import events (last 7 days)
skillmeat enterprise audit instance-imports

# Filter by actor (who imported)
skillmeat enterprise audit instance-imports --actor you@example.com

# Filter by target instance
skillmeat enterprise audit instance-imports --target-type team --target-id "Team A"

# Filter by action (import, promote, deploy)
skillmeat enterprise audit instance-imports --action promote

# Filter by date range
skillmeat enterprise audit instance-imports --since 2026-05-01 --until 2026-05-31

# JSON output for analysis
skillmeat enterprise audit instance-imports --output json

Output shows: - Actor (who performed the action) - Target instance (where it was imported) - Artifact name and ID - Timestamp - Action type (import, promote, deploy) - Status (success, denied) - Denial reason (if applicable)

What's Recorded

Every import records: - Actor: User who triggered the import - Action: import, promote, or deploy - Target instance: personal, team, or enterprise name - Artifact: name, type, version (if applicable) - Status: success, denied, or error - Reason: if denied (permission, policy, validation) - Timestamp: ISO 8601 UTC

Promotions also record the lineage edge (the relationship from source to destination binding).

Timeline

• Start date: Date this feature shipped
• Before that date: No audit records (feature did not exist)
• Going forward: All imports/promotions recorded automatically

For compliance, keep regular audit log exports (see admin guide for instructions).

Summary

Multi-instance import: - Web: Checkbox selector in import dialogs - CLI: --instance and --instances flags - Exit codes: 0 (all success), 2 (partial), 1 (all fail)

Promotion: - Web: Artifact card context menu → "Promote" - CLI: skillmeat collection promote <name> --to <instance> - Single-target in v1 (to main branch only)

Partial success: - Web: Dialog shows per-instance outcome - CLI: Exit code 2 with per-target output lines

Audit trail: - Admin query: skillmeat enterprise audit instance-imports - Records import, promote, deploy actions - Begins on feature ship date

See Also

• Artifact Instance Scoping Admin Guide — Policy configuration for team admins
• Enterprise Governance Guide — Broader RBAC and policy context