Skip to content

application/agent-skills+md contradicts the registered-suffix claim and ADR 0014's own rationale #71

Description

@liady

The known-types list in "Catalog Entry > type" includes:

application/agent-skills+md - an Agent Skill defined in a standard Markdown file (the suffix +md is to be registered)

Two contradictions:

  1. The very next paragraph claims "These values are designed to align with official IANA media type registration standards. Standard ecosystem types use registered structured syntax suffixes (+json, +zip, +gzip)." The +md suffix is not a registered structured syntax suffix, so the list contradicts its own registrability claim.

  2. ADR 0014's rationale already resolved this differently: "Standard Markdown is represented by the generic, globally registered text/markdown media type. Because using text/markdown in isolation does not indicate the document is an Agent Skill ... we use the standard IANA profile parameter (profile="urn:air:agent-skill") to cleanly declare the semantic profile of the document while remaining 100% standard-compliant." That decision never made it into the known-types list - the list (in both the ADR's own Decision section and the spec) still carries application/agent-skills+md.

The docs type table (docs/guides/creating-a-catalog.md, "Choosing a type") repeats application/agent-skills+md and would need the same update.

Suggested resolution: replace application/agent-skills+md with text/markdown;profile="urn:air:agent-skill" per the ADR 0014 rationale, or explicitly decide to pursue +md registration and fix the surrounding registered-suffix claim. Either way the ADR's Decision and Rationale sections should stop disagreeing with each other.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions