Skip to content

Extracting Embedded Artifacts

Embedded artifacts—agents, commands, hooks, and sub-skills nested inside a container (skill, composite, bundle)—can be promoted to standalone, independently-versioned collection members. This guide explains when to extract, how extraction works, and how SkillMeat deduplicates and versions extracted children.

Overview

What is an embedded artifact?

An embedded artifact is a child artifact that lives inside a container. Common examples:

  • An agent defined inside a skill's .claude/agents/ folder
  • A command defined inside a skill's .claude/commands/ folder
  • A hook defined inside a skill's .claude/hooks/ folder
  • A sub-skill referenced inside a composite

By default, embedded artifacts are tied to their parent container. Extracting promotes them to standalone collection members.

Why extract?

Reasons to extract embedded artifacts:

  1. Reuse: Use the extracted artifact in multiple parents without duplication
  2. Independent versioning: Edit and version the child separately; edits append as new versions rather than modifying the parent
  3. Discoverability: Extracted artifacts appear in your collection browser, searchable and taggable
  4. Deployment flexibility: Deploy the child independently or as part of the parent

Extraction Workflow

Extracting a child artifact

When you import or sync a container, SkillMeat automatically detects embedded children and offers an Extract action in the UI.

  1. Open a container artifact (e.g., a skill) in the artifact browser
  2. In the Contains tab, you'll see embedded children listed
  3. Click the Extract button next to the child you want to promote
  4. Review the extraction summary (new collection member, content hash, version)
  5. Confirm to complete extraction
# List children in a container
skillmeat show skill:my-skill --contents

# Extract a child (example)
skillmeat extract-child skill:my-skill agents:my-agent

What happens during extraction

Extraction:

  1. Materializes the child to a standalone collection path (e.g., .claude/agents/my-agent/)
  2. Stores content in content-addressed storage (CAS) to enable deduplication
  3. Creates a collection membership record linking the child to your collection
  4. Indexes the child in the artifact browser with its own metadata, tags, and version history

The child is now a first-class collection member: independently versioned, deployable, and discoverable.

Deduplication

How deduplication works

SkillMeat uses content-addressed storage (CAS) to avoid byte duplication:

  • Each extracted child has a unique content hash (SHA-256)
  • If two containers have an embedded child with identical content, both link to the same underlying artifact version — no duplication
  • When a child is edited, a new version is appended (see "Editing Extracted Children" below)

Example:

Suppose you have two skills, each with an agent named analyzer. Both agents have identical code:

Skill A
└── agents/
    └── analyzer/  (code hash: abc123...)

Skill B
└── agents/
    └── analyzer/  (code hash: abc123...)

After extraction, both link to the same analyzer artifact. The content is stored once. If you later edit Skill A's agent, a new version of analyzer is created, and Skill A pins the new version while Skill B continues to pin the original.

Enterprise tenant isolation

In enterprise deployments, deduplication is scoped to your tenant. Children from different tenants are never linked, even if they have identical content.

Editing Extracted Children

Once extracted, children follow the same versioning model as any artifact:

Default: Version append

When you edit an extracted child, the change appends a new version to the existing artifact:

  1. Parent artifact is re-imported with the edited child
  2. SkillMeat detects same-name-different-content
  3. A new ArtifactVersion is created with the new content
  4. Parent's pin updates to the new version hash
  5. Version history is preserved; you can roll back or inspect previous versions

Example:

Artifact: analyzer (original)
├── Version 1 (hash: abc123...)
├── Version 2 (hash: def456...)  ← after first edit
└── Version 3 (hash: ghi789...)  ← after second edit

Parent pin: Version 3 (ghi789...)

Optional: Fork to a new name

To create an independent copy with a new name (preserving lineage):

  1. Use the Fork action in the UI (or CLI)
  2. Provide a new name (e.g., analyzer-fast)
  3. A new artifact is created as a sibling with explicit lineage
  4. Original parent continues pinning the original version
  5. Lineage is tracked in version metadata for audit trails

Example:

Original:
├── Artifact: analyzer (Version 3: ghi789...)
│   └── Parent pin: analyzer (ghi789...)

After fork to "analyzer-fast":
├── Artifact: analyzer (Version 3: ghi789...)
│   └── Parent pin: analyzer (ghi789...)
├── Artifact: analyzer-fast (Version 1: ghi789... + fork metadata)
│   └── Lineage: parent_hash = ghi789...

Common Patterns

Extracting a shared utility agent

You have a skill document-processor with an embedded agent markdown-formatter that you want to reuse in other skills:

  1. Open document-processor in the browser
  2. In the Contains tab, click Extract next to markdown-formatter
  3. markdown-formatter becomes a standalone collection member
  4. Other skills can now reference the extracted markdown-formatter instead of embedding a copy

Extracting and versioning

You extracted markdown-formatter and later improved it:

  1. Update markdown-formatter in its standalone folder
  2. Re-import or sync the updated skill
  3. A new version of markdown-formatter is appended automatically
  4. document-processor is pinned to the new version
  5. Other skills using markdown-formatter can upgrade independently via sync/pull

Rolling back an extracted child

You edited markdown-formatter and want to revert:

  1. Open markdown-formatter in the browser
  2. Go to the Versions tab
  3. Find the previous version
  4. Click Restore to revert the parent's pin to that version

Display & Discovery

Finding extracted children

Extracted artifacts appear in:

  • Artifact Browser (/artifacts) — searchable by name, type, tag
  • Collection context — listed under your collection membership
  • Parent's Contains tab — shows all extracted and embedded children with pinned versions

Metadata

Like any collection member, extracted children support:

  • Tags — organize by use case or domain
  • Description — document purpose and usage
  • Version history — inspect changes and roll back
  • Deployments — track which projects use this child

Troubleshooting

"Extract button is grayed out"

Extraction may be unavailable if:

  • The child is already extracted (already a collection member)
  • The feature is disabled in your SkillMeat instance (check settings)

"Child content is unchanged, but a new version was created"

This typically means a minor formatting change (whitespace, line endings) altered the content hash. New versions are created even for tiny changes to preserve exact reproducibility.

"Parent is pinned to the wrong version"

If a parent is pinned to an unexpected version:

  1. Check the version history of the child artifact
  2. Use the Sync/Diff tab to inspect the difference
  3. Pin to the correct version or re-import the parent

Best Practices

  1. Extract early if reuse is likely — Extracted artifacts are easier to manage across multiple parents than embedded children
  2. Use versions, not forks, for iterations — Version append preserves lineage and is the default; fork only when creating a true variant
  3. Tag extracted children — Use tags (e.g., utility, shared, domain:nlp) to organize and discover
  4. Review version history — Before deploying, check recent versions to understand changes
  5. Sync frequently — Use sync/pull to propagate improvements to all parents at once

Learn More

  • Bundle & Composite Authoring: bundle-composite-authoring.md — authoring containers with children
  • Version History: version-history.md — detailed version rollback and restore workflows
  • Syncing Changes: syncing-changes.md — sync/pull strategies for drift and updates