> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Official skills plugin
> Build plugins that work well with our agents, using your own coding agent and the open source incident.io skills plugin.
Extensions are currently in **Private Beta**. Get in touch by [email](mailto:support@incident.io) or our shared Slack
channel if you'd like to try them out.
The [incident.io skills plugin](https://github.com/incident-io/skills) is an open source plugin for your coding agent. Install it in Claude Code, Cursor, Codex, or another agent that reads the plugin format, and your agent learns how to build [extensions](/investigations/extensions/overview) that work well with our agents: what makes a skill get selected and followed, how to check your existing setup before drafting, how to register and sync a plugin, and how to read the feedback we record about each skill once it's live.
The plugin bundles the [incident.io MCP server](/ai/remote-mcp), which is how your agent reads your plugins, connectors, and skill feedback, and registers and verifies changes.
## Installing
Install the plugin in your coding agent following the [installation instructions](/ai/remote-mcp#install-the-plugin) on the remote MCP server page, which cover Claude Code, Cursor, Codex, VS Code, and other agents. The first time a skill uses the incident.io connection, your agent will ask you to sign in to your incident.io account.
These skills need a large model. Run them on Claude Opus, GPT-5, or equivalent. Smaller models follow the workflows
unreliably, and the skills say so when they detect one.
## What the plugin gives you
A set of skills, each owning one job. Your agent picks the one that fits what you ask, or you can invoke one directly with `/incident-io:`. The three you'll use most:
* **`extensions`** is the entrypoint. It reads your current setup, works out whether a plugin or a connector solves the problem you describe, scaffolds and registers a plugin, and hands off to the skill that owns the rest.
* **`skill-authoring`** writes a new skill from your team's knowledge, verifies it before it ships, and improves an existing skill from the usage feedback we record.
* **`doctor`** reviews the health of your setup: sync failures, skills that load but don't get followed, feedback issues worth acting on. It reports and points you to the fix, and never edits anything.
Other skills cover turning runbooks into skills, writing architecture docs, and reviewing what your extensions did over a period. The [repository README](https://github.com/incident-io/skills) has the current list.
The plugin carries our guidance, not your content. Your skills and docs live in your own repository, next to the code they describe and reviewed like it.
## Getting started
The guides below run in your coding agent. You can invoke a skill directly, or just say what you want in plain language and let the agent pick the one that fits.
### Creating your first plugin
Invoke the `extensions` skill and your agent checks what you already have before proposing anything. It will confirm every file and registration with you before creating it.
```text title="Example session" wrap nocopy highlight={1,10} theme={null}
> /incident-io:extensions
● I'm checking your configuration before we get started.
Plugins: none registered
Connectors: Sentry, Grafana, GitHub (all healthy)
You don't have a plugin yet. What would you like to build first? It's usually easiest to begin with a specific use case, for example a skill that triages one class of incident.
> A triage skill for our checkout failures
```
From here the agent asks about the case you have in mind, drafts the skill from what you tell it, and proposes where in your repository the plugin should live. It's your knowledge that goes in: the agent asks for the specifics an experienced responder would know rather than writing a generic skill about a topic. See [Writing skills that work](/investigations/extensions/plugins#writing-skills-that-work) for what makes the difference.
You can also start with reference material about your architecture, or just create an empty placeholder to fill in later.
```text title="Example session" wrap nocopy highlight={1,9,13} theme={null}
> /incident-io:extensions create an empty plugin and then interview me to create architecture docs
● Created ops/.claude-plugin/plugin.json and ops/README.md. An empty plugin needs the manifest, or a sync finds nothing to read.
Now the docs. I've read your repo rather than guessing, and I can see a Go service in server/, a React app in web/, and Terraform deploying both.
You call this "the platform". Is that the Go service, the service plus the web app, or the whole deployable unit?
> The Go service. The web app is a separate thing.
● Noted. When the web app breaks, do the same people check the same dashboards as when the Go service breaks?
> Different teams entirely.
● Then they're two systems, and each gets its own directory. Next question: where does the Go service actually run?
```
### Syncing to incident.io
The agent registers the plugin as part of creating it, and the first sync starts right away. Two things need to be true for it to land:
* **The repository is connected to incident.io.** Plugins sync through your connected GitHub or GitLab integration, so [connect the code repository](/nexus/code/overview) first.
* **Your changes are on the default branch.** Syncs read the default branch, so the plugin's skills appear once your branch merges, not before.
To confirm it landed, open [Extensions](https://app.incident.io/~/nexus/extensions) in your dashboard, or just ask your agent. A healthy plugin shows a completed sync with your skills listed; an unreachable repository or malformed plugin shows a sync error with the reason. From then on we re-sync hourly, and your agent can trigger a sync whenever you push a change you want picked up now. See [Plugins](/investigations/extensions/plugins#keeping-in-sync).
### Adding a skill
Once you have a plugin, the flow is shorter, because the setup is done. The agent still checks first: whether a similar skill already exists that should be edited instead, and whether the systems the skill would lean on are actually connected.
```text title="Example session" wrap nocopy highlight={1} theme={null}
> /incident-io:extensions I want a skill for triaging Stripe issues
● Checking your setup for this:
Plugin ops: synced 12 minutes ago, 4 skills
Skill selection: automatic, so a new skill goes live when it merges
Stripe: not connected
Nothing you've connected can reach Stripe today, so a skill naming it would have nothing to call. You can connect your Stripe MCP server first, or write the skill against what you already have. Which would you prefer?
```
Connecting a system is done in the dashboard, as a [connector](/investigations/extensions/connectors). The agent links you there and carries on with what exists.
### Turning runbooks into skills
If your team already has runbooks, ask your agent to find them and it looks wherever they live: your repository, a Notion or Confluence space you've [connected as documentation](/nexus/documentation), or somewhere you point it at. Ask it to turn a runbook into a skill and `skill-authoring` rewrites the procedure for an agent: what to establish, which tools to use, how to read what comes back, and what to do when a step can't be completed. Several runbooks about the same system usually become one skill with a reference file per case. See [Adapting existing runbooks](/investigations/extensions/plugins#adapting-existing-runbooks) for why the translation matters.
## Verifying a skill before you merge
Before a skill ships, the agent can verify it against incident.io. A fresh agent that has the skill, and no knowledge of what you meant it to do, is handed a realistic request, and what it does is graded against what should have happened. Nothing needs to merge first: the agent can verify a change to a plugin that's already synced, the files on your disk before they're committed anywhere, or a branch you've pushed. Uploaded files are held to the same [size limits](/investigations/extensions/plugins#keeping-in-sync) as a sync.
```text title="Example output" wrap nocopy theme={null}
● Verified skills/stripe/SKILL.md on branch stripe-skill:
Loaded on "checkout payments are failing": pass
Told a Stripe outage apart from our own errors: pass
Scoped the failures to a time window: fail
The "recent failures" step reads two ways. Suggested edit, anchored to the line it came from:
was: "look for recent payment failures"
now: "list failed payment intents from the last 30 minutes, grouped by decline code"
Apply it and verify again?
```
By default the verification simulates calls to your telemetry and connectors, which tells you the skill routes to the right tool. Ask for live reads when you want to know the tool answers the way the skill assumes. Writes are never made during a verification.
## Improving skills over time
### From real usage
Every time an agent loads a skill during an incident or a chat, we record it and, once the run is scored, assess it: was the skill followed, did following it help, and what specifically held it back. You can read this on each skill's page in the dashboard, described under [Seeing how a skill is used](/investigations/extensions/plugins#seeing-how-a-skill-is-used). Ask your agent to improve a skill and `skill-authoring` reads the same feedback, fixes the issues by theme without undoing what the feedback credits, and verifies the fix where it can.
```text title="Example session" wrap nocopy highlight={1} theme={null}
> Improve the checkout-queue skill from its feedback
● Reading feedback for checkout-queue: 31 loads, 24 assessed.
Open issues:
1. Step 3 says "check the queue depth" without naming which queue. Agents picked
the retry queue in 4 of 6 runs; the skill meant fulfillment-worker. (6 runs)
2. The description promises payment provider status, but nothing in the body
covers it. (3 runs)
Strengths to keep:
- The "compare against the same hour last week" step is credited in 9 runs.
I'll fix both issues and leave the comparison step alone. Want to see the diff first?
```
### Keeping your setup healthy
Run `doctor` on a schedule as well as on demand. It reviews your plugins, skills, and connections and says what to fix: a plugin that stopped syncing, a skill that keeps loading but never gets followed, feedback issues worth acting on. It never edits anything itself, so it's safe to run weekly.
The repository also has a review skill that reports what your extensions did over a period, the skill loads that changed an investigation and the incidents no skill covered, which you can point at a channel for a regular digest.
## Related
What a plugin contains, and how skills are selected and synced.
Connect an MCP server or HTTP API so skills have something to call.
Installation for each coding agent, and everything else the MCP server can do.
How plugins and connectors fit together.