> For the complete documentation index, see [llms.txt](https://skyforgeai.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://skyforgeai.gitbook.io/docs/use/custom-skills.md).

# Custom Skills

SkyForge ships with 73 built-in skills covering the full ServiceNow platform. You can extend this with your own custom skills — for company-specific patterns, internal APIs, team conventions, or any domain knowledge you want the agent to carry.

There are two ways to manage custom skills: the **Skills tab in the Dashboard** (create, upload, edit, enable/disable, delete — dashboard changes apply without restarting SkyForge), or **editing files directly** on disk (see [Managing skills manually](#managing-skills-manually-file-based) below — restart behavior differs slightly from the dashboard path). Both work on the same files, so you can mix approaches — hand-edit a skill the dashboard created, or the dashboard will pick up a skill you dropped in by hand.

***

## Managing skills from the Dashboard

Open the **Skills** tab in the Hub dashboard (left nav, between Instance and Prompts).

![Skills tab — custom and bundled skills](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-26fb8f7035f60728f95c3919052f529e3f69a22c%2Fskills-tab-overview.png?alt=media)

* **Custom Skills** — anything you've created or uploaded. Each shows a toggle switch (enable/disable — takes effect immediately for the local agent, within a few seconds for external MCP clients like Claude Desktop), plus **Edit**, **Export** and **Delete**.
* **Bundled Skills** — ship with SkyForge, read-only.
* Both lists are paginated (12 per page) and searchable via the **Search skills…** box at the top.

**Creating a skill:** click **+ Create Skill**, fill in a name (lowercase, hyphens), a one-line description (this is what the agent reads to decide when to load the skill — be specific, see [Writing a good description](#writing-a-good-description) below), and the skill content in the markdown editor.

![Create Skill form with markdown editor](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-825b218d2ea402ec54a24492927fdb82e83bd4ad%2Fskills-create-form.png?alt=media)

The content editor has a small toolbar (bold, italic, heading, inline code, code block, bullet/numbered list, link) and a **Write / Preview** toggle so you can check the rendered markdown before saving.

**Uploading a skill:** click **Upload .md/.zip** and pick a file that already has valid `SKILL.md` frontmatter (`name` + `description`), or a zip containing one — useful if you're bringing in a skill written elsewhere, or one exported from another tool.

**Editing a skill:** click **Edit** on any custom skill — the form pre-fills with the actual saved content (not a blank box), so you're editing in place, not starting over.

![Edit form pre-filled with existing skill content](https://2874025704-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJEVszlHbBuPIN3VRjBS%2Fuploads%2Fgit-blob-fc5291bcf1e7292cc36d155d5b85dbf446dcb72e%2Fskills-edit-form.png?alt=media)

The edit form also carries the **Enabled** toggle in the top right and an **Export .md** button, so enabling, disabling and exporting can all be done without leaving the editor.

**No restart, ever.** Any change made through the dashboard — create, edit, toggle, delete — is picked up by the local agent instantly and by external MCP clients (Claude Desktop, etc.) within about 5 seconds.

***

## Managing skills manually (file-based)

Prefer editing files directly, or scripting skill creation? Same underlying mechanism the dashboard uses — a Markdown file with a YAML frontmatter header.

Create a file named exactly **`SKILL.md`** (case-sensitive) inside a named folder:

```
~/.config/skyforge/skills/my-skill/SKILL.md
```

**Template:**

```markdown
---
name: my-skill-name
description: >
  ALWAYS load this skill when the user mentions "keyword1", "keyword2", "keyword3".
  Be specific — the agent reads this description to decide when to load the skill.
tools:
  - tool_search
---

# My Skill Title

Write your skill content here. This is what the agent will read when the skill is loaded.
Include patterns, rules, examples, constraints — anything the agent should know.
```

### Frontmatter fields

| Field         | Required | Purpose                                                     |
| ------------- | -------- | ----------------------------------------------------------- |
| `name`        | ✅        | Unique identifier — used with the `skill()` tool            |
| `description` | ✅        | Trigger condition — agent reads this to decide when to load |
| `tools`       | Optional | List of MCP tools this skill covers                         |

### Writing a good description

The description is the most important part. The agent uses it to decide whether to load the skill. Be explicit:

```yaml
# Bad — too vague
description: Use this for API work.

# Good — specific keywords, explicit instruction
description: >
  ALWAYS load this skill when the user mentions "inmorphis API", "internal REST endpoint",
  "company integration", or any work involving our internal API gateway.
```

Use `ALWAYS`, `FIRST`, `BEFORE ANY` to signal priority. List the exact phrases a user would say.

***

## Skill locations

**Filename must be `SKILL.md` — case-sensitive.**

| Path                                         | Scope                                                                                          |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `~/.config/skyforge/skills/{name}/SKILL.md`  | Global — applies to all projects                                                               |
| `~/.config/skyforge/skill/{name}/SKILL.md`   | Global (singular — where the Dashboard writes new skills; discovered identically to `skills/`) |
| `{project}/skills/{name}/SKILL.md`           | Project-level                                                                                  |
| `{project}/skill/{name}/SKILL.md`            | Project-level (alt spelling)                                                                   |
| `{project}/.skyforge/skills/{name}/SKILL.md` | Project-level (hidden)                                                                         |

For personal or team-wide skills, use the global path (`~/.config/skyforge/skills/`). For project-specific conventions, use `{project}/skills/`.

***

## Enabling / disabling a skill

Add `enabled: false` to a skill's frontmatter to turn it off without deleting it — this is exactly what the Dashboard's toggle switch does under the hood:

```yaml
---
name: my-skill-name
description: ...
enabled: false
---
```

Omitting `enabled` (or setting it `true`) means enabled — this is the default for every existing skill, so nothing changes unless you explicitly add the field. A disabled skill is hidden from both the local agent and external MCP clients (`sn_load_skill`), but stays on disk untouched — flip it back to `true`, or delete the line, to re-enable.

***

## Verifying discovery

Skills created or edited through the **Dashboard** are picked up automatically — no restart needed (instantly for the local agent, within \~5 seconds for external MCP clients like Claude Desktop).

If you added or edited a `SKILL.md` file **by hand** instead:

* **External MCP clients** (`sn_load_skill`, used by Claude Desktop etc.) will pick it up automatically within \~5 seconds — no restart needed there either, since that path rescans the custom-skill directories on a short TTL regardless of how the file got there.
* **The local TUI/CLI agent** caches skills for the life of the process, so a manually-added file needs either a restart, or any action in the Dashboard's Skills tab (which forces a fresh scan as a side effect).

Either way, confirm it's discovered with:

```bash
cat ~/.config/skyforge/CUSTOM-SKILLS.md
```

Your skill should appear in the table. If it doesn't:

* Check the filename is exactly `SKILL.md` (not `skill.md`)
* Check the frontmatter has both `name` and `description`
* Check the path matches one of the supported locations above
* Check you haven't accidentally set `enabled: false` in the frontmatter

***

## Loading a skill in a session

The agent automatically loads skills when conversation keywords match the description. You can also load one explicitly:

> "Load the my-skill-name skill"

Or reference it directly in your message using its exact name.

***

## Example — company API skill

```markdown
---
name: acme-api-patterns
description: >
  ALWAYS load this skill when the user mentions "ACME API", "internal gateway",
  "company REST service", or any integration with our internal systems.
tools:
  - sn_create_rest_message
  - sn_create_rest_message_function
---

# ACME Internal API Patterns

## Base URL
All internal API calls go through: `https://api.acme.internal/v2`

## Authentication
Use OAuth 2.0 with client credentials. Store credentials in ServiceNow Connection Alias.

## Common endpoints
- `GET /incidents` — fetch incident list
- `POST /incidents/{id}/update` — update incident status

## Error handling
Always wrap in try/catch. Log errors with `gs.error()`. Return structured error objects.
```

***

## Using SkyForge in Claude Desktop / Claude Code

SkyForge's agent expertise can be used inside Claude Desktop, Claude Code, or other MCP clients — pairing an uploaded Claude Skill (instructions) with the SkyForge MCP server (tools). Export the orchestrator skill with `skyforge export-skills` and connect the client to the HTTP MCP server.

Full step-by-step setup — starting the server, exporting/uploading the skill, and the `claude_desktop_config.json` block — is in [SkyForge in Claude Desktop](/docs/extend/claude-desktop.md). Client config reference lives in [Running SkyForge → Connecting to the MCP server](/docs/use/running-skyforge.md#connecting-to-the-mcp-server).