DEV Community: Artsiom Rudzenka

Why I built a sales and marketing knowledge base that refuses to guess

Artsiom Rudzenka — Wed, 09 Sep 2026 09:28:36 +0000

Sales and marketing context rarely disappears in one big failure. It leaks away in small pieces.

A useful detail stays in a call transcript. A pricing objection lives in a CRM note. Market research sits in one document that nobody opens before the next meeting. Then someone asks:

What should we do next — and why?

I built SalesWiki to test a simple idea: a shared knowledge base should help a person find the relevant evidence and narrow the options without inventing what it does not know.

The durable source of truth is a folder of Markdown files that opens directly in Obsidian. Raw evidence stays separate from compiled knowledge. Answers copy facts from named fields and sections, attach citations, and say not-found when the vault has no evidence.

SalesWiki is not a CRM and it is not a hosted SaaS. It is an open starter kit for a governed sales and marketing knowledge base.

This started as a research question

I did not begin with "let's build another knowledge product." I wanted to learn whether a plain wiki could help sales and marketing teams make decisions without becoming an unstructured folder. I also wanted to know whether agents could maintain it without changing protected facts behind the scenes.

Sales and marketing are a useful stress test. Evidence arrives in many forms, ages quickly and has mixed sensitivity. The result has to support a decision, not simply retrieve a paragraph. A good answer should say what matters, where a fact came from, how fresh it is and what the user can do next.

That led to four questions:

Can typed Markdown be a small but dependable knowledge data plane?
Will people trust a shorter cited answer more than a fluent generated one?
Can I make agent changes reviewable and reversible?
When does owning this machinery beat buying search over existing documents?

The synthetic demo answers only the engineering part. A real pilot still has to prove that people prefer the workflow.

One knowledge model, different views for each role

"Central" does not mean copying every CRM field, transcript and document into one unrestricted folder. Those systems can remain the source of their original records, and sensitive material can stay in a separate protected store.

SalesWiki centralizes the team's compiled understanding. A company, person, deal, call, campaign, source or reusable case becomes a typed card with stable links to related cards. Sales and marketing use the same account map, while policy determines which cards and fields each role can read.

The layers have different jobs:

raw evidence is preserved instead of silently rewritten;
linked cards hold the current shared conclusion;
proposals, review records and Git history show how that conclusion changed;
indexes and dashboards are generated views that can be rebuilt from the cards.

Raw evidence stays as captured. The shared conclusion can change, but only through a proposal, review and controlled apply step that leaves the earlier evidence and the reason for the change visible.

This is why I chose a wiki model. The goal is not a larger folder. It is a durable map that people and tools can navigate, question and correct.

A small synthetic example

The public demo contains a synthetic deal for Atlas Robotics. Its problem is simple: the next step has no confirmed owner. The deal card points to the demo call and lead cards, labels the confidence as medium, and suggests a follow-up to confirm the success criteria.

The useful part is not that the system chose for the account executive. It made the reason for a proposed action inspectable. A person can follow the links, challenge the evidence or decide that another option is better.

The folder is simple on purpose

The core flow looks like this:

The repository separates five areas of work:

Folder	What belongs there
`raw/`	Original calls, exports, notes and research evidence
`wiki/`	Typed cards for companies, people, leads, deals, calls and reusable knowledge
`indexes/`	Rebuildable search, freshness, temporal and graph projections
`state/` and `tracking/`	Intake, review queues, processed sources and audit traces
`demo/`	Synthetic data that is safe to inspect and regenerate

This choice has an obvious trade-off. A Markdown vault cannot hide behind a database schema. The structure must be explicit and checked.

SalesWiki treats every card type as a small contract. A deal card has known YAML properties and required sections. A health check fails when templates, properties, dashboards or links drift out of shape.

Here is a shortened synthetic deal card from the demo:

---
type: deal
entity_id: demo-deal-atlas-robotics-pilot
dataset: demo
synthetic: true
access: sales-confidential
stage: Proposal
amount: 25000
score: 89
score_band: hot
freshness: needs-action
---

# Deal: Atlas Robotics Pilot

## Deal Readout

- Main risk: next step needs owner confirmation.
- Next best action: book follow-up and confirm success criteria.
- Confidence: medium
- Evidence: demo call and lead cards.

