skill-gap-audit

Audit Meteor skill gaps

Compare the published catalog with current Meteor documentation and implementation. Produce a prioritized maintenance report. Do not create or edit skills during the audit.

This workflow adapts Meteor's docs-gap and changelog skill patterns while keeping the checkout path, checked-out branch, release context, and comparison revisions configurable.

Inputs

Determine these inputs before analysis:

• Agent-skills repository root.
• Agent-skills target ref and commit SHA. A coordinated release supplies the freshly fetched release PR head for beta/RC or default branch for stable, with a clean worktree.
• Meteor source checkout.
• Audit mode: full catalog or incremental changes.
• Meteor base and target Git revisions for an incremental audit.
• Meteor version or release context when the audit targets a release.
• Reviewed Meteor changelog, docs-gap report, and approved documentation changes when a coordinated release supplies them.
• Optional previous committed audit record.
• Optional output path. Return the report in the response when no path is requested.

Coordinated Meteor release audits

When the Meteor release process invokes this skill, start after its changelog and approved documentation gaps have been consolidated. Treat those artifacts as discovery and user-facing intent, then verify their claims against the release diff, current documentation, implementation, and tests. Do not copy core maintainer workflows into the public application-developer catalog.

The Meteor release commit may not exist yet during the first audit. In that case, include approved working-tree documentation changes, record the Meteor commit SHA and dirty state, and identify the audit as pre-publication. Before the Agent Skills tag is published, audit the exact Meteor release commit from a clean Agent Skills worktree pinned to the catalog commit being prepared for publication. If the first report is already committed, preserve it and create an incremental follow-up instead of rewriting it.

Pin the Agent Skills snapshot

For a coordinated release, require the caller to supply an Agent Skills target ref and commit SHA resolved after fetching the selected release branch: existing PR head for beta/RC, default branch for stable. Beta/RC audits do not require a merge; preserve the open PR and do not substitute its synthetic merge commit. Verify that the audit worktree is clean and that its HEAD equals the supplied SHA. Load this skill and inspect distributable content from that same worktree; do not load audit instructions from one revision while analyzing another.

Record the target ref, exact commit SHA, and clean state in the report. If the checkout is dirty, stale, or at a different commit, stop and ask the caller to provide a clean pinned worktree. This audit does not fetch, switch branches, or create worktrees on its own.

For a standalone audit without a supplied target, use the current HEAD, record its branch, SHA, and dirty state, and state that remote freshness was not established. Do not claim that it represents the latest published or default-branch catalog without evidence.

Resolve the Meteor checkout

1. Prefer a path supplied by the user or task.
2. Otherwise, use METEOR_CHECKOUT when it is set.
3. Otherwise, inspect accessible workspace roots and direct sibling directories for candidates.
4. Validate each candidate with git -C <path> rev-parse --show-toplevel and require v3-docs/, packages/, and tools/. Use Git remotes to distinguish meteor/meteor or a clear fork from unrelated repositories.
5. Continue automatically only when one credible candidate remains. Report its resolved path, remote, branch, commit SHA, and dirty state.
6. Ask the user for a checkout path when discovery finds none or remains ambiguous. Do not assume a home directory layout or clone without authorization.

The checkout can live anywhere accessible in the current environment. Do not store its machine-specific absolute path in committed skill content.

Audit method

Read the audit method before gathering evidence, including final-tag versus branch changes and earlier stable/package backports. Run affected acceptance cases in fresh read-only conversations when changing those audit decisions.

Build the skill inventory

For every publishable folder under skills/:

1. Read the frontmatter description, tagline, kind, area, bundle membership, Meteor range, and documentation sync date.
2. List the outcomes and symptoms promised by SKILL.md.
3. Map each promise to its supporting reference and evaluation case.
4. Compare naming, classification, routing, structure, references, and case style with the closest neighboring skills. Treat useful local variation as intentional unless it conflicts with the repository contract or behavior.
5. Note overlap with neighboring skills, promises without behavioral coverage, and classifications that do not match the skill's actual outcome or installation audience.
6. Exclude folders beginning with _ and internal .github/skills/.

Classify findings

Classification	Meaning	Normal action
Covered	Current skill instructions and cases address the behavior	No change
Partial	Skill mentions it but lacks a decision rule, example, or evaluation	Expand existing skill
Outdated	Skill conflicts with current documentation or implementation	Correct and retest
Overlap	Multiple skills advertise the same request without clear routing	Narrow descriptions
Candidate	Important repeatable workflow has no suitable skill	Propose a skill
Documentation only	Useful fact does not justify agent workflow guidance	Leave in docs
Uncertain	Available evidence is missing or contradictory	Investigate and do not implement

Propose a new skill only when it meets the threshold in skill-maintenance. Prefer expanding an existing skill when its scope already owns the user outcome.

Prioritize

Use this order:

1. Incorrect security, data-access, deployment, or migration guidance.
2. Removed APIs and breaking behavior.
3. Advertised capabilities with no instructions or acceptance case.
4. New user-facing workflows with strong skill value.
5. Routing overlap and near-miss failures.
6. Helpful improvements that are not release blockers.

Report

Read references/report-template.md before producing the report.

Every finding must include:

• Classification and priority.
• Affected skill or proposed scope.
• User impact.
• Evidence path, revision, and relevant symbol or section.
• Existing acceptance cases.
• Recommended action and acceptance evidence.

For full and release audits, include a claim matrix covering every distributable skill. For incremental audits, include every changed claim plus all claims affected by the Meteor diff, even when the skill file itself did not change.

Keep uncertain findings separate from confirmed gaps. State why evidence is insufficient and what would resolve it.

Handoff to skill maintenance

The audit is read-only except for writing a report to a user-requested output path. Do not update skills, metadata, branches, or GitHub state during an audit-only request.

When the user asks only for an audit, stop after the report and offer the prioritized findings for review.

When the same request explicitly asks to audit and fix:

1. Finish and preserve the audit report before editing.
2. Read skill-maintenance.
3. Implement only confirmed Partial, Outdated, or Overlap findings within the authorized scope.
4. Ask before creating a Candidate skill or acting on an uncertain finding.
5. Keep each change traceable to its evidence and acceptance criteria.
6. Run the complete maintenance validation and report which findings were applied.