Skip to main content
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

1

Open Skills settings

In the Unblocked web app, open Settings and select Skills.
2

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.
3

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.
4

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.

​
SKILL.md format

Start every skill with YAML frontmatter, followed by markdown instructions. Only name and description are supported in frontmatter. 
---
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:

​
Sample skills

​
Managing incidents

---
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.
---

## Procedure

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.

## Response guidelines

- 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.