Skip to main content
Extensions are currently in Private Beta. Get in touch by email or our shared Slack channel if you’d like to try them out.
A plugin is a directory of skills and docs that lives in one of your repositories. Connect it once and we keep it in sync, so the instructions our agents follow are the ones in your codebase, reviewed the same way you review anything else. Our agents already know how to investigate: they have your telemetry, code, and docs through Nexus, and they know what Postgres is or what a Kubernetes pod restart means. What they don’t know is your setup. A skill teaches them that: which replication slots serve the production app and which feed analytics, the naming convention your services use for database users, which of a connector’s tools matters and how to read what it returns.
The quickest way to a working plugin is the official incident.io skills plugin, installed in your coding agent. It writes skills for the environment our agents run in, an incident with telemetry and connectors rather than a developer’s machine, so agents can follow them more easily. It can also create, register, and verify a plugin for you.

​
What a plugin contains

​
Skills

Skills are the part we act on, and a plugin needs at least one to sync. Each lives in its own directory under skills/, holding a SKILL.md with a name and description at the top and your instructions below.
skills/feature-flags/SKILL.md
The description is what we match against when deciding whether a skill fits the work at hand, and it’s the only thing read before that decision. Write it for the reader who has to choose: say what the skill covers and when it applies, not just what it’s called.

​
Docs

Docs are everything else in the plugin: architecture docs describing what a system is and where it runs, reference files a skill sends the agent to when it needs detail, data files a skill reads. Keep detail a skill only sometimes needs in files alongside it and link to them from SKILL.md, so the agent loads a short set of instructions and reads deeper only when the job calls for it. Markdown in your plugin is also indexed alongside your connected documentation, so an agent can find it by searching as well as by following a skill’s link. Architecture docs describe what each system is: where it runs, what it depends on, and the exact names of its clusters, hostnames, queues, and buckets. Agents read them to work out what a system is before debugging it. A structure like this works well, with one directory per system as responders think of them during an incident, and a README at the root that lists the systems and maps common questions to the file that answers them:
Architecture docs should name stable things exactly and, for values that change often, like replica counts, say where the live value lives rather than quoting it. Skills own procedures and architecture docs own facts, so a doc links to the skill that handles a failure rather than describing the fix. If your team already keeps architecture docs elsewhere, leave the detail there and add a summary to the plugin so agents know the system exists and what it’s called. The official skills plugin can write these for you, starting with an interview about what each system actually is.
Plugins use the open agent skills and Claude Code plugin formats, so a plugin you write for us also loads in Claude Code, Cursor, Codex, and other coding agents, and the general advice on writing good skills applies here too. Your team can follow the same skills at their terminal that our agents follow during an incident.

​
What a skill can draw on

A skill followed by our agents runs inside incident.io, so the agent acts on your instructions with every source and capability the run can reach:
  • Your telemetry. It can query logs, metrics, traces, and dashboards across every data source you’ve connected through Nexus.
  • Your connectors. It can call any tool you’ve allowed on a connector, so a skill can direct it at systems we have no native integration for.
  • Your code and documentation. It can search connected repositories, recent changes, and the docs you’ve synced.
  • The incident. In an investigation it has the incident in front of it, plus whatever has been established by the time the skill runs: the alerts and description at the start, and search results and findings later on.
Write instructions as the thing you want established, not the tool you’d use. “Work out whether a deploy landed inside the window” can be answered from your change events, a connector to your CI system, or your code history, whichever you’ve connected. A skill that names a single tool stops working when that tool isn’t connected, so say what you want established and let the agent pick the route. That also lets the same skill work in your coding agent, where the tools are set up differently.

​
Triage skills

Most skills wait to be picked: an agent loads one when its description matches the work in front of it. Skills that own a system or a class of incident get used earlier than that. At the start of every investigation, alongside the initial searches, we read your skills’ names and descriptions against everything we know about the incident: the alert, the description, how it’s classified, what its fields record. A skill that owns the incident is followed there and then, and its findings are in hand when the first hypothesis is formed. That’s how you get custom triage: encode where an investigation of a given kind should look first, and the first hypothesis comes back faster and more accurate. Nothing marks a skill as a triage skill. The name and description are all we read when deciding, so:
  • Name the skill after what it owns. checkout-queue or single-customer says what it covers. incident-triage covers everything, so it matches nothing specific.
  • A subject can be a class of incident, not just a system. If your team handles one kind of incident the same way every time, own that class and say so in the description.
  • Use the words your organization uses. Selection matches against the incident’s own alert, description, and fields. A skill named for a severity you don’t use by that name matches nothing.
  • Write every branch down. The procedure runs unattended, with nobody to answer a question or pick between two options. A step that assumes a console or a teammate stalls it.

​
Adding a plugin

Plugins sync from a GitHub or GitLab repository you’ve already connected for code. The plugin can live at the repository root or under a subpath, such as plugins/ops/, so it sits comfortably inside a repository you already keep operational content in. If you don’t have a plugin yet, your coding agent can create one for you, along with its first skill, and register it. See the official skills plugin. To add one by hand:
  1. From Extensions, add a plugin and choose the repository.
  2. We scan the default branch for plugin directories, looking for either a .claude-plugin/plugin.json or a skills/ directory containing at least one SKILL.md. You’ll see what we found, with the skills in each. For a repository too large to scan, name the plugin’s directory instead.
  3. Choose whether every skill is available, or pick the ones you want.
