T-GLK0-spec-fields-and-skills-ref-oracle

State: planning/proposed · Impact: high · Complexity: medium

Goal

solutions/agent-pants/docs/vault/research/agent-skills-conformance.md found ten gaps against the Agent Skills spec. Five are already closed in code (the portable dialect, the space-separated allowed-tools, metadata nesting, the corrected module doc) since the audit was written; three of the spec’s six frontmatter fields — license, compatibility, metadata — still have no home on either skill model, and nothing anywhere runs the reference validator against what we emit. This task closes both remaining gaps and reconciles the vault’s own task notes with what has actually shipped.

Today

Location	Role today
solutions/agent-pants/crates/agent-adapt-core/src/content.rs#SkillContent	Carries name, description, argument_hint, argument_names, body, allowed_tools, model_override, context_mode, user_invocable, disable_model_invocation, tags, annotations; no license, compatibility, or metadata field
packages/rust/agent-adapt/src/model/skill.rs#Skill	Same gap: annotations is the only place an unmodelled key rides through
packages/rust/agent-adapt/src/render/skill_md.rs	render_skill_md emits allowed-tools as a space-separated scalar (G1 closed), folds annotations under metadata (G3 closed); module doc already states the six-field contract correctly (G9 closed)
packages/rust/agent-adapt/src/render/frontmatter.rs#FrontmatterBuilder	raw_entry emits nested values under a named key (used for metadata); list still emits a YAML block sequence, used for arguments, not allowed-tools
packages/rust/agent-adapt/src/runtime.rs	AGENT_SKILLS_FIELDS names the six spec keys explicitly, noting only three are modelled; CLAUDE_CODE_EXTENSION_FIELDS lists the six Claude-only keys; every non-Claude-Code FrontmatterDialect.omit_fields lists them (G2, G5 closed)
packages/rust/agent-adapt/src/runtimes/portable.rs	The portable (Agent Skills-only) runtime exists and renders the spec’s six-field frontmatter with no extension keys
packages/rust/agent-adapt/tests/portable_vs_claude_code_dialect.rs	Asserts the portable render drops exactly CLAUDE_CODE_EXTENSION_FIELDS and that its keys are inside name/description/allowed-tools; nothing here runs an external validator
solutions/determined/crates/determined-core/src/wire/mod.rs#AgentSkillNoteFields	No license, compatibility, or metadata field; ap_license is a separate ap--namespaced key, not the spec’s license:
solutions/determined/experiences/agent-pants/app/utils/fieldSpec.ts	FIELD_SPECS has no entries for license, compatibility, or metadata
solutions/agent-pants/docs/vault/tasks/conform-skill-frontmatter.md	Says “Implemented on PR #1248, open against main and unmerged”; the fix shipped in bb00c3283 (portable dialect) and is not stated as merged
solutions/agent-pants/docs/vault/tasks/model-spec-optional-fields.md	Still status: open; matches today’s real gap (G4, G7 partial)
solutions/agent-pants/docs/vault/tasks/validate-against-skills-ref.md	Still status: open; matches today’s real gap (G10) — no validator test exists anywhere in the repo

Proposed

Skill and SkillContent both gain license: Option<String>, compatibility: Option<String> (refused over 500 chars, the same pattern description’s 1024 cap already uses in discover.rs), and metadata: BTreeMap<String, String>. Reading a note with these frontmatter keys and publishing it emits them once each as modelled fields, never duplicated into annotations. AgentSkillNoteFields and fieldSpec.ts#FIELD_SPECS expose all three. A Rust integration test renders the fixture corpus’s skills to every target and runs skills-ref validate (or the agentskills CLI, per the research’s correction of the package name) over each output tree, skipped with a named install command when the tool is absent, asserting every target except claude-code is conformant. The three vault notes are rewritten in place to describe the shipped state — conform-skill-frontmatter.md and its G1/G2/G3/G9 close as done, model-spec-optional-fields.md closes with this task, validate-against-skills-ref.md closes with this task’s test — never marked “superseded”.

Approach

