Agent Skill vs Knowledge Base: Where Runbooks Go

An agent skill is an instruction package an agent loads and follows when it judges the skill relevant; a knowledge base is a collection of documents an agent searches and cites. So the procedure in a runbook belongs in a skill, and the reference around it belongs in a knowledge base. In Insulin, size, citation, sync and scope settle the cases in between.

---

Deciding where a runbook, a policy or a standard operating procedure should go? Insulin’s own documentation offers two answers. The Marketplace page counts “troubleshooting runbooks” among the team knowledge a skill can codify. The Knowledge Bases page counts “runbooks, tickets, contracts” among the material an agent can pull in to ground its response. This blog has filed runbooks in both places too: the guide to grounding an AI agent in your documents loads support runbooks into a knowledge base, and the skill posts turn a runbook into a skill.

Both are right, because “runbook” names two different things. One is a procedure: the steps to take when a particular situation arises. The other is reference: the background, specifics and history someone looks things up in. Insulin gives each its own home. Here is the rule that splits them, then the table, then the edges.

Is a runbook an agent skill or a knowledge-base document?

Split it by use: the procedure an agent follows goes in a skill, and the reference people look things up in goes in a knowledge base. Most runbooks hold some of each, so most end up split.

A skill is a markdown-based instruction package an agent loads and follows when it judges the skill relevant. Agents discover enabled skills automatically, and a skill’s Trigger, a short description of when it applies, helps them decide; the difference between an agent and a skill covers the rest of the definition. A knowledge base is a named collection of documents that agents can search when answering. Insulin splits each document into chunks and indexes it for hybrid vector and keyword search, and an agent cites the source document for each result.

The difference that matters for a runbook is the verb. A skill is followed: the agent loads its content into its context and follows the instructions in it. A knowledge base is searched: the agent finds what answers a question and names the document it came from. The steps for handling a disputed invoice want the first; the contract clause on credits wants the second.

Where should each part of a runbook go?

Start from what you have; the table names its home and the reason. The next section explains each reason.

What you have	Put it in	Why
A procedure to follow when a situation arises	A skill	Agents load a skill when they judge it relevant, and its Trigger helps them decide
A rule every reply of one agent must obey	That agent’s system prompt	The system prompt defines a custom agent’s behavior and constraints; a skill loads only when judged relevant
Reference people look things up in	A knowledge base	Hybrid search finds the matching content, and the agent cites the source document for each result
A long document, or many documents	A knowledge base	An uploaded skill is one markdown file of up to 50 KB or a .zip package of up to 10 MB; a knowledge base takes PDF, DOCX and text files of up to 25 MB each
A document the team keeps editing in Google Drive or ClickUp	A knowledge base on a synced connector	With Auto-sync on, Insulin sweeps connectors about once an hour; uploaded files and crawled websites don’t auto-sync
Know-how every agent in the organization should apply	A skill in the Organization store	Only an org admin can add one, and it is visible to the whole organization; enabled skills are discovered automatically, loaded on relevance, never guaranteed. A knowledge base must be attached to each custom agent, and an agent searches up to three per turn
Material an agent should maintain	A knowledge base attached in Edit mode	Edit lets the agent create, update and deprecate files, never delete them; Read mode only searches

What decides the edge cases?

Six documented mechanics decide the rows above, each a question you can answer about your document.

Is it long, or a PDF or Word file?

Then it belongs in a knowledge base. An uploaded skill is a single markdown file (.md or .markdown) of up to 50 KB, or a .zip package of up to 10 MB that includes a SKILL.md. A knowledge base takes PDF, DOCX and text formats such as .md, .csv and .json, up to 25 MB per file, plus pasted text of up to 2 MB.

The 50 KB ceiling is a limit, not a target: the Marketplace docs advise one topic per skill, because agents load only what is relevant. A procedure that runs for pages is usually two skills, or a short skill and a knowledge base.

Must the answer point to its source?

Then use a knowledge base, where the agent cites the source document for each result. That is what reference needs: when a spec or a contract term comes back in an answer, the reader can open its document and check. Test search previews what an agent would retrieve, with each result’s source document, before you attach the base.

Does the team keep editing it?

Then leave it where the team edits it and add it through a synced connector. Insulin sweeps connectors that have Auto-sync enabled about once an hour. Uploaded files and crawled websites don’t auto-sync, so an uploaded copy stays as it was until someone uploads a file with the same name, which replaces it in place.

The connectors are Google Drive (documents and files), ClickUp (tasks and Doc pages) and GitHub (issues and pull requests as Markdown, with no source code), so check that GitHub’s sync covers where your runbook sits. One more limit: an organization knowledge base supports only the Google Drive connector, while GitHub and ClickUp are available on user knowledge bases.

A skill is changed with Edit, which updates its name, description, prompt, Trigger, category or tags, so every skill needs an owner who edits it when the procedure changes.

Who needs it?

Know-how for every agent in the organization is an Organization-store skill; reference for some agents is a knowledge base attached to them. A Personal-store install creates a private copy in your own workspace; the Organization store is shown only to org admins, and an install there creates an org-shared copy visible to your whole organization. Either way, agents load enabled skills based on relevance, so even an organization-wide skill is never guaranteed to load.

