> ## 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.
# Plugins
> Sync skills from your repository so investigations work the way your team does.
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.
A plugin is a directory of skills that lives in one of your repositories. Connect it once and we keep it in sync, so the instructions investigations follow are the ones in your codebase, reviewed the same way you review anything else.
We use the [Claude Code plugin format](https://docs.claude.com/en/docs/claude-code/plugins). If you already keep skills in a repository for your own agents, point us at it as it is.
## What a skill looks like
Each skill lives in its own directory under `skills/`, holding a `SKILL.md` with a name and a description at the top and your instructions below.
```markdown theme={null}
---
name: checkout-triage
description: How to triage checkout failures, including which dependencies to check first.
---
Checkout runs through the payments service and the fulfillment queue. When checkout
error rates rise, check these in order:
1. The payment provider's status, which fails independently of us.
2. Queue depth on `fulfillment-worker`, which backs up before checkout visibly breaks.
...
```
The description is what we match against when deciding whether a skill fits the work at hand, so write it for the reader who has to choose: say what the skill covers and when it applies, not just what it's called.
Reference material a skill points at can sit alongside it in the same directory. Anything else the plugin contains, like commands or agent definitions you use in your own tooling, is synced but ignored. We only read skills.
## What a skill can draw on
A skill isn't limited to what's written in it. The agent following one acts on your instructions with everything the investigation can reach:
* **Your telemetry.** It can query logs, metrics, traces, and dashboards across every data source you've connected, the same way investigations query them.
* **Your connectors.** It can call any tool you've allowlisted on a [connector](/investigations/extensions/connectors), 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 work so far.** It has the incident in front of it, plus whatever the investigation has established by the time the skill runs: at the start that's the alerts and description, and later it includes search results and findings.
Write your 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 one tool breaks when that tool isn't there; a skill that names the need lets us use the best route your setup offers.
## Connecting a plugin
Plugins are synced from a GitHub or GitLab repository you've already [connected for code](/investigations/connect/code/overview).
1. From [Extensions](https://app.incident.io/~/nexus/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.
3. Choose whether every skill is available, or pick the ones you want.
Skills are read-only to us. We never write to your repository, and an investigation can't change a skill based on what
it learns.
## Keeping in sync
We re-sync every plugin hourly, and you can sync on demand. Each sync records the commit it read, so you can always tell which version of a skill an investigation actually followed.
If you chose specific skills rather than all of them, new skills added later stay off until you enable them. That way a merge to your default branch can't quietly change how investigations behave.
There are limits on what we'll sync: 500 files per plugin, 20MB in total, and 1MB per file. If a plugin exceeds them the sync fails and tells you why, rather than syncing part of it.
## Running a skill at a fixed point
By default we load a skill when its description matches the work in front of us. If you'd rather a skill ran every time, bind it to a point in the investigation with an `incident.yaml` at the root of your plugin.
```yaml theme={null}
investigations:
- when: initial_searches
skill: checkout-triage
blocks: true
```
Two points are available today. `investigation_start` runs before any evidence has been gathered, and `initial_searches` runs alongside the first round of searches, so the skill can use what they turn up. Setting `blocks: true` holds the investigation's first hypothesis until the skill has finished, so its work is available to reason from rather than arriving late.
Setting this up from the dashboard is coming, and `incident.yaml` may change before it lands. We also don't report
mistakes in the file back to you yet: a trigger we can't read is skipped while the rest of the file still applies, so
check the skill ran the way you expected after your first sync.
## Seeing how a skill is used
Every time an investigation loads a skill, we record it. Each skill has a page in [Extensions](https://app.incident.io/~/nexus/extensions) showing how often it's been loaded, which investigations used it, and whether following it helped or sent them the wrong way.
We also review the uses themselves and write up what would make the skill better: the line that sent an agent the wrong way, a description that promised more than the skill delivered, or 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.
Use it to check a new skill is being picked up at all, and to find the ones that aren't earning their place.
## Writing skills that work
* **Only include what we'd use in an incident.** Every skill in a plugin is one more for us to choose between, so one that never applies makes the right one harder to find. If something exists for your own tooling rather than for incident response, leave it out with skill selection.
* **Be specific to your environment.** 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 we see before deciding whether to load it.
* **Point at real identifiers**: service names, queue names, dashboard titles. They give an investigation something to search for.
* **Keep each skill to one job.** Several focused skills beat one long one, because we can pick the right one.
* **Say what to do when something isn't there.** Skills that assume a tool exists behave badly when it doesn't.
Start with the runbook your team actually opens during your most common incident. It's the fastest way to see whether
a skill changes how an investigation goes.
## Related
Connect an MCP server so skills have something to call.
Search runbooks and reference docs as evidence.