We're starting to treat AI skills as software.
We're still managing them like prompts.
That gap is easy to ignore when one developer keeps a handful of local instruction files. It gets expensive once skills are shared across a team, loaded by several agent runtimes, and trusted to guide tools that can read repositories, run commands, or touch production systems.
A reusable skill isn't just text anymore. It has an interface, dependencies, compatibility assumptions, failure modes, and a blast radius. It can go stale, conflict with another skill, or work fine on one runtime and quietly fail on another. At that point it's behaving like a software artifact, and software artifacts need governance.
The prompt model breaks at team scale
The first version of almost every agent workflow is a prompt: explain the task, add a few examples, ask the model to follow the rules.
Then the prompt grows. Someone appends architectural conventions, then safety warnings, then tool-specific syntax. A second developer copies it and tweaks a line. Another team spins up a "cleaner" version. Six months later, nobody can say which copy is the real one.
That's not mainly a context-window problem. It's a lifecycle problem.
| When a skill is treated as a prompt | When a skill is treated as software |
|---|---|
| Copied between chats | Stored in a canonical repository |
| Changed without history | Versioned with meaningful diffs |
| Trusted because it reads well | Evaluated against explicit criteria |
| Bound to one agent host | Declares and tests portability |
| Reviewed informally | Passes review and security gates |
| Owned by whoever last edited it | Has an owner and lifecycle |
The model still executes instructions probabilistically. The asset around those instructions doesn't have to be unmanaged.
What makes a skill a software artifact?
Not every prompt deserves a release process. The boundary is reuse plus consequence.
A skill crosses that boundary when it's expected to:
- work repeatedly rather than once;
- be discovered and activated from natural-language intent;
- coordinate tools, scripts, files, or sub-agents;
- behave consistently across projects or runtimes;
- be maintained by more than one person; or
- produce changes whose failure matters.
At that point the skill starts looking like software in five specific ways.
It has an interface: its name and description decide when an agent picks it up, and its inputs, outputs, and verification steps form a contract with whoever uses it. It has dependencies, often on tools, MCP servers, scripts, reference files, or other skills. Compatibility becomes a real question once host-specific fields and capabilities start producing different behavior across Claude Code, GitHub Copilot, Cursor, Codex, and Gemini CLI. You can assess its quality attributes: clarity, completeness, specificity, discoverability, testability, portability, safety. And it carries risk, since instructions can normalize destructive commands, expose credential paths, trust hostile content, or hide behavior behind Unicode characters that look harmless.
Calling the file "Markdown" doesn't make any of that go away.
Governance is not bureaucracy
Say "governance" and most people picture a committee standing between an engineer and the work that actually matters. That's not what I mean by it here.
For skills, governance comes down to a small set of questions:
- What assets do we have?
- Who owns them?
- What contract does each asset promise?
- Which runtimes and dependencies does it support?
- What evidence is required before it's shared?
- What should block a change, and what should merely warn?
- How do we upgrade, deprecate, and remove it safely?
Good governance makes the safe path the easy path: a standard for authors, a shared vocabulary for reviewers, a deterministic baseline for CI.
Open the full-size SVG diagram →
None of this is meant to slow every edit down. It's meant to make the lifecycle visible.
Memory was the symptom, not the product
My own path to this idea started with an AI pair programmer that kept losing project context between sessions: architectural decisions, naming conventions, testing expectations, the reasoning behind earlier choices.
My first instinct was to write a bigger instruction file.
That helped, until it didn't. The file got harder to navigate, harder to validate, and increasingly tied to one specific tool. The deeper issue wasn't that the model needed a bigger memory. It was that project knowledge needed structure.
So instead of asking an agent to remember everything, I started packaging bounded procedures as skills: discoverable, reusable, versioned, reviewable, portable.
The memory problem is what led me to the architecture. Governance turned out to be the actual product.
A concrete experiment: Skill Governance Toolkit
I built the open-source Skill Governance Toolkit as a reference implementation of this approach.
It uses one canonical skills/ directory and a shared AGENTS.md source of project rules, while packaging the same six core meta-skills for Claude Code, GitHub Copilot, Cursor, OpenAI Codex CLI, and Google Gemini CLI.
Those meta-skills cover a practical lifecycle:
- find an existing skill before creating another;
- evaluate one skill across nine quality dimensions;
- compare local and corporate variants;
- audit a library for systemic issues;
- convert host-specific skills into portable ones; and
- initialize optional integrations.
The repository also includes a deterministic, read-only audit engine. The same checks run locally or in CI through a CLI, interactively through MCP, or inside a locked-down Docker container. A changed-only gate can block newly introduced high-severity findings without forcing a team to fix all historical debt first.
This distinction matters:
- deterministic checks handle reproducible facts such as malformed front matter, unsafe shell patterns, hidden characters, hardcoded paths, and missing contracts;
- model-assisted evaluation handles semantic questions such as whether instructions are clear, examples are useful, or trigger phrases are discoverable.
Governance needs both. Asking an LLM to make every safety decision creates recursive trust. Asking a lexical scanner to judge clarity creates false confidence.
The questions we should ask in review
Once you start seeing skills as software, the review question changes. "Does this prompt look good?" isn't enough anymore.
Ask instead:
- Is its activation boundary specific enough to avoid collisions?
- Does it state what it will and will not change?
- Are inputs, outputs, and completion criteria explicit?
- Can it run without one vendor's private front matter?
- Are required scripts and MCP servers declared?
- Does a mutating workflow preview changes and support recovery?
- Could untrusted content be mistaken for instructions?
- What happens on interruption, retry, or partial failure?
These are ordinary engineering questions. That's the point.
The shift
Prompt engineering asks: how do I phrase this instruction so the model follows it?
Skill engineering asks: how do I design, validate, distribute, and evolve this capability so a team can rely on it?
We'll keep writing prompts. But the reusable ones are turning into something more consequential: interfaces between human intent, model behavior, and the tools that actually do things.
Teams that catch that shift early won't just end up with better prompts. They'll have a capability system they can actually maintain.
Next: Part 2 — Designing a Governance Layer for AI Skills examines the architecture: instruction layers, deterministic and semantic checks, portability, CI policy, and safe adoption.
Series:
- AI Skills Are Becoming Software. They Need Governance. (this article)
- Designing a Governance Layer for AI Skills
- AI Skills Are Executable Assets. Let's Review Them Like Code.
The toolkit is open source and MIT-licensed: github.com/artemrudenko/skill-governance-toolkit.
How is your team reviewing and maintaining reusable agent instructions today?
Top comments (0)