A custom agent searches the knowledge bases explicitly attached to it (a user-level agent can attach your user knowledge bases, an org-level agent organization ones), while the built-in Insulin assistant searches the ones you own by default. An agent searches up to three knowledge bases at query time, and an org role alone opens no organization knowledge base: access comes from a per-knowledge-base share or org-wide sharing.

Must it hold in every reply?

Then it belongs in the agent’s system prompt, not in a skill. The system prompt holds the instructions that define a custom agent’s behavior, personality and constraints, while a skill is loaded only when the agent judges it relevant. Never confirm a credit amount; finance confirms credits is a system-prompt rule for a support agent, because it has to hold in conversations no skill was loaded into. A rule that matters only while one procedure runs, such as a discount ceiling in the quoting steps, stays in that skill’s constraints. The built-in Insulin assistant can’t be edited, so a standing rule needs a custom agent.

Should the agent maintain it?

Then attach a knowledge base in Edit mode. In Read mode, an agent retrieves and searches the knowledge base for grounded context only. In Edit mode it can also create, update and deprecate files, but never delete them; a deprecated file is retired from search and can be restored. That makes Edit mode the fit for material an agent keeps current itself, such as a known-issues list a support agent updates as cases close.

How do you split one runbook in practice?

Take each part of the runbook through the table, and keep every part in exactly one place. Acme’s support-operations runbook for billing disputes is a long Word document. It opens with seven steps to take when a customer says an invoice is wrong, then carries the pricing reference, the contract clauses on credits and an appendix of past disputes. Its escalation contacts sit separately in Google Drive and change most weeks.

Part of the runbook	Where it goes	Why
The seven steps for a disputed invoice	A skill, with a Trigger such as When a customer says an invoice doesn’t match what they agreed to pay	A procedure to follow when that situation arises
Never confirm a credit amount; finance confirms credits	The support agent’s system prompt	It must hold in every reply, not only when the skill loads
The pricing reference, credit clauses and past disputes	A knowledge base, as an uploaded DOCX	Reference to look things up in, cited in each answer
The escalation contacts	The same knowledge base, through the Google Drive connector with Auto-sync on	They change at their source, and the connector is swept about once an hour

Take the seven steps out of the document you upload: two copies of one procedure drift apart, and six months on nobody knows which is current. Shaping those steps into a good skill, with one procedure and a Trigger that names the situation, is the job of the worksheet for turning a team procedure into an agent skill.

The split also settles maintenance: the support lead edits the skill, the owner of the pricing reference uploads each new version under the same file name, and the contacts stay current through the connector.

Frequently asked questions

Should a runbook be an agent skill or a knowledge-base document?

Split it by use. The procedure an agent should follow when a situation arises goes in a skill. The reference people look things up in goes in a knowledge base, where the agent cites the source document for each result. Most runbooks need both.

What is the difference between an agent skill and a knowledge base?

A skill is a markdown instruction package an agent loads into its context and follows when it judges the skill relevant. A knowledge base is a named collection of documents an agent searches, citing the source document for each result.

Will an agent always load a skill?

No. Agents discover and load enabled skills automatically based on relevance to the conversation, and a skill’s Trigger helps them decide, so no skill is guaranteed to load. A rule that must hold in every reply of one agent belongs in that agent’s system prompt.

How large can a skill be, compared with a knowledge-base file?

An uploaded skill is a single markdown file of up to 50 KB or a .zip package of up to 10 MB. A knowledge base takes PDF, DOCX and text files of up to 25 MB each, so long manuals and large document sets belong there.

How do I keep a runbook current when my team keeps editing it?

Add it to a knowledge base through a synced connector: Google Drive, ClickUp, or GitHub issues and pull requests. With Auto-sync on, Insulin sweeps connectors about once an hour. Uploaded files and crawled websites don’t auto-sync, so an uploaded copy stays as it was until replaced.

How do I make know-how available to every agent in the organization?

Have an org admin add it as a skill in the Organization store, where it is visible to the whole organization. Agents discover enabled skills automatically but load them on relevance, never guaranteed. A custom agent searches only the knowledge bases attached to it.

Takeaways

• Split a runbook by use: the procedure an agent follows is a skill, the reference people look things up in is a knowledge base, and each part sits in exactly one place.
• A rule that must hold in every reply goes in the agent’s system prompt, because a skill loads only when judged relevant.
• Long documents, PDFs and Word files go in a knowledge base: an uploaded skill tops out at 50 KB as markdown or 10 MB as a .zip, a knowledge-base file at 25 MB.
• A document your team keeps editing belongs on a synced connector, swept about once an hour; uploads and crawled websites don’t auto-sync.
• Organization-wide know-how is an Organization-store skill, loaded on relevance and never guaranteed; reference for some agents is a knowledge base attached to them, up to three searched per turn.
• Material the agent should maintain goes in a knowledge base attached in Edit mode: create, update and deprecate, never delete.

Before you write the skill half of a runbook from scratch, browse the Insulin Agent Marketplace, the catalog of pre-built agents and skills you install and then edit as your own.