Add Agent Zero-native skill adapter format #14

New issue

Open

opened 2026-08-22 06:48:52 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-22 06:48:52 +00:00

(Migrated from github.com)

Context

The repository already supports the Agent Zero deployment path (usr/skills/<skill-id>/) through lib.adapters.agent-zero and lib.mkAgentZeroHomeManagerModule.

That is not yet an Agent Zero-native format adapter. Current Agent Zero documentation uses the shared SKILL.md base but also supports discovery metadata such as tags and trigger fields, and provides its own validator/CLI. Agent Zero matches skills using name/description/tags.

Keep the canonical skill source platform-neutral. Do not hand-maintain a second Agent Zero copy.

Parent: #11
Backlog: #13

Required design

Define a generated Agent Zero view derived from each canonical skills/<skill-id>/ package.

Canonical source remains:

skills/<skill-id>/SKILL.md
scripts/      # optional
references/   # optional
assets/       # optional

Agent Zero view installs under:

<agent-zero-root>/usr/skills/<skill-id>/

The adapter may add Agent Zero-specific discovery metadata, but must not fork the instruction body.

Metadata policy

Preserve the repository's canonical selection convention:

canonical description: 2–8 comma-separated keywords;
no prose inflation in canonical frontmatter;
no duplicated durable SKILL.md body.

For Agent Zero, derive richer discovery fields from explicit adapter metadata rather than making the canonical description verbose. Candidate adapter fields:

tags
triggers / current upstream trigger field spelling
optional version/license metadata only when the canonical package owns those values

Do not invent trigger phrases from the body at install time. Adapter metadata must be deterministic and reviewable.

Research/validation gate

Before implementation:

verify the exact current Agent Zero frontmatter field names against upstream agent0ai/agent-zero;
verify whether unknown top-level fields remain acceptable to the generic Agent Skills validator;
decide whether the generated Agent Zero view needs a transformed SKILL.md or an Agent Zero-side metadata companion supported by upstream;
use Agent Zero's own skill validation path in CI when practical;
confirm scripts/references/assets survive unchanged.

Flake/API shape

Expose Agent Zero as a first-class format, not merely a target root. The design should make it possible to obtain:

canonical generic package;
Agent Zero-formatted package/view;
install-root-aware Home Manager deployment.

Exact attribute names should follow the existing flake naming style rather than creating a parallel API hierarchy.

Acceptance

Agent Zero is represented as a real generated format adapter;
canonical skills remain single-source;
keyword-only canonical descriptions remain intact;
Agent Zero discovery metadata is deterministic and validated;
support files are preserved;
no Agent Zero installation root is guessed;
docs distinguish format from deployment path so this ambiguity does not return wearing a fake mustache.

