We're starting to treat AI skills as software.
We're still managing them like prompts.
Update, 27 October 2026: Version 1.21.2 adds clearer checks and safer updates. The dated update below separates format, toolkit policy and observed behavior.
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.
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 keeps six core meta-skills in one skills/ directory and project rules in one AGENTS.md file. It provides packaging for Claude Code, GitHub Copilot, Cursor, OpenAI Codex CLI and Google Gemini CLI. Packaging alone does not establish that every skill works in every environment.
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. Teams can call it locally, in CI, through MCP, or inside Docker. This delivery layer remains a preview. Teams can configure the gate to block new high-severity findings while they address older findings separately.
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.
I use each check for a specific question. A pattern match does not prove safety. A model's quality score still needs review.
Update: what version 1.21.2 checks
The checks on 27 October 2026 addressed three questions: format, toolkit policy and observed behavior.
The 1.21.2 changelog records changes across the 1.21 releases:
- The installer preserves skills and indexes that users changed or that it does not own.
- Metadata migration previews changes and creates a backup before writing.
- Skill discovery includes local skills missing from a managed index.
- The GitHub workflow fixes a setup error that previously prevented it from starting.
These changes address adoption problems as well as skill content. An upgrade needs to preserve the user's work.
The toolkit now separates the official skills-ref format validator from its own policy checks. It can also invoke a separately installed Cisco Skill Scanner.
| Check | Observed result | What remains unproven |
|---|---|---|
| Official format validator | It accepted all six bundled skills. | Format acceptance does not establish safe or useful behavior. |
| Selected security rules | They matched all 24 labelled synthetic examples: 12 positive and 12 negative. | This small corpus does not establish general detection accuracy. |
Agent assessment with and without skill-evaluate
|
Both conditions answered all 12 factual questions correctly across three synthetic cases. | This comparison showed no added benefit on those questions. |
The format validator also accepted a synthetic skill with allowed-tools: Read. The toolkit reported a portability-policy finding for that field. A toolkit policy finding and a format error answer different questions.
The agent comparison used one run per case and condition. It always ran without the skill first. The skill condition used more input tokens and took longer on average. It did not validate the nine quality scores. The experiment report includes the model, counts, timing and limits.
The runtime checks also have different boundaries. Claude Code, Codex and Copilot completed narrow synthetic skill scenarios, mostly with read-only outputs. The integration scenario only gave advice. Gemini discovered skill-find, but it needed authentication before it could execute the skill. The Cursor installer placed the skill files. The checks did not verify discovery or execution.
I now keep format, policy and observed behavior separate when describing compatibility or usefulness. Passing one check does not answer the other questions.
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)