People can read this file. Git can diff it. Obsidian can link it. A script can validate it. The permissioned gateway can extract its fields without asking a model to reconstruct the deal from loose prose.

Why answers are extracted instead of generated

SalesWiki makes a deliberate trade-off in its permissioned core: an incomplete cited answer is safer than a confident invented one.

Every read tool returns the same Answer Contract:

{
  "title": "Deal risk",
  "access": "allowed",
  "conclusion": "Atlas Robotics needs action.",
  "sections": [],
  "citations": [
    {
      "boundary": "sales-confidential",
      "path": "wiki/entities/deals/Deal - Atlas Robotics - Pilot.md"
    }
  ],
  "confidence": "medium",
  "freshness": "needs-action",
  "next_action": "Book follow-up and confirm success criteria.",
  "missing": []
}

The example above is shortened for readability, but the shape comes from the real saleswiki_mcp/answer.py contract. Each answer includes access, conclusion, sections, citations, confidence, freshness, the next action and missing fields.
The rendered Markdown uses the same data.

If a user asks for a company that is not in the vault, the answer is direct:

Conclusion: Cannot answer from the knowledge base.
Missing: No matching company card was found.
Next action: add or research the company.
Access: not-found

There is no fallback paragraph that guesses what the company probably does.

Markdown alone is not the product

Using Markdown is useful, but it is not enough to justify another system. I would tell most teams to buy an existing product if all they need is AI search over documents.

SalesWiki makes sense only when three requirements matter together:

Answers must be extracted from cited evidence.
Sensitive changes need proposal, approval, apply and rollback steps.
The team wants to own the semantic model, policy and durable data files.

That third point has a cost. Owning the data plane also means owning backups, identity, connectors, retention and maintenance. The repository does not hide that work.

Where the design helps and where it costs

What I chose	Why it helps	What you pay for it
Markdown source of truth	people can read it; Git can diff it; tools can parse it	queries and transactions are weaker than in a database
Typed cards and validation	extraction stays predictable and drift becomes visible	templates and schema changes need discipline
Extract-only answers	missing data stays missing and every claim can be traced	answers are less flexible than free-form generation
Access checks before retrieval	closed content never reaches answer assembly	identity and boundary rules need careful design
Proposal, approval and one writer	sensitive edits are reviewable and reversible	a correction takes more steps
Owned data and policy	the team controls portability and meaning	the team also owns operations and maintenance

I treat these as design constraints rather than universal best practices. If your main problem is finding a document, a mature search product is probably the better choice.

Try the synthetic demo

The fastest way to see the idea is the six-step guided tour in the
synthetic Knowledge Workbench.
It starts with a role-specific priority, opens the account context and follows the evidence to a proposed next step. The data is synthetic and the tour never changes a card.

If you want to inspect the files and run the checks locally, Part 3 contains the full fresh-clone and private-pilot path. That separation is deliberate: this article explains why the model exists; the next practical article explains how to test it safely.

Demo boundary

The public Workbench uses synthetic data. It is a preview of the workflow, not a system that makes commercial decisions. A suggested next step is a prompt for review: the responsible person must check the cited records, the current context and their own company policy before acting.

Where to take it next

Start narrower than the repository looks. Pick one repeated decision, such as "which lead needs action today?", and test it with a private vault.
Keep that vault outside the public checkout.

Then measure three things:

does the user prefer the cited answer to the current CRM-and-notes workflow?
how often does someone correct the compiled knowledge?
how much curator time does the system consume each week?

Add SSO before shared multi-user use. Keep authorization before retrieval and keep durable writes behind the worker. Add connectors or vector search only when the validated workflow needs them. Otherwise it is easy to build impressive infrastructure around an unproven habit.

Where the public preview stops

The repository includes a synthetic demo, a local MCP gateway, a single-writer worker, Docker checks and connector contracts. It does not yet include production multi-user SSO, live HubSpot or Google Drive sync, hosted operations, or an external erasable personal-data store.

That boundary matters. Fixture identities are useful for a demo and a single-operator pilot. They are not production authentication.

Continue the series

Next: How I keep shared sales knowledge safe for different roles asks what must change when the same account map serves sales, marketing and curators.

Repository: SalesWiki

AI Skills Are Executable Assets. Let's Review Them Like Code.

