--- title: "Skills" description: "Write down how your team does a task so Halon follows it, copy one of Firefight's skills to change it, and decide on the skills Halon proposes." canonical: https://firefight.app/docs/ai/skills --- # Skills A skill is a short recipe Halon follows for a task: when it applies, the tools it needs, and numbered steps. Halon follows a skill when a question fits it. Firefight ships skills for its own tasks and for each tool you connect. You can add your own beside them, change how Halon does one of Firefight's by copying it, and accept skills Halon proposes from a chat. ## The Skills page Go to **Halon → Skills**. The page has three parts. | Part | What it shows | |---|---| | Proposed by Halon | Skills Halon proposed from a chat that nobody has decided on yet, with why and what would change. It shows only while a proposal waits | | Your skills | The skills you wrote, imported or copied, each with its version and who wrote it | | Firefight's library | Firefight's skills and the skills of the tools you connected, each with its version | Everyone in the workspace can read the page. Adding, changing and deleting skills needs the **Skills** permission, which admins have and can grant on the [Permissions](https://firefight.app/docs/gateway/permissions.md) page. ## Writing a skill Choose **New skill**, or **Write your first skill** before you have any, and fill in: - **Name**, in lowercase words joined by underscores, such as `rotate_api_keys`. Halon finds the skill by this name. - **When Halon uses it**, one sentence, such as "Someone asks to rotate the API keys of a service". - **Tools**, the tools its steps call. The list holds every tool Halon can use in your workspace, Firefight's own and each connected tool's. - **Steps**, numbered, with each tool named in backticks. When you edit a skill, **What changed** is optional and is kept with the new version in its history. A name Firefight's library already uses is refused. To change how Halon does one of Firefight's tasks, copy that skill instead. A skill never widens anyone's access. Loading one makes its tools callable only as far as the person asking, or the agent running, is already allowed to use them. A tool someone may not use stays out of reach, and Halon says so. Firefight refuses a skill whose words look like they hold a password, key or token. Name the connection that holds a credential instead. ## Versions and history Every save is a new version. Choose **History** on a skill to see each version, who wrote it and why, and what it said. **Bring back version** on an earlier version makes it the next version, so nothing in the history is ever lost. If someone else saved the skill while you had it open, your save is refused and the page asks you to look again. ## Copying one of Firefight's skills Choose **Copy** on a skill in Firefight's library. Your copy keeps the name and Halon uses it in place of Firefight's from then on, so changing the copy changes how Halon does that task in your workspace. When Firefight ships a newer version of a skill you copied, your copy is marked with the new version's number, such as **Version 2 is out**. Open it to see what Firefight changed since you copied it. Your copy is never changed for you. - **Take Firefight's version** replaces what your copy says with the new version. What it said before stays in its history. - **Keep mine** leaves your copy as it is. You are told again when a newer version comes out. Deleting a copy makes Halon use Firefight's skill again. ## Skills Halon proposes Ask Halon in a chat to save what it just did as a skill, and it proposes one. Halon also proposes a change when you work out a better way to do something a skill already covers, whether the skill is yours or one of Firefight's. A change to one of Firefight's becomes your copy of it once accepted. Nothing changes until someone accepts. Each proposal shows Halon's reason and what the skill says now beside what Halon would make it say. | Where | How you decide | |---|---| | A dashboard chat | A card under Halon's answer, with **Add skill** (or **Accept change** for a change), **Dismiss** and **Edit it on the Skills page** | | A Slack thread, such as an incident channel or your direct messages with Firefight | A message in that thread, with **Accept**, **Dismiss** and **Edit on the Skills page** | | The Skills page | Under **Proposed by Halon**, with **Add skill** or **Accept change**, **Edit first** and **Dismiss** | - **Add skill** or **Accept change** (**Accept** in Slack) makes it live as Halon wrote it. - **Edit first** opens it in the skill editor, and what you save goes live as your version. Halon's words stay in the history. - **Dismiss** leaves your skills as they are. Wherever someone decides, the card, the Slack message and the page all show who decided. Accepting from Slack needs the same **Skills** permission as the page, and a proposal someone overtook, because the skill changed since Halon wrote it, can only be edited first or dismissed. Halon is told which you chose the next time it answers in that chat. ## Importing and exporting Skills move between workspaces and other agents as `SKILL.md` files. - **Export SKILL.md** on any of your skills, or on any skill in Firefight's library, downloads it. - **Import SKILL.md** reads a file. A file named for one of your skills becomes that skill's next version, and one named for one of Firefight's becomes your copy of it. Anything else becomes a new skill. A file from another agent works as long as its front matter has a `name`, and a `description` or `when` saying when the skill is used. Firefight reads the tools from `tools`, or from `allowed-tools` when there is no `tools`, and refuses a file that names a tool your workspace does not have. ## Turning a skill off The switch at the start of each row turns a skill off without deleting it or its history. While it is off, Halon no longer loads it, and turning it back on brings it back as it was. - A copy of one of Firefight's skills that is off gives Firefight's skill of that name back, so Halon carries on with Firefight's way. - A workflow step that runs a skill of your own that is off is refused when the workflow is published, and fails when it runs, saying the skill is off. The page asks before turning off a skill a workflow runs, and says how many workflows that is. ## From the API and AI agents Your skills are also reachable outside the dashboard, with the same permission and the same rules: - The [REST API](https://firefight.app/docs/api/overview.md) has `GET` and `POST /api/v1/skills`, and `GET`, `PATCH` and `DELETE /api/v1/skills/{id}`. An update changes only what you send, as a new version, and sending the `version_id` you read refuses a change made over someone else's, turning the skill on or off included. Send `enabled` as `true` or `false` to add a skill switched off or to turn one off or on. Any other value is refused with a 422 that says "enabled should be true or false." - The [MCP server](https://firefight.app/docs/api/mcp-server.md) has `list_skills`, `get_skill`, `upsert_skill` and `delete_skill`, for agents connected to your workspace. `upsert_skill` also turns a skill on or off, and adds a new one switched off when you ask it to. ## Deleting a skill Choose **Delete** on a skill and confirm. The confirmation says how many versions go with it. A skill of your own that one of your workflows runs cannot be deleted, and the menu says how many workflows run it. Take it out of those workflows first. For the same reason, a skill a workflow runs keeps its name. A copy of one of Firefight's skills can always be deleted. Halon, and any workflow that runs it, goes back to Firefight's skill of that name.