> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getunblocked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Customize how Unblocked answers questions for you and your team

Use skills to give Unblocked reusable instructions for answering specific kinds of questions.
A skill can describe domain rules, response preferences, project-specific terminology, or process guidance that should apply when a matching question comes up.
Skills can apply when you ask Unblocked questions in Slack, the web app, and the Mac app.

## How it works

Unblocked skills use the Agent Skills format: a `SKILL.md` file with YAML frontmatter and markdown instructions.
The frontmatter gives Unblocked the skill name and a short description of when the skill should be used.
When a skill is relevant to your question, Unblocked loads the full instructions and follows them while answering.

Skills have two scopes:

* **Personal skills** apply only when you ask questions.
* **Shared team skills** apply to everyone on your team.

Team admins can create, edit, and delete shared team skills.
They can also promote one of their personal skills to a shared team skill.
This makes personal skills useful for prototyping, evaluating, and testing instructions before sharing them with everyone.
Any user can create, edit, and delete their own personal skills.

Skill names must be unique within each scope.
If your personal skill has the same name as a shared team skill, your personal skill applies when you ask questions.

## Create a skill

<Steps>
  <Step title="Open Skills settings">
    In the Unblocked web app, open **Settings** and select **Skills**.
  </Step>

  <Step title="Choose a scope">
    Use **My Skills** for instructions that should apply only to your questions.
    Use **Shared Team Skills** for instructions that should apply to everyone on your team.
  </Step>

  <Step title="Write the skill">
    Select **Create Skill** and enter the skill in `SKILL.md` format.
    The editor saves the raw markdown file and validates it when you create or update the skill.
  </Step>

  <Step title="Save the skill">
    Select **Create** or **Save**.
    When you create a shared team skill, Unblocked asks you to confirm because the skill affects everyone on your team.
    You can create it as a personal skill instead if you want to test it first.
  </Step>
</Steps>

## SKILL.md format

Start every skill with YAML frontmatter, followed by markdown instructions.
Only `name` and `description` are supported in frontmatter.

```markdown theme={null}
---
name: answering-onboarding-questions
description: Answers onboarding questions about repositories, services, and workflows. Use when someone asks how to get started.
---

Find the most current setup docs before answering.
```

The `name` field must use lowercase letters, numbers, and hyphens.
It must be 64 characters or fewer, cannot start or end with a hyphen, and cannot include consecutive hyphens.

The `description` field should tell Unblocked when to use the skill and when not to use it.
It must be 1024 characters or fewer and cannot contain XML tags.

The markdown body contains the instructions Unblocked loads when the skill is used.
It must not be blank and must be 10,000 characters or fewer.

## Write effective skills

Keep the description specific so Unblocked can decide when the skill applies and when it should stay out of the way.
For example, `Investigates active incidents by researching recent changes, messages, customer reports, prior incidents, and runbooks. Use when triaging incidents, summarizing impact, or analyzing follow-up work. Not intended for unrelated project planning or onboarding.` is more useful than `Helps with incidents`.

Write instructions as durable steps, checks, or preferences.
Keep activation rules in the description; use the body for the procedure Unblocked should follow after the skill has loaded.
Avoid copying large blocks of temporary project status into a skill.
If the guidance depends on a source of truth, tell Unblocked what to check instead of embedding information that will go stale.

Create a personal skill first when you are still refining the instructions.
After it works well for your own questions, a team admin can promote it to a shared team skill.

For more guidance on writing effective skills, see:

* [Agent Skills best practices for skill creators](https://agentskills.io/skill-creation/best-practices)
* [Claude skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)

## Sample skills

### Managing incidents

```markdown theme={null}
---
name: managing-incidents
description: Investigates active incidents by researching recent changes, messages, customer reports, prior incidents, and runbooks. Use when triaging incidents, summarizing impact, or analyzing follow-up work. Not intended for unrelated project planning or onboarding.
---

## Investigation flow

1. Research recent code changes and pull requests that could be related to the incident.
2. Find recent Slack messages about the affected service, feature, customer workflow, or error.
3. Find recent customer issues in issue trackers and shared Slack channels.
4. Look for similar incidents from the past and compare symptoms, causes, and resolutions.
5. Load relevant runbooks before recommending remediation steps.

## Incident summary should include

- Separate confirmed facts from hypotheses.
- Cite the sources that support each major claim.
- Call out missing evidence or conflicting signals.
- Include owners, follow-up work, and customer impact when the sources mention them.
```

### Recovering from incidents

```markdown theme={null}
---
name: recovering-from-incidents
description: Guides incident recovery by finding dashboards, rollback rules, service owners, escalation paths, and status update formats. Use during active recovery or when preparing recovery guidance. Not intended for post-incident retrospectives or unrelated operational planning.
---

## Recovery checklist

1. Identify the affected service, feature, customer workflow, and current severity.
2. Find the runbook, dashboard, alert, and recent deploy history for the affected area.
3. Check documented rollback rules before recommending a rollback, hotfix, or mitigation.
4. Identify service owners, on-call contacts, and escalation paths from team docs or schedules.
5. Find the incident update format the team already uses before drafting updates.

## When drafting updates

- Start with the safest immediate action and the evidence that supports it.
- Include dashboard links, rollback criteria, owners, and escalation targets when available.
- Clearly mark unknowns, risks, and decisions that need human approval.
- Draft updates in the team's usual incident communication format.
```

### Triaging support bugs

```markdown theme={null}
---
name: triaging-support-bugs
description: Helps triage bug reports in support Slack channels. Use when someone reports broken behavior, customer impact, or a possible regression. Not intended for feature requests or general troubleshooting questions.
---

## First response in Slack

Start by acknowledging the report and asking for the minimum information needed to route it:

- Affected customer, account, workspace, or user
- Reproduction steps
- Expected behavior and actual behavior
- When the issue started
- Screenshots, screen recordings, logs, URLs, or error messages

## Before escalating

Search for related issues, recent changes, incidents, and prior support reports. If the report is missing reproduction details or customer impact, ask for that information before opening or escalating an engineering ticket.

## Escalation handoff

- Be concise, helpful, and specific about what information is still needed.
- Separate customer-visible symptoms from internal hypotheses.
- Include links to matching tickets, pull requests, incidents, or docs.
- Summarize the triage before escalating so engineers can quickly understand impact and reproduction steps.
```

### Writing release summaries

```markdown theme={null}
---
name: writing-release-summaries
description: Turns pull requests and issues into consistent release notes. Use when summarizing shipped work for customers, support, sales, or internal stakeholders. Not intended for deep technical design reviews.
---

## Inputs to collect

Gather the relevant pull requests, issues, changelog entries, and release branch details. Check whether the audience is customers, support, sales, leadership, or engineering before choosing the level of detail.

## Release note structure

Use this structure unless the requester asks for a different format:

1. Customer-facing highlights
2. Bug fixes
3. Internal changes
4. Breaking changes
5. Follow-ups

## Writing rules

- Use a consistent heading structure for every release summary.
- Keep customer-facing items clear and non-promotional.
- Include breaking changes and required follow-up actions before lower-priority details.
- Link each summary item to the source pull request, issue, or document.
```