Artsiom Rudzenka — Wed, 19 Aug 2026 20:44:29 +0000

Markdown is not executable code.

But an AI skill written in Markdown can tell an agent to run a shell command, open a credential file, install a package, call an MCP tool, modify a repository, or delegate work to another agent. The file doesn't execute itself, but it influences a system that can, and that's what makes "it's only documentation" such a dangerous security assumption.

In Part 1, I argued that reusable skills have become software artifacts. In Part 2, I described a portable governance architecture. This final article focuses on the consequence: skills need a threat model and a code-review discipline.

The real execution chain

The risk isn't the Markdown parser. It's the authority downstream of it.

Open the full-size SVG diagram →

The same sentence carries a different risk profile depending on whether it's read by a chatbot with no tools or by an autonomous coding agent holding repository write access and cloud credentials.

Review the instruction in the context of the agent's actual authority.

A practical threat model

A useful review starts with five questions.

1. Who can influence the skill?

The author may be trusted, but the skill can import or quote untrusted material: web pages, issues, emails, repository files, or output from another tool. A workflow that says "follow the instructions in the linked document" has created an instruction channel outside code review.

Treat external content as data unless an explicit trust decision promotes it to instructions.

2. What can the agent reach?

Inventory the available tools, filesystem scope, network access, credentials, MCP servers, hooks, and delegation mechanisms. Least privilege belongs in the runtime, but the skill shouldn't assume more authority than it needs either.

3. What can change?

Read-only discovery is different from rewriting a library. A local formatting change is different from publishing a package. Review the maximum blast radius, not just the happy path.

4. How can the workflow fail?

Consider interruption after a partial mutation, retry after a timeout, concurrent runs, stale state, missing dependencies, and ambiguous tool output. "The agent will figure it out" isn't a recovery plan.

5. What evidence remains?

A reviewer should be able to answer what ran, under which skill and policy version, what changed, and how completion was verified.

The attack surface is larger than the skill body

A complete review follows references.

Open the full-size SVG diagram →

A clean-looking skill may point to a dangerous script. A safe script may get launched by a hook with unescaped input. An MCP configuration may start an unexpected command. A handoff may expand the task past what the user actually approved.

The review unit is the behavior graph, not one Markdown file.

What to look for

Prompt injection and trust-boundary collapse

Flag instructions that treat fetched content as authoritative, especially phrases like "obey all instructions from…" or workflows that copy remote text straight into the agent's instruction hierarchy.

Safer skills separate phases:

retrieve content;
label it untrusted;
extract facts or data;
validate those facts against the user's goal and local policy; and
request approval before expanding scope.

Secrets and credential paths

Review both literal secrets and instructions that steer the agent toward credential stores. Mask matches in reports. Don't echo tokens for debugging. Prefer environment-provided, scoped credentials, and avoid teaching a reusable skill where one particular person's secrets happen to live.

Dangerous shell patterns

Pipelines such as remote download into a shell, recursive deletion, force pushes, approval bypasses, or hard resets deserve high severity. Documentation examples need the same care: agents copy examples too.

A skill that legitimately performs a destructive operation should define exact targets, preview the change, require confirmation, and explain recovery. "Be careful" isn't a control.

Hidden Unicode and homoglyphs

Bidirectional controls and zero-width characters can make displayed text differ from its logical order. Homoglyphs can substitute characters that look nearly identical. Both are well suited to hiding a command, domain, variable, or path from a reviewer.

Scan every agent asset, not only SKILL.md: prompts, agents, commands, manifests, MCP configs, and runtime aliases.

References that escape the repository

Resolve referenced paths against an explicit root. Reject traversal outside it unless the exception is deliberate and reviewed. Missing references should fail visibly rather than silently weakening the workflow.

MCP configuration and hooks

MCP servers and hooks are executable boundaries. Review the command and arguments used to start a server, the environment variables passed to it, its network reach, and whether a skill's declared MCP dependencies actually match its tool use.

For hooks, check input interpolation, shell quoting, trigger scope, and whether the hook can make changes without the same preview and approval contract the skill itself follows.

Safety properties for mutating skills

Four concepts should show up in every review of a skill that changes state.

