Part V — File Formats and Protocols

This part covers Chapters 21–24: the SKILL.md format, data and backup, file naming conventions, and the settings-export format.

21. Skill (SKILL.md) format

[!ref] Full details in the User Manual, "The Skill system".

21.1 File structure

<skill-root>/
├── SKILL.md              # required; frontmatter + body
├── README.md             # optional; human-facing
├── examples/             # optional; example input/output
└── …                     # optional resources

21.2 Frontmatter fields

The top of SKILL.md is a YAML frontmatter block delimited by ---. Recognised fields:

Field	Type	Required	Description
`name`	string	✓	Slash name (lowercase hyphenated recommended)
`description`	string	✓	One-line description; listed in `/help`
`argument-hint`	string		`<arg1> <arg2>` hint
`allowed-tools`	array		Allow-list of tools for this skill
`denied-tools`	array		Deny-list (mutually exclusive with allow-list)
`work-modes`	array		Applicable modes `[plan, execute, …]`
`model`	string		Force a specific model; otherwise inherit
`temperature`	number		Force temperature; otherwise inherit
`version`	string		Semantic version
`license`	string		SPDX identifier
`author`	string		Author / team
`tags`	array		Marketplace filtering
`signature`	string		GM signature block (signing tool writes this)

21.3 Body template

Body is standard Markdown with extensions:

Syntax	Meaning
`$1` `$2` `$N`	Nth positional argument
`$ARGUMENTS`	All args joined verbatim
!`<shell>`	Shell preprocess; the output substitutes here
`{{include:path}}`	Inline another Markdown file (relative to skill-root)

21.4 Three-layer priority

Layer	Path	Priority
Global	Global skills directory	Lowest
Workspace	`<workspace>/.config/skills/<name>/`	Middle
Plugin	Bundled with a plugin pack	Highest

21.5 Invocation

Method	Trigger	Behaviour
User slash	`/<name> <args>`	Render and inject into the next system prompt
Assistant active	`skill.invoke` tool	Render and return as a tool response in the stream

21.6 Built-in skills

Built-in skills (e.g. skill-creator) are materialized on startup, with content drift auto-overwritten.
Build-time signing + a built-in signature anchor (trust ExtraSignerRoots) let them pass even under a strict signing policy.
The Settings → Skills panel marks built-in vs. user vs. third-party with a "Built-in" badge.
Compatible with Agent Skills (agentskills.io): cross-client discovery / parsing tolerance + tool-name translation mapping.

21.7 `market.check` (publishing-contract validation)

A built-in read-only, deterministic, offline tool that validates a local skill / plugin directory against the zMarket publishing contract:

Param	Type	Default	Notes
`path`	string	—	required, target directory relative path (e.g. `.avlcode/skills/my-skill`)
`kind`	string	auto-detect	`skill` / `plugin` / `mcp` / `provider`
`version`	string	inferred	override / supply strict semver
`source`	string	`./<name>`	override source form
`manifest`	string	derived	supply the manifest JSON directly

Reports pass / fail + reasons + what's missing (name slug, strict semver, source form, capability declaration, archive safety, etc.). No network, no submission. Note: a .skill-sign signature ≠ zMarket acceptance; it only checks the publishing-contract shape, not a runtime security audit.