> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Skills
> A Skill is a reusable capability bundle — a SKILL.md instruction file plus a declared set of allowed tools — that the AI SRE agent can invoke on demand during a conversation. Install from the Marketplace, upload your own, or create one in conversation with skill-creator.
**Private beta**: AI SRE is currently in private beta. Pro or higher accounts can apply for free beta access through the [AI SRE private beta application form](https://c9xudyniiq.feishu.cn/share/base/form/shrcn0ngCfdoygiaHnAT80BfZiH); after approval, Flashduty will add your account to the whitelist. Features and the UI may change during the beta.
## Overview
***
A Skill is a **reusable capability bundle**. Every skill consists of two parts:
* A **SKILL.md** instruction document that tells the agent "when to use it, how to use it, and what steps to follow";
* The **allowed tools** declared by the skill, plus optional supporting resource files (scripts, templates, sub-documents, etc.).
A skill is packaged as a Skill archive (`.zip` or `.tar.gz`, with extension `.zip` / `.skill` / `.tar.gz` / `.tgz`) and uploaded to AI SRE; a `.tar.gz` is normalized to canonical zip at install. The archive's root directory must contain a `SKILL.md` file; all other resource files can be placed anywhere inside the archive and will be read by the agent on demand during execution.
Once enabled, the skill becomes visible and callable by the agent in the session. The agent can **autonomously decide** when to invoke a skill, or you can **explicitly trigger** it in the chat box with `/` (e.g., `/skill-creator`).
When triggering explicitly, you can append arguments: `/ arg1 arg2`. The SKILL.md body can reference positional arguments with `$1`…`$9` (whitespace-split) and the full raw remainder with `$ARGUMENTS`; these placeholders are substituted with the actual values before the turn is sent.
The difference between Skills and MCP: MCP provides **connectivity to external tools**; Skills provide **the methodology for orchestrating those tools to complete a category of tasks**. They work together — a skill declares in SKILL.md which tools it needs, including built-in tools and MCP tools in the form `mcp:server/tool`.
### SKILL.md Format
`SKILL.md` consists of two parts — YAML frontmatter (metadata) and a body (human-readable instructions for the agent) — separated by `---`:
```markdown theme={null}
---
name: skill-name
description: USE FIRST for ... — a concise description of the problem this skill solves and when to use it
version: "1.0.0"
tags:
- tag1
- tag2
author: author-name
license: MIT
allowed-tools: bash, read, task
---
## Instructions
The skill body goes here: execution steps, constraints, notes…
```
Frontmatter fields:
| Field | Type | Required | Description |
| --------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Yes | Skill name in kebab-case (lowercase letters, digits, and hyphens only, e.g. `my-skill-name`), 1–64 characters. This becomes the `/` trigger word. |
| `description` | string | No | Skill description. This is the primary signal the agent uses to select a skill — write it as an imperative "USE FIRST / prefer-over-X" statement; the more precise it is, the more reliably the skill will be invoked. |
| `version` | string | No | Version string, e.g. `1.0.0`. |
| `tags` | string\[] | No | List of tags. |
| `author` | string | No | Author name. |
| `license` | string | No | License identifier. |
| `allowed-tools` | string\[] | No | List of tools this skill is allowed to use. Leave empty for no additional restrictions. |
Tools can be specified in two ways:
* **Built-in tools**: write the tool name directly. Available built-in tools include `read`, `write`, `edit`, `bash`, `grep`, `glob`, `skill`, `mcp`, `todo`, `time`, `webfetch`, `web_search`, and others.
* **MCP tools**: write them as `mcp:server/tool` (e.g., `mcp:my-server/query`). At upload time, only the existence of the MCP server is validated; the specific tool name is verified when the MCP is loaded during a session.
The AI SRE runtime bundles a few skills that are available without installation. `flashduty` is one such reference: it uses the `fduty` CLI to cover the entire Flashduty API, allowing the agent to investigate incidents, read AI insights, query alerts, correlate changes, and more — use it as a template when writing your own skills. Another bundled skill is `github`, which the agent self-selects from `` to let AI SRE work directly inside a GitHub repository — explore code, investigate PRs and commits, and open a PR or issue on request; it requires the GitHub App (cloud) or the runner host's `gh` (BYOC). See [Apps](/en/ai-sre/apps).
## Install from Marketplace
***
Go to **Plugins → Skill** and click **Browse Marketplace** to open the skill **catalog**, where you can browse and install skill templates provided by Flashduty and Anthropic with a single click.
On the skill list page, click **Browse Marketplace** to open the catalog dialog, which displays all available skill templates in a card grid.
Use the search box at the top to search by name or description. The **Filter** in the top-right corner lets you view only "Installed" or "Not Installed" skills; **Sort** supports "Installed First" or "Name A–Z".
Click the **+** button on any uninstalled card to install it. Installation copies the template content into your account as a regular skill entry and marks its source template (shown as a `v` badge on the card to indicate "from Marketplace").
An installed card shows a gear icon in the top-right corner. Click it to open that skill's detail panel for management.
### Automatic and Manual Updates
When a Marketplace template publishes a newer version, the corresponding skill entry displays an **Update available** badge. Whether the update is applied automatically depends on whether the skill has been modified locally:
A skill that has not been locally modified after installation is **automatically** updated to the latest Marketplace version when the list loads — no manual action required. A notification appears after a successful update.
A skill that has been locally edited or re-uploaded is **skipped** by auto-update to avoid overwriting your changes. It retains the **Update available** badge, and you must **manually** click to update and confirm the overwrite.
Updating a modified skill **overwrites your local changes with the latest Marketplace version and cannot be undone**. The UI displays an "Overwrite update" confirmation dialog — proceed with caution. After reinstalling the Marketplace version, the local-modification flag is cleared and the skill returns to a clean state, re-enrolling in automatic updates.
## Custom Skills
***
In addition to installing from the Marketplace, you can upload your own skill packages. On the skill list page, click **Upload Skill** and fill in the form:
| Field | Type | Required | Description |
| -------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Owner | Team / Account | Yes | Select the scope for this skill: **Account** (visible to all members account-wide) or a specific **Team** (visible only to members of that team). To upload into a team scope, you must belong to the target team; account-level upload is limited to the account owner or admins. See "Scope" below. |
| Zip file | File | Yes | An archive containing `SKILL.md` (required) and any optional resource files. `.zip` / `.skill` / `.tar.gz` / `.tgz` archives are accepted. |
At upload time, the system automatically validates that: the archive is a valid zip, `SKILL.md` exists in the root directory, the frontmatter is parseable, `name` follows kebab-case naming, and all declared tools are valid (built-in tools exist, MCP servers exist). **Skill names must be unique within an account** — a duplicate name is rejected with a prompt to choose a different name.
All metadata other than the skill name (description, version, tags, author, tools, etc.) is parsed from `SKILL.md`'s frontmatter and does not need to be entered separately in the form.
### Overwrite upload (Replace)
When you want to replace an existing skill with a new version, the upload endpoint supports two overwrite modes. The UI presents a "Replace" confirmation dialog at the appropriate moment:
| Mode | Trigger | Behavior |
| ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Replace by name** | Upload with `replace=true` and no `skill_id` | Matches an existing skill in the account by the `name` field in the new archive's `SKILL.md` and overwrites its content. The SkillID remains the same, so all existing references (e.g., `/` triggers) continue to work. |
| **Replace by ID** | Upload with `replace=true` and a `skill_id` | Ignores the `name` field in the zip and directly targets the skill with the specified ID. Use this when you want to overwrite a specific record even if the skill has been renamed. |
Both modes return the updated skill object on success. If the target skill does not exist, a 404 error is returned — neither mode silently creates a new skill. **Without the `replace` parameter (the default), a name collision is rejected outright**; the upload endpoint never implicitly overwrites an existing skill.
### Create in conversation (skill-creator)
Besides uploading a zip, you can **create and refine skills right inside an AI SRE session**. `skill-creator` is a Flashduty-provided Marketplace skill, pre-installed into your account by default, that exists specifically to "build skills." Trigger it with `/skill-creator` in any session, or just describe what you want in natural language:
* **Create from scratch**: say "help me create a skill for troubleshooting X," or after an investigation, "turn that workflow into a skill." skill-creator clarifies your intent, drafts the `SKILL.md`, optionally sets up test cases and iterates on them, and saves the result as a skill in your account once you're happy.
* **Rewrite & optimize**: click **"Edit in Chat"** in a skill's detail panel to have skill-creator rewrite that skill; it can also tune the `description` to improve triggering accuracy.
Once the draft is ready, the agent saves it as a skill with one click. If the name conflicts with an existing skill, a "Replace" confirmation dialog appears — under the hood this invokes the replace-by-name mode (`replace=true`, no `skill_id`).
Skill archive size limits: archives saved by the agent in-conversation are capped at **10 MB**; archives uploaded via the web form or file upload in a session are capped at **100 MB**.
## Management and Inspection
***
The skill list displays each skill's **name** (with source template badge and **Update available** marker), **scope** (account or team), **version**, **enabled** toggle, and an **actions** column.
Toggle using the switch in the list or the detail panel. Only **enabled** skills are visible to the agent; a disabled skill is invisible to the agent and cannot be invoked.
Click the edit button to update the **description** and **owner** (scope). To modify skill content, download the zip, edit it, then **re-upload** (this creates a new version and marks the skill as modified).
In the detail panel, select "Replace" to overwrite the current skill content with a new zip. The SkillID remains unchanged, so any existing references (e.g., `/` triggers) continue to work.
Download the complete zip package (including `SKILL.md` and all resource files) for offline editing or backup.
Removes the skill from the current scope. Any active sessions currently using it will continue to fail until the skill is reinstalled. This action requires confirmation.
### Detail Panel
Click any row in the list to open the skill's **detail panel**:
* **Left side**: the file tree of the skill package (`SKILL.md`, `README.md`, etc. are prioritized as the default preview file).
* **Right side**: content preview of the selected file, with the skill description shown at the top.
* **Header area**: skill name (short reference in the form `skill-xxxxxx`), scope label (account / team name), source template version badge (hover to see "From Marketplace — template name `v`"), **Update available** marker, author, `version`, and the full SkillID.
* **Actions**: try in chat (injects `/` into a new session), update to latest version, edit in chat, replace, download, uninstall.
When a skill package is **too large to preview**, the detail panel displays the file size and suggests using "Download" instead.
## Scope
***
Skills share the same **two-level scope** model with other resources (Knowledge Packs, MCP, Agents, environments), divided into account level and team level:
| Scope | Visibility |
| ------------- | ------------------------------------ |
| Account level | Visible to all members account-wide |
| Team level | Visible only to members of that team |
**Edit permissions**: the account owner or an account administrator can edit any skill; team members can edit team-level skills belonging to **their own team**. There is no "creator retains rights" exception. Rows you cannot edit appear as **read-only** in the list.
**Create and reassign**: to upload or install a new team-level skill, you must belong to the target team; account-level creation is limited to the account owner or admins. When editing an existing skill, the account owner or admins can move it to any team to recover resources left behind by empty teams or departed members; regular members can move it only to teams they belong to.
**Runtime visibility**: at session start, only **account-level** skills and skills belonging to the **team bound to the current session** are loaded into the session. Skills and MCP servers from other teams are mounted into the current session on demand only after the agent reads that team's knowledge during an investigation. **The account is the sole security boundary at runtime; team is only an ownership and editing tag.**
## Related Pages
***
Use DUTY.md and Knowledge Packs to provide the agent with team context and troubleshooting experience.
Connect external tools so skills can invoke them in SKILL.md using `mcp:server/tool`.
Extend AI SRE's collaboration and task-delegation capabilities with Agents.
Explicitly trigger a skill in a session with `/`, or let the agent invoke it autonomously.
Learn about AI SRE's overall capabilities and positioning.