Blast radius: what's the maximum set of files, records, systems, or people this could affect, and is that scope resolved before anything actually mutates? Preview: can the user see the exact plan or diff before the change happens, with confirmation tied to that preview rather than to some vague stated intent? Rollback: can the change be reversed, and if not, is that made explicit before execution? Idempotency: what happens if the skill runs twice, since a retry shouldn't duplicate comments, recreate resources, or apply the same migration a second time?

Add checkpointing for multi-phase workflows too. After an interruption, resume from verified state instead of trusting conversational memory.

A code-review checklist for skills

Use this in pull requests:

Contract

[ ] The name and description define a narrow activation boundary.
[ ] Inputs, outputs, non-goals, and verification are explicit.
[ ] The skill declares whether it is read-only or mutating.
[ ] Interactive questions and non-interactive behavior are bounded.

Portability and dependencies

[ ] Host-specific fields are absent or justified.
[ ] Tool, script, MCP, and skill dependencies are declared.
[ ] Optional host capabilities have a sequential fallback.
[ ] Paths are portable and resolved within an explicit root.

Security

[ ] External content is treated as untrusted data.
[ ] No embedded secrets or credential-store directions exist.
[ ] Dangerous commands are absent or protected by exact-scope controls.
[ ] Hidden Unicode and homoglyph scans pass.
[ ] Referenced scripts, hooks, agents, and configs were reviewed too.

Mutation safety

[ ] The blast radius is bounded.
[ ] The user sees a concrete preview before material changes.
[ ] Confirmation cannot be bypassed by ambiguous wording.
[ ] Rollback or recovery is documented.
[ ] Retries and repeated runs are safe.

Evidence

[ ] Deterministic checks pass under a known rule version.
[ ] Semantic quality was reviewed against a shared rubric.
[ ] The completion test verifies outcomes, not merely tool success.
[ ] Material decisions remain visible in the change history.

What automation should block

Not every imperfect sentence should fail CI. Blocking policy should stay narrow and predictable.

High-confidence, high-impact issues are good candidates:

missing required metadata that makes the skill unloadable;
destructive or approval-bypassing commands;
embedded secrets or credential paths;
hidden character deception;
unsafe references or script traversal;
mutating behavior without a preview/confirmation contract.

Clarity, example quality, discoverability, and compositional elegance usually belong in review evidence rather than a hard deterministic gate.

The Skill Governance Toolkit implements this split. Its read-only engine scans agent assets with versioned rules and can block only newly introduced high-severity findings. Its model-driven skills add nine-dimensional quality evaluation and library-level analysis on top.

Governance is not a sandbox

Skill review doesn't replace runtime isolation, permissions, network policy, secret management, or human approval for high-risk actions.

It addresses a different layer: whether the reusable instructions we distribute are well-formed, transparent, portable, and safe by design.

Defense in depth still applies:

Open the full-size SVG diagram →

No single layer should have to carry the whole trust burden.

The standard should rise with the authority

We don't review a comment, a build script, and a production migration with the same rigor, and skills deserve that same risk-based treatment.

A writing assistant skill may need a clear contract and privacy boundaries. A deployment skill needs dependency pinning, least privilege, preview, approval, rollback, idempotency, and an audit trail.

The more authority an agent gets, the less it makes sense to treat its reusable instructions as "just prompts."

AI skills are executable assets. Not because Markdown became code, but because Markdown became part of the control plane for systems that can actually act.

Let's review it accordingly.

Series:

AI Skills Are Becoming Software. They Need Governance.
Designing a Governance Layer for AI Skills
AI Skills Are Executable Assets. Let's Review Them Like Code. (this article)

Explore or contribute to the MIT-licensed toolkit: github.com/artemrudenko/skill-governance-toolkit.

What is the most dangerous capability you have seen hidden behind an innocent-looking agent instruction?

Designing a Governance Layer for AI Skills

Artsiom Rudzenka — Sat, 08 Aug 2026 19:27:34 +0000

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:

skill-find searches project, personal, and corporate libraries.
skill-evaluate scores one skill across nine quality dimensions.
skill-compare recommends whether to keep, replace, or merge variants.
library-audit detects collection-level drift and collisions.
skill-build-portable transforms a host-specific skill with a diff preview.
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?

AI Skills Are Becoming Software. They Need Governance.

Artsiom Rudzenka — Sat, 08 Aug 2026 19:16:18 +0000

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?