The first sync starts straight away. A healthy plugin shows a completed sync with its skills listed. An unreachable repository or a malformed plugin shows a sync error with the reason, so you can fix it in the repository and sync again.
We only ever read your repository. We never write to it, and an investigation can’t change a skill based on what it learns.

​
Choosing which skills are live

Every skill in a plugin is one more for an agent to choose between, so a skill that never applies during an incident makes the right one harder to find. If your repository holds skills for your own tooling that have no place in an incident, leave them out of the selection. Selection is either automatic or by hand. Automatic means every skill in the current version is available, including ones added later. When you pick skills by hand, a skill merged later stays off until someone enables it, so a merge to your default branch can’t change how Investigations behave without someone choosing that. A skill that’s off is withheld from agents entirely, including its reference files.

​
Keeping in sync

We re-sync every plugin hourly, and you can sync on demand from the dashboard or by asking your coding agent. Syncs read the default branch, so a change appears once your branch merges, not before. Each sync pins the plugin to one commit, so a skill can’t change under an investigation that’s already following it. The plugin list shows when each plugin last synced, and links from the dashboard into your repository point at that commit. There are limits on what we’ll sync: 500 files per plugin, 20 MB in total, and 1 MB per file. If a plugin exceeds them the sync fails and tells you why, rather than syncing part of it. If you work with the official skills plugin, your coding agent registers the plugin and triggers the first sync as part of creating it. See Syncing to incident.io.

​
Creating and maintaining plugins

We recommend writing and maintaining your plugins with the official incident.io skills plugin installed in your coding agent. It checks your existing setup before drafting, verifies a skill against a realistic scenario before you merge, and reads the usage feedback below when you ask it to improve a skill.

​
Adapting existing runbooks

Most teams already have runbooks: procedures for debugging incidents, written for a person, living in Notion or Confluence or as markdown in a repository. They’re the best starting material for a plugin, and connecting them as documentation already lets agents find them. What connecting them doesn’t do is make them work as instructions. A runbook written for a responder tends not to work for an agent. “Ask the on-call DBA to check the replica” or “open the dashboard and look for the spike” assume a person with a laptop and colleagues. The agent has tools, not a laptop, and nobody to ask. So the work of building a plugin is mostly translation: take the procedures your team actually opens during incidents and rewrite them as skills, saying what to establish and how to read what comes back. The translation is rarely one to one. Five runbooks about the same system often become one skill whose description says which cases it covers, with the detail of each case in a reference file the agent reads only when that case applies. That keeps the skill short, with a description specific enough to be picked for the right incidents. The official plugin’s skill-authoring skill walks through this, and the plugin can find the runbooks you have wherever they live and curate new material from closed incidents.

​
Writing skills that work

A skill for incident.io is an ordinary agent skill, so the general advice on writing skills applies. What makes one worth having is the expertise specific to your organization, which our agents can’t get anywhere else.
  • Be specific to your environment. Our agents already read logs, query metrics, and search code on their own, so a skill that says to check logs adds nothing. A skill that names the service, the dashboard, and the failure mode does.
  • Say when the skill applies in the description. That’s the only thing read before deciding whether to load it.
  • Point at real identifiers: service names, queue names, dashboard titles. They give an agent something to search for.
  • Keep each skill to one subject. Several focused skills beat one long one, because the right one can be picked.
  • Say what to do when something isn’t there. Skills that assume a tool exists behave badly when it doesn’t.
  • Say how to read the results. Does an empty result mean nothing happened or that the source couldn’t be asked? Misreading zero as failure, or failure as zero, is the most common way a correct procedure produces a wrong answer.

​
Seeing how a skill is used

Every time an agent loads a skill, we record it. Each skill has a page in Extensions showing how often it’s been loaded, in which investigations and chats, whether the agent followed it, and whether following it helped. We also review the uses themselves and write up what would make the skill better: the step that sent an agent the wrong way, a description that promised more than the skill delivered, a tool the skill reached for that you haven’t connected. Each point quotes the part of your skill it’s about, so you know exactly what to edit, and it’s marked resolved once that text changes. Your coding agent reads the same feedback when you ask it to improve a skill. Use it to check a new skill is being picked up at all, and to find the ones that aren’t being used.

​
FAQs

They work together, and most teams want both. Connecting your docs lets agents search everything your team has written, wherever it lives, and cite it as evidence. A skill is instructions an agent follows rather than knowledge it reads: it’s loaded when it applies and acted on, and we track whether following it helped. Docs in a plugin get both treatments, since they’re indexed for search as well as being there for skills to point at.
You can, and the format is the same. Bear in mind that registering a plugin makes every selected skill available to agents during real incidents, and content written for your coding agent may not be what you want followed there. Most teams create a plugin for incident.io and adapt the skills that belong in an incident, rather than syncing an existing tree as it stands.
Start with one. Which plugin a skill lives in has no effect on whether it’s selected, so the split is about who owns and reviews the content, not about how agents use it. Add a second plugin when a different team wants to own its own.
The agent carries on and does the best it can with what it has. You don’t have to notice this yourself: the usage feedback flags when a skill reached for a tool that wasn’t there.

Official skills plugin

Create and improve your plugin with your coding agent.

Connectors

Connect an MCP server or HTTP API so skills have something to call.

Documentation

Search runbooks and reference docs as evidence.

Extensions overview

How plugins and connectors fit together.