Agent Skill Frontmatter Audit

Agent Skill Frontmatter Audit

Packmind renders skills (one of the three artefact types along with standards and commands) as a SKILL.md file with YAML frontmatter deployed into each AI coding agent's expected folder (.claude/skills/, .cursor/skills/, .github/skills/, .agents/skills/, .opencode/skills/, etc.).

There is a shared Agent Skills baseline specification that all supporting agents commit to (the "core" fields every agent understands), and then each agent may publish its own documentation extending that baseline with agent-specific "additional properties". Both layers evolve over time: the baseline spec ships new versions, and vendors add, rename, or deprecate extensions.

This skill audits Packmind's rendering against both layers and produces a dated report at the project root so drift can be tracked release over release.

Context

The audit is a four-way comparison per agent:

1. Baseline spec — the current Agent Skills specification at https://agentskills.io/specification.md. Defines the set of fields every compliant agent is expected to accept (typically name, description, and similar core keys).
2. Upstream agent spec — the agent's own public documentation page. May extend the baseline with agent-specific properties, or may be baseline-only.
3. Packmind declared support — the per-agent constants in packages/types/src/skills/skillAdditionalProperties.ts.
4. Packmind actual rendering — what each agent's deployer in packages/coding-agent/src/infra/repositories/{agent}/{Agent}Deployer.ts actually writes into the YAML frontmatter.

The four pairs can disagree silently:

• Baseline vs. upstream — a vendor page that omits a field the baseline requires is a vendor bug to note, not a Packmind action item.

• Upstream vs. constants — Packmind is behind (or ahead of) the vendor on agent-specific fields.

• Constants vs. deployer — internal drift; the "supported" promise in the codebase is a lie.

• A dead doc URL — the audit can no longer be trusted automatically for that agent.

None of these produce runtime errors. A deprecated field is silently ignored by the agent; a missing field is a silent feature loss for users. The only way to catch either is an audit against the upstream spec — which is what this skill automates.

Core principle: baseline-only is fine

Some agents choose to support only the baseline spec — no additional properties on top. That is a legitimate design choice and must not be reported as a warning, gap, or drift. Concretely: if an agent has no _ADDITIONAL_FIELDS constant in Packmind, no filterAdditionalProperties call in its deployer, and no agent-specific properties documented upstream, that agent is "baseline-only" and the report should mark it in sync with a short note like "no additional properties — baseline spec only".

Only flag a missing constant / missing filter when the agent's own upstream documentation lists properties beyond the baseline. Otherwise the absence is correct.

Sources in scope

The baseline spec is fetched once. Each of the five agents is fetched individually. Keep this list verbatim — adding, removing, or re-pointing an entry is a skill update, not an ad-hoc decision.

The canonical constants file is packages/types/src/skills/skillAdditionalProperties.ts.

Workflow

Run the steps in order. Parallelise fetches and codebase reads whenever one step doesn't depend on another — the audit is network-heavy and the user is waiting for a report.

Step 1 — Fetch the baseline spec and all upstream docs

Issue WebFetch calls in parallel: one for the baseline spec, plus one per agent URL.

For the baseline spec, extract:

• The version identifier of the spec (if stated on the page), so the report can cite which baseline was used.

• The complete list of baseline frontmatter keys with whether each is required or optional, and a one-line description quoted from the spec.

For each agent doc, extract:

• The complete list of YAML frontmatter keys the agent documents on SKILL.md. Separate baseline fields (those already in the baseline spec) from agent-specific additions.

• Any explicit deprecation markers (words like "deprecated", "removed", "no longer supported", "legacy", or strikethrough styling the page renders).

• A short one-line description of each agent-specific key, quoted from the vendor wording rather than invented.

• Whether the agent's docs explicitly declare "this agent supports only the baseline" or equivalent. If so, note it — it's the cleanest signal for the baseline-only classification.

Classify the fetch result of every URL as one of:

• ✅ Reachable and relevant — the page loads and documents skills/frontmatter.

• ⚠️ Redirected — the URL resolves but lands on a different, still-relevant page. Record both the requested and resolved URLs.

• ❌ Dead — 404, 403, empty body, or the landing page no longer mentions skills/frontmatter. Record the exact failure signal.

Do not fall back to training-data knowledge for a dead URL. If the baseline spec itself is dead, note that the entire audit cannot separate baseline from agent-specific fields and mark every per-agent classification as (uncertain — baseline source unreachable). If an agent doc is dead, only that agent's findings are marked uncertain.

Step 2 — Read Packmind's declared support

Read packages/types/src/skills/skillAdditionalProperties.ts. Extract:

1. Each per-agent constant that exists (today: CLAUDE_CODE_ADDITIONAL_FIELDS, COPILOT_ADDITIONAL_FIELDS, CURSOR_ADDITIONAL_FIELDS). For each, capture the YAML key ↔ camelCase storage key mapping. Claude Code declares its fields as a Record<string, string> (YAML→camel); Cursor and Copilot declare a flat string[] of camelCase keys. Do not assume the shape is uniform.
2. CLAUDE_CODE_ADDITIONAL_FIELDS_ORDER — the canonical rendering order for Claude. A key that's in CLAUDE_CODE_ADDITIONAL_FIELDS but not in the order array (or vice-versa) is a low-severity internal drift worth mentioning.
3. Any new constant that may have been introduced for Codex or OpenCode since this skill was last updated.

The absence of a constant for Codex or OpenCode is not automatically a finding. Whether it's a gap depends entirely on Step 1: if the agent's upstream doc lists no properties beyond the baseline, the absence is correct. If it does list extensions, then the absence is a missing-support finding.

Step 3 — Read the deployer for each agent

For each agent, open its deployer file listed in the scope table. In the file, locate:

• The method that produces the frontmatter block (typically generateSkillMdContent or similar). Read which keys it writes and in what order.

• Any call to filterAdditionalProperties(...): which constant does it pass in?

• Any call to sortAdditionalPropertiesKeys(...): missing here means non-deterministic YAML output for that agent's frontmatter.

For Codex and OpenCode, the current pattern is to delegate multi-file skill deployment to SingleFileDeployer/base-class logic (see packages/coding-agent/src/infra/repositories/utils/ and defaultSkillsDeployer/). If the deployer has no skill-specific frontmatter method at all, record (inherits base deployer; baseline fields only) as the deployer behaviour.

Treat a missing filterAdditionalProperties call as a concern only when the agent's upstream doc lists additional properties — in that case, the deployer either bypasses the declared list (leaking everything) or emits nothing agent-specific (leaking nothing, failing to expose supported fields). Figure out which from the emitted-keys list and classify accordingly. If the agent is baseline-only upstream, no filter is needed and no finding should be raised.