Designing a Governance Layer for AI Skills

In Part 1, I argued that reusable AI skills have become software artifacts.

That thesis is only useful if it changes the architecture.

A governance layer should make skills easier to discover, safer to reuse, and cheaper to maintain. It shouldn't require every team to adopt the same model, editor, or orchestration framework. And it needs to separate facts a machine can enforce from judgments that still need a human reading them.

This article walks through the architecture behind the open-source Skill Governance Toolkit, including the choices that mattered more than the code did.

Start with the lifecycle, not the tool

It's tempting to begin with a marketplace, an MCP server, or a CLI. Those are delivery mechanisms. Governance begins with a lifecycle:

Open the full-size SVG diagram →

Each transition needs a contract. Discovery needs consistent metadata. Evaluation needs criteria. Distribution needs compatibility claims. Adoption needs an upgrade and removal path.

Skip those contracts and a collection of skills is just a folder.

Three instruction layers

The toolkit separates information by loading cost and responsibility:

L1 — Project rules       always loaded
L2 — Procedural skills   loaded when intent matches
L3 — Specialized agents dispatched when supported

AGENTS.md holds universal project rules. A SKILL.md contains a bounded procedure activated by its description. A file under agents/ supplies specialized expertise that an orchestrator may dispatch.

Open the full-size SVG diagram →

That layout avoids two expensive extremes: loading every procedure on every turn, or burying every rule inside an opaque runtime configuration.

The sub-agent layer is optional by design. Four supported runtimes can use the included code-reviewer agent; Gemini CLI currently needs the instructions inlined or run sequentially instead. Portability claims carry more weight when you're upfront about limitations like that.

One source, multiple runtimes

Forking the same skill for each host looks pragmatic at first. In practice it creates five sources of truth.

The toolkit instead keeps one canonical skills/ directory. Runtime manifests and thin aliases point back to it:

• AGENTS.md is the rule source;
• CLAUDE.md and GEMINI.md import it;
• Copilot, Cursor, and Codex consume the appropriate root files or manifests;
• host-specific packaging changes, but skill content doesn't.

The rule is simple: capability differences belong in compatibility metadata and fallback paths, not in duplicated skill bodies.

Split deterministic checks from semantic judgment

This is the most important boundary in the design.

Some findings have to come out identical no matter which model happens to be running:

• required front matter is missing;
• a host-only allowed-tools field breaks portability;
• a secret-like token is embedded;
• a destructive shell command appears;
• a file contains hidden bidirectional characters or suspicious homoglyphs;
• a referenced script escapes the repository boundary;
• a mutating skill has no preview or confirmation contract.

Other questions are inherently semantic:

• Is the description specific enough for reliable discovery?
• Are examples representative rather than decorative?
• Does the workflow explain edge cases clearly?
• Are constraints proportionate to the risk?
• Would another engineer understand how to verify the result?

Open the full-size SVG diagram →

The deterministic engine is stdlib-only Python, read-only by default, and needs no network access. The same rules are exposed in three modes:

Mode	Best for
CLI	local checks and CI gates
MCP	an agent auditing a skill while it is being edited
Docker	isolation, reproducibility, or environments without local Python

These are delivery layers, not three separate engines. A finding shouldn't change just because it came from an editor instead of CI.

Progressive enforcement beats the clean-slate fantasy

A governance rollout often fails for a predictable reason: the first audit surfaces years of debt and immediately blocks every change.

The toolkit's changed-only gate compares findings at a base ref against findings at HEAD. A finding's identity excludes its line number, so moving existing text around doesn't turn old debt into a new failure.

Open the full-size SVG diagram →

That makes a simple policy possible: don't let the library get worse, then improve it on purpose. High-severity new findings can block; medium and low findings can start out advisory.

Governance as a set of composable skills

The toolkit ships six meta-skills instead of one universal "govern everything" agent:

1. skill-find searches project, personal, and corporate libraries.
2. skill-evaluate scores one skill across nine quality dimensions.
3. skill-compare recommends whether to keep, replace, or merge variants.
4. library-audit detects collection-level drift and collisions.
5. skill-build-portable transforms a host-specific skill with a diff preview.
6. integration-init installs optional analysis integrations.

The boundaries between them matter. A detect-only library audit shouldn't quietly rewrite files, a mutating portability workflow needs to preview its changes before applying them, and a comparison tool should hand you a decision rather than sneak in an undeclared migration.

Small skills also compose better. An audit can spot a problem, an evaluator can explain it in depth, and a builder can propose a repair, all without one oversized workflow owning every decision.

Installation is part of governance

Distribution code can wreck trust even when the skills themselves are excellent.

So the installer distinguishes user-owned files from toolkit-owned files. It only touches user instruction files inside marker blocks. Toolkit-owned files are tracked separately, so upgrades and uninstalls remove only what the toolkit put there. User content outside the markers, state directories, and generated reports stay untouched.

Safe upgrade, rollback, and uninstall aren't packaging trivia. They're lifecycle requirements.

Traceability and resumability

Audit reports include both the engine version and the rule-catalog version, so a verdict can always be traced back to the policy that produced it.

Longer workflows checkpoint after expensive phases into a project-local state directory. If a run gets interrupted, it resumes instead of repeating work or guessing what already completed. It's a small implementation detail, but it has an outsized effect on reliability: agent workflows fail and get interrupted just like any other distributed process.

What I would keep invariant

Tools and formats will change. These design principles should outlast them:

• one canonical source for each skill;
• explicit interfaces and compatibility claims;
• deterministic gates for deterministic facts;
• semantic review for semantic quality;
• read-only inspection as the default;
• preview and recovery for mutations;
• progressive enforcement for legacy libraries;
• traceable rule and engine versions; and
• optional runtime optimizations with functional fallbacks.

Governance should stay portable even when the agents running it aren't.

The architecture in one view

Open the full-size SVG diagram →

The implementation itself is deliberately modest. What matters is the separation of concerns: authoring, evaluation, enforcement, packaging, and execution no longer collapse into one giant prompt.

---

Previous: Part 1 — AI Skills Are Becoming Software. They Need Governance.

Next: Part 3 — AI Skills Are Executable Assets. Let's Review Them Like Code. goes deeper into the threat model: prompt injection, Unicode deception, referenced scripts, hooks, MCP configuration, blast radius, rollback, and idempotency.

Explore the implementation: github.com/artemrudenko/skill-governance-toolkit.

Where would you draw the boundary between a CI-blocking rule and a review-time recommendation?