1. Add license: Option<String>, compatibility: Option<String>, metadata: BTreeMap<String, String> to Skill (model/skill.rs) and SkillContent (content.rs); a value already present in a note’s frontmatter for these keys is read into the new field rather than into annotations.
2. Update render_skill_md to emit license and compatibility as scalars and merge the new metadata field into the same metadata: block annotations already folds into, so both sources land in one map rather than two competing keys.
3. Add a compatibility length refusal (500 chars) alongside the existing description 1024 refusal in discover.rs, naming the field and the overrun the same way.
4. Add license, compatibility, ap_metadata (the wire’s ap- prefix stays reserved per AgentSkillNoteFields’s own doc, so the spec’s metadata key needs its own wire field) to AgentSkillNoteFields, and three rows to fieldSpec.ts#FIELD_SPECS.
5. Write the validator integration test: render a minimal skill, a maximal skill, one with unknown vault frontmatter, and one with peer resources and a rewritten reference link, to every RuntimeId; shell out to the installed validator (agentskills validate, per the research’s correction) over each rendered tree; assert every target VALID except claude-code, asserted invalid on exactly its six extension keys; skip with an install-command message when the binary is absent.
6. Rewrite conform-skill-frontmatter.md in place: its Summary states the fix shipped in bb00c3283, not “open against main”; check off its acceptance criteria against the current skill_md.rs.
7. Rewrite model-spec-optional-fields.md and validate-against-skills-ref.md in place to status: closed once steps 1-5 land, citing this task.

Areas

Area	Note
packages/rust/agent-adapt/src/model/skill.rs	Add license, compatibility, metadata fields
solutions/agent-pants/crates/agent-adapt-core/src/content.rs	Add license, compatibility, metadata fields to SkillContent
packages/rust/agent-adapt/src/render/skill_md.rs	Emit license, compatibility scalars; merge metadata field into the annotations-derived map
solutions/agent-pants/crates/agent-adapt-core/src/discover.rs	500-char compatibility refusal beside the existing description cap
solutions/determined/crates/determined-core/src/wire/mod.rs	license, compatibility, ap_metadata on AgentSkillNoteFields
solutions/determined/experiences/agent-pants/app/utils/fieldSpec.ts	license, compatibility, metadata field specs
packages/rust/agent-adapt/tests/validate_against_skills_ref.rs	Renders the fixture corpus per target and runs the reference validator over each tree
solutions/agent-pants/docs/vault/tasks/conform-skill-frontmatter.md	Rewritten to the shipped state; PR reference corrected
solutions/agent-pants/docs/vault/tasks/model-spec-optional-fields.md	Closed once fields land
solutions/agent-pants/docs/vault/tasks/validate-against-skills-ref.md	Closed once the validator test lands

Acceptance criteria

• AC-1: Skill and SkillContent both carry license, compatibility, and metadata fields, and a round trip (read a note with all three set, publish it) emits each exactly once.
• AC-2: compatibility over 500 characters is refused, naming the field and the overrun, the same shape as the existing description refusal.
• AC-3: A new Rust test renders the fixture corpus to every RuntimeId and runs the reference validator over each output tree, passing on every target except claude-code (asserted invalid on exactly its six extension keys); the test skips with a named install command when the validator binary is absent, never a silent pass.
• AC-4: fieldSpec.ts#FIELD_SPECS lists license, compatibility, and metadata with kinds matching the spec’s applicability.
• AC-5: conform-skill-frontmatter.md, model-spec-optional-fields.md, and validate-against-skills-ref.md each carry status: closed (or the vault’s closed equivalent) and describe the shipped state, not a stale “open against main”.

Out of scope

• name, description client-side validation and the wizard/rename echo — T-M8AL-name-and-field-spec-validation.
• The empty-slug collapse (G6) and peer-resource path escape (G8) — neither is modelled or validated here; they are separate, already-ticketed gaps (solutions/agent-pants/docs/vault/tasks/fix-empty-slug-collapse.md, fix-peer-resource-path-escape.md) not part of this milestone.
• Surfacing which fields narrow a skill’s reachable harnesses in the editor — that is T-8BUZ-marketplace-targets-and-support-warnings.

Dependencies

• none

Discovery context

From the user’s Agent Manager planning request of 2026-09-07, “Spec adherence today” table row “compatibility ≤500, license, metadata string map” (Nowhere) and “Validator oracle” (none, G10). Full findings in solutions/agent-pants/docs/vault/research/agent-skills-conformance.md, whose G1/G2/G3/G5/G9 verdicts are superseded by bb00c3283 (the portable frontmatter dialect) — verified directly against packages/rust/agent-adapt/src/render/skill_md.rs and runtime.rs on 2026-09-08 before writing this task, since the audit predates that commit. Spec facts from agentskills.io/specification, fetched 2026-09-07: license optional; compatibility optional, max 500 chars; metadata optional map string to string. Validator: skills-ref on PyPI, CLI name agentskills (the vault note’s correction).

---

← Back to Tasks