Frontmatter schema

Concise field-by-field schema for ARTIFACT.md, SKILL.md (for skills), and DOMAIN.md.

This page is a concise reference. For prose-style explanations of when to use each field, see Authoring → Frontmatter reference and Authoring → Domains.

Manifest files

Every artifact directory contains an ARTIFACT.md. Skill artifacts (type: skill) additionally contain a SKILL.md to comply with the agentskills.io standard. Field allocation across the two files for skills is summarized in the SKILL.md section below; ARTIFACT.md for non-skills carries every field listed below.

ARTIFACT.md

Universal fields

Field	Type	Required	Description	For skills
`type`	enum	yes	`skill`, `agent`, `context`, `command`, `rule`, `hook`, `mcp-server`, or extension type.	In `ARTIFACT.md`
`name`	string	yes	Short identifier. For skills, must match the parent directory name (per agentskills.io).	In `SKILL.md`
`version`	semver	yes	Author-chosen semver. Once `(artifact_id, version)` is ingested, it's bit-for-bit immutable.	In `ARTIFACT.md`
`description`	string	yes	"When should I use this?" ≤ 1024 chars for skills.	In `SKILL.md`
`when_to_use`	list of strings	no	Explicit situations the artifact applies to.	In `ARTIFACT.md`
`tags`	list of strings	no	Filter target for `search_artifacts`.	In `ARTIFACT.md`
`sensitivity`	enum	no	`low` (default), `medium`, `high`.	In `ARTIFACT.md`
`license`	string	no	SPDX identifier.	In `SKILL.md`
`search_visibility`	enum	no	`indexed` (default) or `direct-only`.	In `ARTIFACT.md`
`deprecated`	bool	no	When `true`, `load_artifact` returns a deprecation warning.	In `ARTIFACT.md`
`replaced_by`	string	no	Suggested upgrade target (canonical artifact ID).	In `ARTIFACT.md`
`release_notes`	string	no	Free text.	In `ARTIFACT.md`
`audit_redact`	list of strings	no	Frontmatter field names whose values the registry replaces with `[redacted]` in audit log entries referencing this artifact.	In `ARTIFACT.md`
`lint_suppress`	list of strings	no	Lint rule codes to silence for this artifact. Only advisory rules honor the list.	In `ARTIFACT.md`
`source`	string	no	Document-level provenance of the prose body. `authored` is the documented value; any other value marks the body's default trust region as untrusted. Inline `<!-- begin imported ... -->` blocks override it per region.	In `ARTIFACT.md`

Caller-interpreted fields

Field	Type	Description
`mcpServers`	list of objects	MCP servers the artifact wants registered when loaded.
`requiresApproval`	list of objects	Tools that require user approval before execution.
`runtime_requirements`	map	Runtime versions and system packages bundled scripts depend on.
`sandbox_profile`	enum	`unrestricted` (default), `read-only-fs`, `network-isolated`, `seccomp-strict`.
`effort_hint`	enum	`low`, `medium`, `high`, `max`. Advisory.
`model_class_hint`	enum	`nano`, `small`, `medium`, `large`, `frontier`. Advisory.
`sbom`	object	Author-supplied SBOM hint (e.g. `{format: cyclonedx-1.5, ref: ./sbom.json}`). Stored verbatim and exposed on `load_artifact`; Podium does not parse, validate, or scan it. Vulnerability scanning is a CI/CD concern.

Type-specific fields

Field	Applies to	Description
`input`	`agent`	Reference to the agent's input JSON Schema document, written as `{ $ref: ./schemas/input.json }`. A bare path scalar also parses.
`output`	`agent`	Reference to the agent's output JSON Schema document, in the same form as `input`.
`delegates_to`	`agent`	List of artifact IDs this agent delegates to. Advisory; ingest records the edges and does not constrain the target's type.
`rule_mode`	`rule`	`always` (default), `glob`, `auto`, `explicit`.
`rule_globs`	`rule`	Required when `rule_mode: glob`. Comma-separated glob patterns.
`rule_description`	`rule`	Required when `rule_mode: auto`. Drives the harness's autoload heuristic.
`hook_event`	`hook`	Canonical lifecycle event name. Session: `session_start`, `session_end`. Prompt: `user_prompt_submit`. Generic tool: `pre_tool_use`, `post_tool_use`, `post_tool_use_failure`. Tool subtypes: `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`. The adapter translates to the harness's native event; coverage varies.
`hook_action`	`hook`	Shell snippet executed when the event fires.
`server_identifier`	`mcp-server`	Canonical server identifier. Drives the reverse index: any artifact whose `mcpServers:` entry resolves to this identifier gets a dependency edge to the registration, regardless of the referencing artifact's type.

Cross-cutting fields

Field	Type	Description
`extends`	string	Inherit and refine another artifact's manifest. Single scalar (no multiple inheritance). Pin syntax: `<id>`, `<id>@<semver>`, `<id>@<semver>.x`, `<id>@sha256:<hash>`.
`target_harnesses`	list of strings	Opt out of cross-harness materialization. Set to a list of harness names; the artifact only materializes for harnesses on the list.
`external_resources`	list of objects	External resources (URL + sha256 + size + signature) too large to bundle.

External resources object schema

yaml

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

Provenance markers (in prose body)

<authored prose>

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

For skills, the prose body lives in SKILL.md; for non-skills, it lives in ARTIFACT.md.

SKILL.md (for type: skill)