## Context The repository already supports the Agent Zero deployment **path** (`usr/skills/<skill-id>/`) through `lib.adapters.agent-zero` and `lib.mkAgentZeroHomeManagerModule`. That is not yet an Agent Zero-native **format adapter**. Current Agent Zero documentation uses the shared `SKILL.md` base but also supports discovery metadata such as `tags` and trigger fields, and provides its own validator/CLI. Agent Zero matches skills using name/description/tags. Keep the canonical skill source platform-neutral. Do not hand-maintain a second Agent Zero copy. Parent: #11 Backlog: #13 ## Required design Define a generated Agent Zero view derived from each canonical `skills/<skill-id>/` package. Canonical source remains: ```text skills/<skill-id>/SKILL.md scripts/ # optional references/ # optional assets/ # optional ``` Agent Zero view installs under: ```text <agent-zero-root>/usr/skills/<skill-id>/ ``` The adapter may add Agent Zero-specific discovery metadata, but must not fork the instruction body. ## Metadata policy Preserve the repository's canonical selection convention: - canonical `description`: 2–8 comma-separated keywords; - no prose inflation in canonical frontmatter; - no duplicated durable `SKILL.md` body. For Agent Zero, derive richer discovery fields from explicit adapter metadata rather than making the canonical description verbose. Candidate adapter fields: - `tags` - `triggers` / current upstream trigger field spelling - optional version/license metadata only when the canonical package owns those values Do not invent trigger phrases from the body at install time. Adapter metadata must be deterministic and reviewable. ## Research/validation gate Before implementation: 1. verify the exact current Agent Zero frontmatter field names against upstream `agent0ai/agent-zero`; 2. verify whether unknown top-level fields remain acceptable to the generic Agent Skills validator; 3. decide whether the generated Agent Zero view needs a transformed `SKILL.md` or an Agent Zero-side metadata companion supported by upstream; 4. use Agent Zero's own skill validation path in CI when practical; 5. confirm scripts/references/assets survive unchanged. ## Flake/API shape Expose Agent Zero as a first-class format, not merely a target root. The design should make it possible to obtain: - canonical generic package; - Agent Zero-formatted package/view; - install-root-aware Home Manager deployment. Exact attribute names should follow the existing flake naming style rather than creating a parallel API hierarchy. ## Acceptance - Agent Zero is represented as a real generated format adapter; - canonical skills remain single-source; - keyword-only canonical descriptions remain intact; - Agent Zero discovery metadata is deterministic and validated; - support files are preserved; - no Agent Zero installation root is guessed; - docs distinguish `format` from `deployment path` so this ambiguity does not return wearing a fake mustache.

lost-rob0t commented

2026-08-22 06:50:18 +00:00

(Migrated from github.com)

Upstream verification — 2026-08-22

Checked current agent0ai/agent-zero runtime rather than relying only on prose docs.

Confirmed:

global skill roots include both bundled skills/ and user usr/skills/;
the parser accepts triggers, trigger_patterns, trigger, or activation as trigger aliases;
it accepts tags / tag;
it accepts allowed-tools, allowed_tools, or tools;
version, author, license, compatibility, and metadata are also parsed;
search scores exact trigger matches above description/tag matches, so native trigger metadata is materially useful rather than decorative;
Agent Zero validation currently enforces Agent Skills-compatible name rules, nonempty/<=1024 description, and <=500 compatibility, but does not require tags/triggers.

Design implication: use canonical generic SKILL.md as the source body, keep terse canonical descriptions, and generate an Agent Zero view that adds deterministic tags + triggers. Prefer canonical spelling triggers; runtime compatibility with trigger_patterns exists but does not need to become our emitted spelling.

Still verify the generic skills-ref validator's behavior for extra top-level Agent Zero keys before choosing whether generated A0 metadata can live directly in an otherwise generic file or must exist only in the transformed Agent Zero view.

## Upstream verification — 2026-08-22 Checked current `agent0ai/agent-zero` runtime rather than relying only on prose docs. Confirmed: - global skill roots include both bundled `skills/` and user `usr/skills/`; - the parser accepts `triggers`, `trigger_patterns`, `trigger`, or `activation` as trigger aliases; - it accepts `tags` / `tag`; - it accepts `allowed-tools`, `allowed_tools`, or `tools`; - `version`, `author`, `license`, `compatibility`, and `metadata` are also parsed; - search scores exact trigger matches above description/tag matches, so native trigger metadata is materially useful rather than decorative; - Agent Zero validation currently enforces Agent Skills-compatible name rules, nonempty/<=1024 description, and <=500 compatibility, but does not require tags/triggers. Design implication: use canonical generic SKILL.md as the source body, keep terse canonical descriptions, and generate an Agent Zero view that adds deterministic `tags` + `triggers`. Prefer canonical spelling `triggers`; runtime compatibility with `trigger_patterns` exists but does not need to become our emitted spelling. Still verify the generic `skills-ref` validator's behavior for extra top-level Agent Zero keys before choosing whether generated A0 metadata can live directly in an otherwise generic file or must exist only in the transformed Agent Zero view.