Authoring SKILL.md

This is a featured battery

The format is portable. The lifecycle is deliberately not hidden inside the markdown.

A skill's SKILL.md is a manifest plus operational body:

---
name: reports
description: Generate and audit reports
license: Apache-2.0
compatibility: Requires Python 3.14+
metadata:
  team: finance
allowed-tools: []
---

Treat report inputs as untrusted. Validate before exporting.

parseSkillMd(text) returns the frontmatter mapping and the body after the closing delimiter. It requires string name and description; malformed YAML throws E_SKILL_MANIFEST_INVALID. Unknown frontmatter keys are not carried forward.

The helper is for source authors. The manager's load path does not parse markdown. descriptor(ref) is the authority for the live descriptor, tools, channel, trust tier, scripts, isolated tools, and compatibility passthrough; read(ref) with no path is the body. This avoids two parsers disagreeing about what a loaded skill means.

agentskills.io compatibility

The battery carries license, metadata, and free-text compatibility through discovery and descriptors. It surfaces them for routing and audit but does not interpret compatibility prose. It deliberately ignores allowed-tools: a skill declaring its own permissions is not a permission boundary. The mandatory gate, wrapper, sandbox policy, and deployer configuration are the boundary.

The standard's lifecycle vocabulary is Discovery → Activation → Execution. ADK keeps that format compatibility while adding explicit deactivation with unload_skill; format portability does not require surrendering lifecycle control.

A filesystem name-matches-directory rule is not enforced because SkillSource need not have directories. descriptor.id === ref.id is the identity check that applies to every source.