A SKILL.md carries the agentskills.io standard's frontmatter and the agent-facing prose body. For skills, the ARTIFACT.md body is empty (a one-line HTML comment pointer is allowed).

Top-level fields (per agentskills.io)

Field	Type	Required	Description
`name`	string	yes	1–64 chars, lowercase Unicode alphanumeric and hyphens, no leading/trailing/consecutive hyphens, must match the parent directory name.
`description`	string	yes	1–1024 chars. Describes what the skill does and when to use it.
`license`	string	no	License name or reference to a bundled license file.
`compatibility`	string	no	≤ 500 chars. Free-form environment notes. When it is omitted, the Claude Code adapter derives a string from `runtime_requirements` and `sandbox_profile` at materialization time; the other adapters copy `SKILL.md` unchanged and leave the field absent.
`metadata`	map (string → string)	no	Open-ended map for client-specific extension.
`allowed-tools`	list of strings	no	Experimental. Pre-approved tools, one per entry. A scalar fails to parse.

Body

Markdown after the frontmatter. The agentskills.io spec recommends ≤ 5K tokens and ≤ 500 lines, with longer reference content factored into references/.

Lint rules

Lint enforces (errors unless noted):

Both SKILL.md and ARTIFACT.md exist for type: skill.
SKILL.md name matches the parent directory.
SKILL.md name syntax follows the agentskills.io constraints.
SKILL.md description is non-empty. The ≤ 1024-char cap is checked by the skills-ref validate rule below and reported as a warning.
SKILL.md does not contain Podium-only fields (type, version, when_to_use, etc.).
ARTIFACT.md does not contain name, description, or license (warning); when present, values must match SKILL.md exactly (error on mismatch).
ARTIFACT.md body is empty or a single HTML comment (warning).
skills-ref validate passes against SKILL.md (warning; suppression flag available).

DOMAIN.md

Top-level fields

Field	Type	Description
`unlisted`	bool	When `true`, removes this folder and its subtree from `load_domain` enumeration. Default `false`.
`description`	string	One-line summary used wherever the domain appears as a child or sibling in another `load_domain` response.
`discovery`	object	Per-domain overrides of discovery rendering rules. See below.
`include`	list of glob patterns or artifact IDs	Imports artifacts from elsewhere into this domain.
`exclude`	list of glob patterns	Applied after `include`. Removes paths.

The prose body below the frontmatter is long-form context returned by load_domain only when this domain is the requested path.

`discovery` block

Field	Type	Description
`max_depth`	int (≥1)	Cap on the depth of the rendered subtree below the requested path.
`fold_below_artifacts`	int (≥0)	A subdomain whose visible artifact count (recursive) is below this threshold collapses into its parent's leaf set.
`fold_passthrough_chains`	bool	Collapse single-child intermediate domains into the deepest non-passthrough ancestor.
`notable_count`	int (≥0)	Cap on the notable list per domain in `load_domain` output.
`target_response_tokens`	int	Soft budget per `load_domain` response.
`featured`	list of canonical artifact IDs	Surfaced first in the notable list.
`deprioritize`	list of glob patterns	Children matching are ranked last and excluded from "notable" unless space permits.
`keywords`	list of strings	Author-curated terms agents should associate with this domain. Per-domain only; no tenant default.

Tenant-level defaults for max_depth, fold_below_artifacts, fold_passthrough_chains, notable_count, target_response_tokens live in registry.yaml. Per-domain overrides apply to the subtree rooted at the DOMAIN.md. A tenant-level discovery.allow_per_domain_overrides: false disables per-domain overrides registry-wide.

Glob syntax

Syntax	Matches
`*`	One path segment.
`**`	Recursive (any number of segments).
`{a,b,c}`	Brace alternation.

A bare canonical artifact ID matches that artifact exactly.

Cross-layer merge

When two layers contribute artifacts with the same canonical ID and the higher-precedence one declares extends:, fields merge per the table below.

Field	Merge
`description`, `name`, `release_notes`	Scalar; child wins.
`tags`	List; append unique.
`when_to_use`	List; append.
`sensitivity`	Scalar; most-restrictive (high > medium > low).
`mcpServers`	List of objects; deep-merge by `name`.
`requiresApproval`	List; append.
`runtime_requirements`	Map; deep-merge with child wins.
`sandbox_profile`	Scalar; most-restrictive.
`delegates_to`	List; append.
`external_resources`	List; append.
`license`	Scalar; child wins (lint warning if changed across layers).
`search_visibility`	Scalar; most-restrictive (`direct-only` > `indexed`).

If a child omits a frontmatter field, 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 a field absent from the table takes the child's value. version is independent, so the child keeps its own, and type must match on both sides because ingest rejects an extends: chain that crosses types.

Extension types register their own merge semantics via TypeProvider.

When two layers contribute a DOMAIN.md for the same path:

Field	Merge
`description` and prose body	Last-layer-wins.
`include`	Additive across layers.
`exclude`	Additive across layers; applied after the merged include set.
`unlisted`	Most-restrictive-wins.
`discovery.max_depth`, `discovery.notable_count`, `discovery.target_response_tokens`	Most-restrictive-wins (lowest value).
`discovery.fold_below_artifacts`	Most-restrictive-wins (highest value).
`discovery.fold_passthrough_chains`	Most-restrictive-wins (`true` over `false`).
`discovery.featured`, `discovery.deprioritize`, `discovery.keywords`	Append-unique.