Skip to content

Parameterized Artifacts

Parameterized artifacts are skills, agents, commands, hooks, rules, or any other artifact type that declares a parameters: block in their manifest. Instead of being static files copied verbatim, parameterized artifacts are rendered for your specific project context before deployment.

This guide covers the full lifecycle: declaring schemas, binding project values, validating, deploying (dry-run and apply), standalone rendering, and querying SkillBOM records.

1. Overview

The PAL (Parameterized Artifact Lifecycle) pipeline has three stages:

ParameterizedArtifact + ProjectBindings + CLI overrides
        ↓
  MaterializationPlan  (--dry-run)
        ↓
  RenderedFiles + SkillBOM record  (--apply)

Key properties:

  • Parameters are typed (string, integer, boolean, enum, path, secret_ref, etc.)
  • secret_ref parameters are never written into rendered files or SkillBOM records — they are references only
  • Rendering uses strict substitution only: no code execution, no imports, no filesystem/network access
  • Every --apply emits a SkillBOM v0 record for auditability

2. Defining Parameter Schemas (in SKILL.md)

Add a parameters: block to the artifact's SKILL.md (or equivalent manifest):

---
name: demo-foundry
type: skill
version: 1.0.0
parameters:
  - name: project_name
    type: string
    required: true
    description: "Human-readable project name used in headings"
  - name: language
    type: enum
    values: [python, typescript, go]
    default: python
    description: "Primary programming language for the project"
  - name: enable_tests
    type: boolean
    default: true
    description: "Include test scaffold in rendered output"
  - name: api_key_ref
    type: secret_ref
    required: false
    description: "Reference to an API key; never written to files"
---

Supported types:

Type Example values
string "my-project"
integer 42
number 3.14
boolean true, false
enum "python" (from declared values)
path "src/handlers"
secret_ref "env:MY_API_KEY" (reference only, never rendered)

3. Project Bindings (.skillmeat/parameters.toml)

Project bindings supply project-specific parameter values. Create the bindings file with:

skillmeat params init
# or for a specific project root:
skillmeat params init --project /path/to/project

This scaffolds .skillmeat/parameters.toml pre-populated with all required parameters found across your collection artifacts:

[defaults]
# Global defaults applied to all parameterized artifacts
project_name = "my-project"
language = "python"

[overrides.demo-foundry]
# Artifact-specific overrides for demo-foundry
language = "typescript"
enable_tests = false

Resolution precedence (lowest to highest):

  1. Artifact manifest defaults
  2. Project [defaults] block
  3. Artifact-specific [overrides.<name>] block
  4. --set KEY=VALUE CLI flags

4. Validating Parameters

Before deploying, verify all required parameters are resolved and types are correct:

skillmeat params validate demo-foundry

Example output when all parameters are resolved:

Parameter validation: demo-foundry
  ✓ project_name  string   "my-project"  (from: project defaults)
  ✓ language      enum     "typescript"  (from: artifact override)
  ✓ enable_tests  boolean  false         (from: artifact override)
  ✓ api_key_ref   secret_ref  <reference>  (from: manifest default)

All 4 parameters resolved. Ready to deploy.

Example output with unresolved required parameters:

Parameter validation: demo-foundry
  ✗ project_name  string  UNRESOLVED  (required, no default)
  ✓ language      enum    "python"    (from: manifest default)

1 unresolved required parameter. Run `skillmeat params init` or pass --set project_name=<value>.

5. Deploying (Dry-Run and Apply)

Dry-run: preview without writing files

# Preview the materialization plan
skillmeat deploy demo-foundry --dry-run

# Pass parameter overrides at deploy time
skillmeat deploy demo-foundry --dry-run --set project_name=acme --set language=go

# Target a specific adapter profile
skillmeat deploy demo-foundry --dry-run --pal-profile copilot

The dry-run output shows:

  • Files that would be created or updated
  • Managed block regions that would be updated
  • Resolved parameter values (secrets shown as <redacted>)
  • Validation results and warnings
  • A SkillBOM preview

Apply: render and write files

# Apply with interactive confirmation
skillmeat deploy demo-foundry --apply

# Skip confirmation prompt (e.g., in CI)
skillmeat deploy demo-foundry --apply --yes

# Combine overrides with apply
skillmeat deploy demo-foundry --apply --set project_name=acme --yes

# Skip signing enforcement (if not required by policy)
skillmeat deploy demo-foundry --apply --skip-signing

After a successful apply:

  • Rendered files are written to the project's .claude/ directory
  • Shared files (e.g., CLAUDE.md, AGENTS.md) receive managed blocks rather than full overwrites: 
    <!-- skillmeat:begin artifact=demo-foundry materialization=mat_abc123 -->
...rendered content...
<!-- skillmeat:end artifact=demo-foundry -->
  • A SkillBOM v0 materialization record is stored in the local database

6. Standalone Rendering

The render command materializes an artifact to an output directory without creating a deployment record or emitting SkillBOM. Useful for previewing output or integrating with other tooling:

# Render to a temporary directory
skillmeat render demo-foundry --output /tmp/rendered-preview

# Render with parameter overrides
skillmeat render demo-foundry --output ./preview --set project_name=acme

The output directory receives the fully rendered artifact files exactly as they would appear after deploy --apply, without modifying the project or database.

7. SkillBOM Records

Every deploy --apply on a parameterized artifact emits a SkillBOM v0 record. Query records with:

# List all materialization records
skillmeat bom materializations

# Filter by artifact name
skillmeat bom materializations --artifact demo-foundry

# JSON output for scripting
skillmeat bom materializations --output json

Each record includes:

Field Description
source_artifact_id Artifact name and version
source_hash SHA of the source artifact at time of apply
parameter_schema_version Version of the parameter schema used
binding_set_id Identifier for the resolved binding set
resolved_values Parameter values used (secret_ref fields shown as "<redacted>")
target_adapter Adapter used for rendering (e.g., claude_skill, generic_markdown)
output_files List of rendered files and their SHA hashes
signed Whether the source artifact had a valid signature
applied_at ISO-8601 timestamp of the apply

SkillBOM records are stored locally in the SkillMeat cache database and are queryable at any time after deployment.