Skip to content

Enterprise Add: Uploading Artifacts to Enterprise Instances

The skillmeat enterprise add CLI command uploads locally-authored artifacts (Skills, Commands, Agents, Rules, Specs, Context Files, or Templates) to a remote SkillMeat enterprise instance. It packages single files or directory layouts and POSTs them to the enterprise instance with automatic deduplication. If an artifact with the same content already exists, the command returns the existing ID. If content differs, the server publishes a new immutable version and updates the artifact—no prior versions are lost.

When to Use This Command

Use skillmeat enterprise add when you need to:

  • Upload a single artifact to an enterprise instance (e.g., a new Skill or Command)
  • Share locally-developed artifacts with your team on the enterprise instance
  • Idempotent uploads: Re-running with identical content returns the existing ID; changed content publishes a new immutable version
  • Avoid bundle overhead: For single artifacts, enterprise add is simpler than bundle publish-pack

For bulk uploads of entire collections, use skillmeat enterprise migrate instead.

For packaging multiple artifacts as a reusable unit, use skillmeat bundle publish-pack instead.

Prerequisites

Before using skillmeat enterprise add, ensure:

  1. Enterprise authentication is configured — your local ~/.skillmeat/enterprise.toml contains:
  2. url: The enterprise instance URL (e.g., https://skillmeat.myorg.com)
  3. token: A Personal Access Token (PAT) with artifact:write scope

Obtain credentials by running: 

skillmeat auth login --enterprise <url>

  1. You have write permissions on the enterprise instance — your PAT must hold the artifact:write scope

  2. The artifact is ready — the local file or directory exists and is well-formed

Basic Usage

Uploading a Single File

To upload a single-file artifact (Skill, Command, Agent, etc.):

skillmeat enterprise add ./my-skill.md

The command auto-detects the artifact type from the filename. On success, it prints the artifact ID:

✓ Uploaded artifact: skill:my-skill

Uploading a Directory Layout

To upload a directory-layout artifact (e.g., a Skill with sub-files):

skillmeat enterprise add ./my-skill-dir/

The directory structure is read and uploaded as a single artifact. The command auto-detects the type from the top-level structure.

Specifying Artifact Type Explicitly

If auto-detection doesn't work or you want to override it, use the --type flag:

skillmeat enterprise add ./my-artifact.txt --type command

Valid types: skill, command, agent, rule_file, spec_file, context_file, template.

Advanced Options

Owner Scope: Personal (Default) vs. Team

By default, artifacts are added to your personal collection (the default owner scope per SkillMeat's collection-scope rule). To add to a team collection, use the --scope flag:

skillmeat enterprise add ./my-skill.md --scope team:<team-name>

Replace <team-name> with the actual team name configured in your enterprise instance.

Scope options: - (omitted): Personal collection (default, recommended) - team:<name>: Team collection; requires team membership - For more details, see Collection Scope Reference

Create, Update & Re-Runs

The command supports three outcomes:

First-time upload (creates artifact)

skillmeat enterprise add ./my-skill.md
# Output: ✓ created artifact skill:my-skill (version <version-id>)

Identical content (no-op, idempotent)

# Re-run with same content
skillmeat enterprise add ./my-skill.md
# Output: = artifact skill:my-skill already up to date (no changes)

Changed content (publishes new version)

# Edit the file and re-run
skillmeat enterprise add ./my-skill.md
# Output: ↑ updated artifact skill:my-skill — published new version <version-id>

Server-side deduplication ensures all three outcomes are idempotent: - Identical re-uploads return the existing ID with no version change - Changed content publishes exactly one new immutable version; all prior versions remain in history - Multiple edits within a single upload are bundled into one atomic version (multi-file changes never split across versions)

Error Handling

If the upload fails, the command prints an error message and exits with code 1:

skillmeat enterprise add ./nonexistent.md
# Error: File not found: ./nonexistent.md
# Exit code: 1

Common errors and their causes:

Error Cause Fix
Authentication failed Enterprise PAT is missing or expired Run skillmeat auth login --enterprise <url>
Forbidden (403) PAT lacks artifact:write scope Contact your admin for a properly-scoped PAT
File not found Artifact path doesn't exist Check the file path and try again
Invalid artifact type --type value is not recognized Use one of: skill, command, agent, rule_file, spec_file, context_file, template
Server error (500) Enterprise instance is unreachable or misconfigured Contact your admin; check enterprise URL in ~/.skillmeat/enterprise.toml

Bulk Upload: enterprise migrate

For uploading an entire local collection to enterprise, use the migrate sub-command:

skillmeat enterprise migrate

This command: - Reads all artifacts from your local collection - Uploads each to the enterprise instance via POST /api/v1/artifacts/upload - Reports per-artifact success/failure - Exits with code 1 if any artifact fails (but continues processing remaining artifacts)

Supports --dry-run to preview without uploading:

skillmeat enterprise migrate --dry-run

For more details, see the enterprise migration documentation.

Comparison: enterprise add vs. bundle publish-pack

Aspect enterprise add bundle publish-pack
Use case Single artifact upload Multiple artifacts + reusability
Workflow Direct CLI command 1. Build pack, 2. Publish to enterprise
Create-or-update Automatic (server-side, creates on first add; publishes new version on content change) Automatic (server-side, creates on first add; publishes new version on content change)
Best for Quick single uploads Packaged bundles, team distributions
Team sharing Manual (each artifact separately) Distribute entire pack as a unit

Use enterprise add for ad-hoc single-artifact uploads. Use bundle publish-pack when you want to package multiple artifacts as a reusable unit (e.g., starter bundles, skill collections).

Integration with Edition Feature Matrix

For a complete reference of upload endpoints and CLI support across local and enterprise editions, see:

Troubleshooting

"Connection refused"

Cause: Enterprise instance URL is incorrect or unreachable.

Fix: 1. Check ~/.skillmeat/enterprise.toml for correct URL 2. Test connectivity: curl https://<url>/api/v1/health 3. Contact your admin if the instance is down

"Invalid or expired token"

Cause: PAT in ~/.skillmeat/enterprise.toml is invalid or expired.

Fix: 1. Re-authenticate: skillmeat auth login --enterprise <url> 2. Enter a fresh PAT from your admin (or generate a new one)

"Artifact type not detected"

Cause: Auto-detection failed (unusual filenames or layouts).

Fix: Explicitly specify the type with --type: 

skillmeat enterprise add ./my-file.txt --type command

"Forbidden (403) — insufficient scopes"

Cause: PAT lacks the artifact:write scope.

Fix: Request a new PAT from your admin with the required scope.