Frontmatter reference

Podium artifact frontmatter is YAML between two --- lines at the top of a manifest file. Manifest files:

• ARTIFACT.md — present in every artifact directory. Carries Podium's canonical schema (universal, caller-interpreted, and type-specific fields). For non-skill types, the prose body below the frontmatter is what the agent reads at load time.
• SKILL.md — present additionally in skill directories (type: skill). Carries the agentskills.io standard's frontmatter (name, description, plus optional license, compatibility, metadata, allowed-tools). Its prose body is what the agent reads at load time. For skills, ARTIFACT.md's body is empty.

Field groups:

• Universal fields apply to every artifact regardless of type.
• Caller-interpreted fields are stored verbatim and read by the host (harness adapter, runtime, etc.) at delivery time.
• Type-specific fields apply to certain types only.

File allocation for skills

Skills split their frontmatter between SKILL.md and ARTIFACT.md so that SKILL.md stays strictly within the agentskills.io specification. The split is mechanical:

For non-skill types (agent, context, command, rule, hook, mcp-server, extension types), ARTIFACT.md carries every field. There is no SKILL.md.

The name field carries the agentskills.io syntax constraints:

• 1–64 characters.
• Lowercase Unicode alphanumeric (a-z, 0-9) and hyphens.
• No leading or trailing hyphen.
• No consecutive hyphens.

Lint applies these constraints to any name: an artifact declares, whatever its type. The further agentskills.io requirement that name match the parent directory name is checked for skills, against SKILL.md.

Universal fields

These apply to every artifact. The "where it lives" column above governs which file holds each field for skills.

# In SKILL.md (for skills) or ARTIFACT.md (for non-skills):
name: run-variance-analysis
description: Flag unusual variance vs. forecast after month-end close. Use after the close period when reviewing financial performance.
license: MIT                       # SPDX identifier

# In ARTIFACT.md (every type):
type: skill | agent | context | command | rule | hook | mcp-server | <extension type>
version: 1.0.0                     # semver, author-chosen
when_to_use:
  - "After month-end close, to flag unusual variance vs. forecast"
tags: [finance, close, variance]
sensitivity: low | medium | high   # public mode rejects ingest above a floor
search_visibility: indexed | direct-only   # default: indexed
deprecated: false                  # set to true to mark this version deprecated
replaced_by: finance/close-reporting/run-variance-analysis-v2
release_notes: "Initial release."
audit_redact: [bank_account, ssn]  # frontmatter field names to mask in audit log entries
lint_suppress: [lint.skill_ref_validate]   # advisory lint rule codes to silence for this artifact

SKILL.md-only fields (skills)

These fields appear only in SKILL.md and only for skills. They come from the agentskills.io specification.

---
name: run-variance-analysis
description: Flag unusual variance vs. forecast after month-end close. Use after the close period when reviewing financial performance.
license: MIT
compatibility: Requires Python 3.10+ and pandas. Designed for Claude Code or similar.
metadata:
  author: example-org
allowed-tools:
  - Bash(python:*)
  - Read
---

Caller-interpreted fields

These fields live in ARTIFACT.md. They are stored verbatim and consumed by the host (harness adapter, runtime, etc.) at delivery time. Podium itself doesn't enforce them; the host decides whether and how to honor them.

mcpServers:
  - name: finance-warehouse
    transport: stdio
    command: npx
    args: ["-y", "@company/finance-warehouse-mcp"]

requiresApproval:
  - tool: payment-submit
    reason: irreversible

runtime_requirements:
  python: ">=3.10"
  node: ">=20"
  system_packages: []

sandbox_profile: unrestricted | read-only-fs | network-isolated | seccomp-strict

effort_hint: low | medium | high | max
model_class_hint: nano | small | medium | large | frontier

sbom:                              # author-supplied passthrough
  format: cyclonedx-1.5            # informational
  ref: ./sbom.json                 # consumers fetch the SBOM via the bundled-resource path

Type-specific fields

These fields live in ARTIFACT.md and apply to specific types only.

