Designing a Governance Layer for AI Skills

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

That thesis is useful only if it changes the architecture.

A governance layer should make skills easier to discover, safer to reuse, and cheaper to maintain. It should not require every team to adopt the same model, editor, or orchestration framework. And it should distinguish facts a machine can enforce from judgments that still need semantic review.

This article describes the architecture behind the open-source Skill Governance Toolkit—including the choices that mattered more than the code.

Start with the lifecycle, not the tool

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

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

Without those contracts, 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.

This avoids two expensive extremes: loading every procedure on every turn, or hiding 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 requires the instructions to be inlined or executed sequentially. Portability claims are more credible when limitations are explicit.

One source, multiple runtimes

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

The toolkit instead keeps one canonical skills/ directory. Runtime manifests and thin aliases point 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 does not.

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 must be identical regardless of which model happens to run:

• 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?

The deterministic engine is stdlib-only Python, read-only by default, and requires no network. 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

They are delivery layers, not three engines. A finding should not change because it was requested from an editor instead of CI.

Progressive enforcement beats the clean-slate fantasy

A governance rollout often fails because the first audit reveals years of debt and immediately blocks every change.

The toolkit's changed-only gate compares findings at a base ref with findings at HEAD. The stable identity of a finding excludes its line number, so moving existing text does not turn old debt into a new failure.

This enables a practical policy: do not make the library worse, then improve it deliberately. High-severity new findings can block; medium and low findings can begin as advisory.

Governance as a set of composable skills

The toolkit includes six meta-skills rather than 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 matter. A detect-only library audit should not silently rewrite files. A mutating portability workflow should preview changes. A comparison tool should produce a decision, not perform an undeclared migration.

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

Installation is part of governance

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

The installer therefore distinguishes user-owned files from toolkit-owned files. It modifies user instruction files only inside marker blocks. Toolkit-owned files are tracked separately so upgrades and uninstall remove only what the toolkit owns. User content outside markers, state directories, and generated reports are preserved.

That is not packaging trivia. Safe upgrade, rollback, and uninstall are lifecycle requirements.

Traceability and resumability

Audit reports include both engine and rule-catalog versions. A verdict can therefore be traced to the policy that produced it.

Longer workflows checkpoint after expensive phases under a project-local state directory. If a run is interrupted, it can resume instead of repeating work or guessing what completed. This is a small implementation detail with a large reliability effect: agent workflows fail and get interrupted like any other distributed process.

What I would keep invariant

Tools and formats will change. These design principles should survive:

• 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 remain portable even when the agents are not.

The architecture in one view

The implementation is deliberately modest. The important result is a 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?