Skill library

Skill library
Masterskills/master/audit/SKILL.md

Master Audit

The meta-skill. Audits every skill on its declared triggers, opens PRs for human review, never edits live skills directly.

Master Audit

The Master Audit skill is the keystone of the library. It is the skill that maintains the other skills. Without it the library decays — sources move, regulations update, internal practice drifts from documented practice. With it, the library stays trustworthy enough that the rest of the organization can rely on it.

What it does

On a schedule defined by each skill's freshnessIntervalDays, the Master Audit:

  1. Loads the category's _audit-guidance.md to determine source priority, update thresholds, and approval requirements for this domain.
  2. Reads the skill's frontmatter and listed sources.
  3. Fetches each source and compares to the cached checksum from sources.json.
  4. If the source has changed, reads the new version and identifies — using the category guidance — whether the change is material to the skill body.
  5. For material changes, drafts a proposed edit to the skill body and opens a pull request against the repository, addressed to the approvers named in the category guidance.
  6. For non-material changes, updates sources.json with the new checksum and notes the audit in the activity feed.
  7. For unchanged sources, simply notes the audit in the activity feed and bumps the skill's lastReviewedAt if the human content was reviewed against current source by the audit run.

Category-level guidance

For each skill audited, Master loads the category's _audit-guidance.md (at skills/{category}/_audit-guidance.md) to determine source priority, update thresholds, and approval requirements. This is the editorial layer that makes the audit domain-aware.

The audit runner is the same code regardless of category — what differs is the right answer for that domain. The Legal category prioritises official regulator publications and routes PRs to Head of Legal & Compliance; the Finance category prioritises national tax authority publications and routes to Head of Finance; the Developer category trusts the organisation's own ADRs above external best-practice writing. Without category guidance the audit would either be too cautious (a PR for every diff) or too permissive (missing the changes that matter).

When a category has no _audit-guidance.md, the audit falls back to conservative defaults: any non-cosmetic source change is treated as material, and the skill's named owner is the sole approver.

What "material" means

A material change is one that affects the operational guidance the skill provides. The category guidance defines what "material" means concretely — what counts in Legal (regulation amendments, court decisions) is different from what counts in Developer (major framework version bumps, high-severity security advisories). When the category guidance is silent on a specific case, the audit defaults to conservative: when in doubt, open a PR for a human to evaluate. False positives on PRs are cheap; false negatives on regulatory changes are expensive.

How a proposed edit lands

Every PR from Master Audit includes:

  • A summary of what changed in the source.
  • A diff against the current skill body showing the proposed edit.
  • A list of projects currently linked to the skill, so reviewers know the blast radius.
  • A draft activity-feed entry describing the change.

A human — usually the skill's named owner — reviews, may modify the diff, and merges. Merging triggers a skill-refresh activity entry. The skill's lastReviewedAt is updated to the merge date.

Audit logs

Every audit run, regardless of outcome, writes an entry to the audit log. The skill detail page surfaces the last audit and a link to the full log. This makes it possible to answer "when was this last verified against source?" without leaving the library.

Triggers

Skills declare how the Master Audit should act on them in their frontmatter triggers array:

  • interval — re-audit every N days regardless of source change.
  • schedule — re-audit on a cron schedule (typically aligned with the upstream source's own publication cadence).
  • event — re-audit when something specific happens elsewhere (a PR opens in SPYN, a release branch is pushed, a candidate completes a test).

Master Audit runs Sunday, Monday, and Wednesday at 18:00 (0 18 * * 0,1,3). Skills without explicit triggers are treated as manual — the Master Audit will flag them at the self-audit pass below.

Self-audit

The Master Audit skill audits itself on the same cadence as everything else. The self-audit checks: that the source list is current, that the audit's published behaviour matches the implementation, and that every other skill has at least one trigger declared. Skills lacking triggers surface in the Updates queue with a recommendation. Self-audit findings are treated like any other audit finding, with one difference: the reviewer cannot be the original author of the proposed change.

Owned by

Platform team. This skill is visible to SuperAdmin and Admin only — not surfaced to User role.