# For type: agent — declared input/output schemas
input: { $ref: ./schemas/input.json }
output: { $ref: ./schemas/output.json }

# For type: agent — well-known delegation targets (advisory)
delegates_to:
  - finance/procurement/vendor-compliance-check@1.x

# For type: rule — controls when the harness loads this rule
rule_mode: always | glob | auto | explicit   # default: always
rule_globs: "src/**/*.ts,src/**/*.tsx"        # required when rule_mode: glob
rule_description: "Apply when working with database migrations"  # required when rule_mode: auto

# For type: hook — lifecycle observer
# `hook_event` is one of the canonical event names; the adapter translates to the harness's native event.
# Session: session_start, session_end.
# Prompt: user_prompt_submit.
# Tool (generic): pre_tool_use, post_tool_use, post_tool_use_failure.
# Tool (subtype): pre_shell_execution, post_shell_execution, pre_mcp_execution, post_mcp_execution,
#                 pre_read_file, post_file_edit.
# Permission: permission_request, permission_denied.
# Subagent: subagent_start, subagent_stop.
# Turn: stop.
# Compaction: pre_compact, post_compact.
# Notification: notification.
# See [Hooks](hooks) for descriptions and the per-event coverage caveat.
hook_event: stop
hook_action: |                    # shell snippet executed when the event fires
  echo "[hook] $hook_event triggered"

# For type: mcp-server — canonical server identifier (drives reverse index)
server_identifier: npx:@company/finance-warehouse-mcp

# Inheritance: explicitly extend another artifact's manifest (cross-layer merge)
extends: finance/ap/pay-invoice@1.2.x

# Adapter targeting: opt out of cross-harness materialization for this artifact
target_harnesses: [claude-code, opencode]

External resources

For artifacts that ship bytes too large to bundle (the per-package soft cap is 10 MB), reference pre-uploaded objects in ARTIFACT.md:

external_resources:
  - path: ./model.onnx
    url: s3://company-models/variance/v1/model.onnx
    sha256: 9f2c...
    size: 145000000
    signature: "sigstore:..."

The registry stores the URL, hash, size, and signature; bytes don't transit the registry. See Bundled resources for the full bundled-vs-external decision.

Provenance markers

An artifact declares the provenance of its prose so the host can apply differential trust. Two markers carry it.

The source: frontmatter field sets the document-level default. It lives in ARTIFACT.md for every type, skills included, and adapters read it from there:

---
type: context
version: 1.0.0
source: authored
---

authored (and an omitted field) leaves the prose trusted. Any other value, imported for example, marks the whole body untrusted.

Inline markers in the prose body (SKILL.md for skills, ARTIFACT.md for non-skills) mark one region and override the document-level default for that region:

<authored prose>

<!-- begin imported source="https://wiki.example.com/policy/payments" -->
<imported text>
<!-- end imported -->

Adapters propagate provenance markers to harnesses that support trust regions (Claude's <untrusted-data> convention, etc.). Hosts can apply differential trust, treating imported content as data rather than as instruction. This is the primary defense against prompt injection from manifests that aggregate external content.

Cross-layer merge

When two layers contribute artifacts with the same canonical ID, the higher-precedence one can declare extends: to inherit and refine the lower one. Field merge semantics:

If a child omits a field of its ARTIFACT.md frontmatter, or sets an empty scalar, the parent's value is inherited unchanged. This holds for every frontmatter field, including the fields in the table above. When both the parent and the child declare a value, a field in the table merges per its row, and every field outside the table takes the child's value. The child's type: must match the parent's, and the child's version: is independent of the parent's.

For skills, the merge applies to the ARTIFACT.md frontmatter alone. The registry serves the child's SKILL.md verbatim, so name, description, license, and the other agentskills.io fields come from the child's SKILL.md and are not inherited from the parent's, whether or not the child's SKILL.md declares them.

See Extends for examples and gotchas.

Where to learn more

• Artifact types explains what each type: is for.
• Domains covers DOMAIN.md, the file that organizes artifacts in a folder hierarchy.
• Bundled resources covers the layout and size caps for files alongside ARTIFACT.md and SKILL.md.