Using Recipes to Bootstrap Artifacts¶
Learn how to deploy artifacts that carry their own setup instructions via recipes — declarative operations that SkillMeat applies automatically, safely, and reversibly when you deploy them to your project.
What is a recipe?
A recipe is an optional recipe.toml file that an artifact author includes to describe first-run setup steps: editing CLAUDE.md, installing dependencies, registering hooks, or deploying workspace directories. When you deploy a recipe-equipped artifact, SkillMeat shows you exactly what will change before applying it.
Overview¶
In SkillMeat, artifacts like skills, commands, and agents often need to modify your project when they're first deployed — adding sections to .claude/, registering MCP servers, or setting up workspace directories. Without recipes, these setup steps were manual and error-prone: you had to read the artifact's SKILL.md, follow instructions, and hope nothing conflicts with other artifacts.
Recipes solve this by letting artifact authors declare setup operations in a structured format. When you deploy a recipe-equipped artifact, SkillMeat:
- Previews the changes — shows you a dry-run diff of what will be modified
- Detects conflicts — warns if another artifact is trying to modify the same files
- Applies safely — creates a snapshot of your project before making any changes
- Enables rollback —
skillmeat artifact uninstallrestores your project to the pre-recipe state - Logs everything — records all operations to
~/.skillmeat/audit/recipes.jsonlfor compliance
Recipes come in three tiers:
| Tier | Surface | Trust gate | When applied |
|---|---|---|---|
| T1 | Declarative operations (file copy, CLAUDE.md edits, workspace dirs) | None | On deploy with --apply-recipe |
| T2 | Sandboxed scripts (Python/shell) | Signed publisher OR per-artifact grant | With --apply-recipe --allow-script |
| T3 | Agent-driven setup (Claude Code subprocess) | Signed publisher AND opt-in | With --apply-recipe --allow-agent-step |
The MVP (v1) ships with T1 declarative operations. T2/T3 are available in v2 with additional opt-in gates.
Prerequisites¶
Before using recipes, you need:
- SkillMeat v2.0+ — Recipes are not available in v0.x or v1.x
- A connected collection — See Adding Artifacts to Your Collection
- A project initialized — Run
skillmeat initor use the Web UI. See Deploying Artifacts
To verify your setup:
Detecting Recipe-Equipped Artifacts¶
Artifacts that carry recipes are clearly marked in both the CLI and Web UI.
CLI¶
When you list artifacts, recipe-equipped artifacts display a Recipe indicator:
Output:
Artifacts (5)
┌──────────────────┬─────────┬──────────┬─────────┐
│ Name │ Type │ Origin │ Recipe │
├──────────────────┼─────────┼──────────┼─────────┤
│ demo-foundry │ skill │ github │ ✓ T1 │
│ clerk-install │ command │ github │ ✓ T2 │
│ canvas-design │ skill │ github │ — │
└──────────────────┴─────────┴──────────┴─────────┘
The Recipe column shows:
- ✓ T1 — declarative operations (safe to auto-apply)
- ✓ T2 — sandboxed scripts (requires explicit opt-in)
- ✓ T3 — agent-driven setup (requires explicit opt-in + trust)
- — — no recipe (standard artifact)
Web UI¶
- Open the Web UI
- Navigate to Collection → Artifacts
- Click on any artifact card to view details
- If the artifact has a recipe, the Recipe tab appears in the detail view
- The tab shows a Recipe badge with the tier level (T1, T2, or T3)
Deploying with a Recipe¶
Deploying an artifact with a recipe requires the --apply-recipe flag to opt in. This ensures you always review changes before applying them.
Basic Deploy with Recipe (CLI)¶
SkillMeat will: 1. Show a dry-run diff of all changes 2. Prompt for confirmation 3. Apply the recipe and create an audit entry
Example:
Output:
Recipe Plan for demo-foundry
────────────────────────────────
Operations:
OP-1: Copy file .claude/rules/demo-foundry-rules.md
OP-2: Merge CLAUDE.md at anchor [demo-foundry-config]
OP-6: Register hook: demo-foundry-post-deploy.sh
Diff Preview:
--- .claude/rules/demo-foundry-rules.md (new)
+++ .claude/rules/demo-foundry-rules.md
+ # Demo Foundry Rules
+ Use the foundry CLI for all artifact generation.
Apply recipe? [y/n]
Always review before applying
Take a moment to review the diff. If something looks unexpected, press n to cancel. You can ask the artifact author for clarification.
Dry-Run Only (Preview Without Applying)¶
To preview changes without applying them:
This shows the same diff but makes no changes. It's useful for planning or sharing changes with teammates.
Suppress the Preview¶
If you've reviewed the changes and want to skip the diff output (not recommended):
Audit Logging¶
Every recipe application is recorded in the audit log:
Example entry (pretty-printed):
{
"timestamp": "2026-05-17T14:32:00Z",
"artifact_id": "demo-foundry",
"artifact_version": "v1.2.0",
"recipe_tier": "t1",
"status": "success",
"operations_applied": 3,
"snapshot_id": "abc123def456...",
"user_identity": "alice@example.com",
"signer_fingerprint": null,
"verification_outcome": "not_applicable"
}
Dry-Run Preview¶
For recipe-equipped artifacts, skillmeat deploy always shows a dry-run preview by default. This is the safest way to review changes before committing them.
Understanding the Preview Output¶
The preview shows:
- Recipe metadata — artifact name, version, tier
- Operations table — each operation (OP-1, OP-2, etc.) and what it targets
- Unified diff — file-by-file changes (similar to
git diff) - Conflict warnings — if multiple artifacts try to modify the same anchor
Example preview:
Recipe Plan for clerk-install (v1.0.0)
──────────────────────────────────────
Tier: T1 (declarative)
Operations:
OP-1 FileCopy .claude/auth/clerk-config.md (1.2 KB)
OP-2 ClaudeMdMerge .claude/ at anchor [clerk-config]
OP-3 WorkspaceDir .claude/clerk-workspace/
Conflicts: None
Diff Preview:
===== .claude/auth/clerk-config.md =====
--- /dev/null
+++ .claude/auth/clerk-config.md
@@ -0,0 +1,15 @@
+ # Clerk Authentication Setup
+
+ To set up Clerk integration, follow these steps...
Reading the Operations List¶
Each operation code (OP-1 through OP-6) means:
| Code | Operation | Example |
|---|---|---|
| OP-1 | Copy artifact file to project | .claude/skills/demo-foundry/SKILL.md |
| OP-2 | Merge into CLAUDE.md at named anchor | Anchor: [demo-foundry-config] |
| OP-3 | Create workspace directory with marker | .claude/demo-foundry-workspace/ |
| OP-4 | Edit workflow file at named anchor | Anchor: [demo-foundry-steps] |
| OP-6 | Register hook or MCP server | Hook: post-deploy-demo-foundry.sh |
Conflict Detection¶
If SkillMeat detects conflicts — two artifacts trying to modify the same anchor or file — the preview will show:
⚠️ Conflicts Detected (blocking):
Conflict 1: Anchor [config-section] in .claude/
- Artifact A (v1.0.0) already applied
- Artifact B (v2.0.0) wants to modify the same anchor
Resolution: Uninstall A first, or ask the artifact authors to use different anchors.
When conflicts are detected, the recipe will not apply. You must resolve the conflict manually (usually by uninstalling one of the conflicting artifacts).
Sandbox Tiers (T2/T3) Opt-In¶
v2 feature
Sandbox execution (T2/T3) is available in SkillMeat v2+. In v1 (MVP), only T1 declarative operations are supported.
T2 and T3 recipes require explicit opt-in because they execute code. They are gated behind additional flags and trust checks.
T2 Sandboxed Scripts¶
T2 recipes include scripts (Python or shell) that run in a restricted sandbox:
T2 scripts run in an isolated environment with limited filesystem and network access. The script cannot: - Access files outside your project - Make unrestricted network calls - Fork arbitrary subprocesses
Trust gates for T2:
- Artifact signed by Anthropic → Automatically trusted; script runs
- Community artifact → You must explicitly grant trust:
- Unsigned artifact → Not allowed; rejected with error
T3 Agent-Driven Setup¶
Experimental
T3 agent execution is experimental and disabled by default in v2. Enable only if you trust the artifact author.
T3 recipes invoke a Claude Code agent subprocess with limited tool permissions:
T3 requires:
1. Publisher trust — same as T2 (artifact must be signed or explicitly granted)
2. Staged plan review — the agent generates a plan in JSON; you review it before applying
3. Per-artifact opt-in — must be enabled via trust grant with allow_t3_steps: true
When you deploy a T3 recipe, SkillMeat: 1. Invokes the agent to generate a plan 2. Shows you the agent's proposed actions 3. Waits for your confirmation 4. Applies the plan exactly as proposed
Example T3 deployment:
Output:
Agent Plan for chrome-devtools
──────────────────────────────
The agent proposes:
1. Check if Chrome is installed
2. Configure .claude/chrome-launch-profile.yaml
3. Register Chrome DevTools MCP server
Review the plan above. Apply? [y/n]
Platform-Specific Notes¶
macOS:
- T2 scripts run via sandbox-exec (system sandboxing)
- Network access is explicitly allowed per network_allowlist in recipe
- No pre-installation required
Linux:
- T2 scripts run via bubblewrap (requires bubblewrap package installed)
- Install: sudo apt install bubblewrap (Debian/Ubuntu) or sudo dnf install bubblewrap (Fedora)
- Full isolation: filesystem, network, PID namespace
Windows / WSL2: - T2 scripts run in degraded mode (limited isolation) - Network filtering still applies - No sandbox isolation; runs in normal process with resource limits - Consider disabling T2 recipes on Windows via org policy if security is critical
Uninstall / Revert¶
Uninstalling a recipe-equipped artifact restores your project to the state before the recipe was applied.
Uninstall via CLI¶
SkillMeat will: 1. Find the snapshot created when the recipe was applied 2. Restore your project to that snapshot (reversing all changes) 3. Remove the artifact 4. Record the uninstall in the audit log
Example:
Output:
Uninstalling demo-foundry (v1.2.0)...
Restoring snapshot from 2026-05-17T14:32:00Z
Restored: .claude/rules/demo-foundry-rules.md
Removed: .claude/demo-foundry-workspace/
Reverted: .claude/ (anchor merge)
Audit entry: uninstall recorded at 2026-05-17T14:35:12Z
Uninstall via Web UI¶
- Open the Web UI
- Navigate to Artifacts
- Find the artifact and click Uninstall
- Confirm the action
- SkillMeat restores the snapshot and refreshes the artifact list
Dependency Safety¶
SkillMeat prevents uninstalling an artifact if other artifacts depend on it:
skillmeat artifact uninstall demo-foundry
⚠️ Cannot uninstall: dependency detected
- clerk-install (v1.0.0) has apply_after: demo-foundry
- Uninstall clerk-install first, then try again.
Reversibility limits
Recipes are reversible for the operations SkillMeat applies. User edits between recipe anchors are not reverted. For example, if you deploy a recipe that creates .claude/config.md, then manually edit that file, uninstalling the recipe will restore the original file (losing your edits). Always keep backups of important files, or use git to version control your .claude/ directory.
The skillmeat doctor Output¶
skillmeat doctor is a diagnostic command that reports on your recipe environment and sandbox capabilities.
Running the Doctor¶
Output:
SkillMeat Doctor — Environment Report
──────────────────────────────────────
System: macOS 14.5 (arm64)
Recipe Engine:
Status: ✓ Operational
Tier 1 (declarative): ✓ Available
Tier 2 (sandboxed): ✓ Available (macOS sandbox-exec)
Tier 3 (agent): ✗ Disabled (bootstrap_t3_enabled = false)
Audit Log:
Location: ~/.skillmeat/audit/recipes.jsonl
Size: 2.4 MB (18 entries)
Missing Runtimes:
(none)
Recommendations:
[✓] All core features available
Understanding the Doctor Output¶
Recipe Engine Status:
- ✓ Operational — recipes can be deployed
- ⚠ Degraded — some features unavailable (see Missing Runtimes)
- ✗ Not available — recipes cannot be used
Tier availability:
- ✓ Available — tier is supported and ready
- ⚠ Available (with warnings) — supported but limited (e.g., T2 on Windows with reduced isolation)
- ✗ Disabled — tier requires opt-in or is not yet released
Missing Runtimes:
- Lists binaries or libraries you should install for full T2 support
- On Linux: bubblewrap (for full isolation)
- On macOS: included with system
- On Windows: native subprocess (no isolation, but functional)
Installing Missing Runtimes¶
If the doctor reports missing runtimes:
This will attempt to install missing packages via your system package manager:
Troubleshooting¶
Common Failures and Solutions¶
Recipe Apply Fails with "Conflict Detected"¶
Problem: The recipe won't apply because SkillMeat detected a conflict with another artifact.
Solution:
1. Review the conflict message to see which anchor or file is contested
2. Either:
- Uninstall the conflicting artifact first: skillmeat artifact uninstall <other-artifact>
- Ask the artifact authors to use different anchors (e.g., [config-primary] vs. [config-secondary])
- Contact the SkillMeat maintainers if the conflict seems like a platform issue
Sandbox Script Fails with "Permission Denied"¶
Problem: A T2 recipe fails with permission or sandbox errors.
Solution: 1. Check that your system has sandbox support:
2. If T2 is listed as⚠ Available (degraded), the sandbox is limited:
- On Windows: T2 runs with minimal isolation (acceptable for trusted artifacts)
- On Linux without bubblewrap: install it (sudo apt install bubblewrap)
3. Verify the artifact is properly signed or granted trust:
Agent Plan Rejected or Seems Wrong¶
Problem: A T3 recipe generates a plan that looks incorrect or suspicious.
Solution:
1. Do not proceed. Do not approve the plan if it seems wrong.
2. Cancel the deployment (press n at the prompt)
3. Contact the artifact author to clarify what the agent should do
4. Report the issue to the SkillMeat project if the agent is misbehaving
"Artifact has no recipe"¶
Problem: You tried to deploy with --apply-recipe but the artifact has no recipe.
Solution:
- This is expected. The artifact simply doesn't have setup operations.
- You can still deploy it normally: skillmeat deploy <artifact-id> (without the flag)
- No recipe means the artifact is self-contained (e.g., a static skill file)
Audit Log is Missing or Corrupted¶
Problem: The audit log at ~/.skillmeat/audit/recipes.jsonl is empty or has parsing errors.
Solution: 1. Check the file exists:
2. If missing, recipes haven't been deployed yet (this is normal) 3. If corrupted, restore from backup:# Check git history if you version control ~/.skillmeat/
git -C ~/.skillmeat log --oneline -- audit/recipes.jsonl
Related Guides¶
- Deploying Artifacts — Core deployment workflow
- Adding Artifacts to Your Collection — Find and add recipe-equipped artifacts
- Authoring Recipes (Developer Guide) — Artifact authors writing recipes should consult
docs/dev/guides/authoring-recipe-toml.mdin the SkillMeat source tree