Working with Skills

Skills are on-demand knowledge documents that teach Fabric how to handle specific tasks — from generating ASCII art to managing GitHub PRs. This guide walks you through using them day to day.

For the full technical reference, see Skills System.

---

Finding Skills

Every Fabric installation ships with bundled skills. See what's available:

# In any chat session:
/skills

# Or from the CLI:
fabric skills list

This shows a compact list with names and descriptions:

ascii-art         Generate ASCII art using pyfiglet, cowsay, boxes...
arxiv             Search and retrieve academic papers from arXiv...
github-pr-workflow Full PR lifecycle — create branches, commit...
plan              Plan mode — inspect context, write a markdown...
excalidraw        Create hand-drawn style diagrams using Excalidraw...

Searching for a Skill

# Search by keyword
/skills search docker
/skills search music

The Skills Hub

Official optional skills (heavier or niche skills not active by default) are available via the Hub:

# Browse official optional skills
/skills browse

# Search the hub
/skills search blockchain

Hub search also covers external community sources — skills.sh, curated GitHub skill packs, ClawHub, LobeHub, and more. The Skills Ecosystem Directory maps these sources with trust tiers and licensing notes; everything installed from an external source passes through the skills guard security scan and lands in quarantine review first.

---

Using a Skill

Every installed skill is automatically a slash command. Just type its name:

# Load a skill and give it a task
/ascii-art Make a banner that says "HELLO WORLD"
/plan Design a REST API for a todo app
/github-pr-workflow Create a PR for the auth refactor

# Just the skill name (no task) loads it and lets you describe what you need
/excalidraw

You can also trigger skills through natural conversation — ask Fabric to use a specific skill, and it will load it via the skill_view tool.

Progressive Disclosure

Skills use a token-efficient loading pattern. The agent doesn't load everything at once:

1. Prompt taxonomy — large catalogs contribute only category counts to the cached system prompt (372 bytes for the current bundled catalog), not every description.
2. skills_list(query="task") — deterministically ranks up to eight candidates from names, descriptions, and verified trigger/non-trigger declarations. It does not call a model.
3. skill_view(name) — loads the full SKILL.md for the selected skill.
4. skill_view(name, file_path) — loads one supporting reference only when needed.

Catalogs with 32 or fewer skills stay inline for convenient browsing. Larger catalogs switch automatically to the bounded taxonomy. This keeps prompt cost bounded while preserving exact-name slash commands and on-demand discovery.

---

Installing from the Hub

Official optional skills ship with Fabric but aren't active by default. Install them explicitly:

# Install an official optional skill
fabric skills install official/research/arxiv

# Install from the hub in a chat session
/skills install official/creative/songwriting-and-ai-music

# Install a single-file SKILL.md directly from any HTTP(S) URL
fabric skills install https://sharethis.chat/SKILL.md
/skills install https://example.com/SKILL.md --name my-skill

What happens:

1. The skill directory is copied to ~/.fabric/skills/
2. It appears in your skills_list output
3. It becomes available as a slash command

tip

Installed skills take effect in new sessions. If you want it available in the current session, use /reset to start fresh, or add --now to invalidate the prompt cache immediately (costs more tokens on the next turn).

Verifying Installation

# Check it's there
fabric skills list | grep arxiv

# Or in chat
/skills search arxiv

---

Plugin-Provided Skills

Plugins can bundle their own skills using namespaced names (plugin:skill). This prevents name collisions with built-in skills.

# Load a plugin skill by its qualified name
skill_view("superpowers:writing-plans")

# Built-in skill with the same base name is unaffected
skill_view("writing-plans")

Plugin skills are not listed in the system prompt and don't appear in skills_list. They're opt-in — load them explicitly when you know a plugin provides one. When loaded, the agent sees a banner listing sibling skills from the same plugin.

For how to ship skills in your own plugin, see Build a Fabric Plugin → Bundle skills.

---

Configuring Skill Settings

Some skills declare configuration they need in their frontmatter:

metadata:
  fabric:
    config:
      - key: tenor.api_key
        description: "Tenor API key for GIF search"
        prompt: "Enter your Tenor API key"
        url: "https://developers.google.com/tenor/guides/quickstart"

When a skill with config is first loaded, Fabric prompts you for the values. They're stored in config.yaml under skills.config.*.

Manage skill config from the CLI:

# Interactive config for a specific skill
fabric skills config gif-search

# View all skill config
fabric config show | grep '^skills\.config'

---

Creating Your Own Skill

Skills are just markdown files with YAML frontmatter. Creating one takes under five minutes.

1. Create the Directory

mkdir -p ~/.fabric/skills/my-category/my-skill

2. Write SKILL.md

~/.fabric/skills/my-category/my-skill/SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
metadata:
  fabric:
    tags: [my-tag, automation]
    category: my-category
---

# My Skill

## When to Use
Use this skill when the user asks about [specific topic] or needs to [specific task].

## Procedure
1. First, check if [prerequisite] is available
2. Run `command --with-flags`
3. Parse the output and present results

## Pitfalls
- Common failure: [description]. Fix: [solution]
- Watch out for [edge case]

## Verification
Run `check-command` to confirm the result is correct.

3. Add Reference Files (Optional)

Skills can include supporting files the agent loads on demand:

my-skill/
├── SKILL.md                    # Main skill document
├── references/
│   ├── api-docs.md             # API reference the agent can consult
│   └── examples.md             # Example inputs/outputs
├── templates/
│   └── config.yaml             # Template files the agent can use
└── scripts/
    └── setup.sh                # Scripts the agent can execute

Reference these in your SKILL.md:

For API details, load the reference: `skill_view("my-skill", "references/api-docs.md")`

4. Validate It

Check the skill's SKILL.md and, when present, its optional governance contract:

fabric skills validate ~/.fabric/skills/my-category/my-skill

Skills without skill.contract.yaml remain valid during migration and are reported as legacy. Use strict mode when a team or CI policy requires every skill to carry a contract:

fabric skills validate ~/.fabric/skills/my-category/my-skill --require-contract
fabric skills validate ~/.fabric/skills/my-category/my-skill --require-contract --json

See Creating Skills for the contract schema.

5. Test It

Start a new session and try your skill:

fabric chat -q "/my-skill help me with the thing"

The skill appears automatically — no registration needed. Drop it in ~/.fabric/skills/ and it's live.

info

The agent can also propose skill changes using skill_manage. /learn and background-review changes are saved as quarantined drafts, not activated immediately. Inspect with /skills diff <id>, then use /skills approve <id> or /skills reject <id>. Promotion activates on the next session by default; add --now only when immediate shared-index refresh is worth invalidating the prompt cache.

---

Per-Platform Skill Management

Control which skills are available on which platforms:

fabric skills

This opens an interactive TUI where you can enable or disable skills per platform (CLI, Telegram, Discord, etc.). Useful when you want certain skills only available in specific contexts — for example, keeping development skills off Telegram.

---

Skills vs Memory

Both are persistent across sessions, but they serve different purposes:

	Skills	Memory
What	Procedural knowledge — how to do things	Factual knowledge — what things are
When	Loaded on demand, only when relevant	Injected into every session automatically
Size	Can be large (hundreds of lines)	Should be compact (key facts only)
Cost	Zero tokens until loaded	Small but constant token cost
Examples	"How to deploy to Kubernetes"	"User prefers dark mode, lives in PST"
Who creates	You, the agent, or installed from Hub	The agent, based on conversations

Rule of thumb: If you'd put it in a reference document, it's a skill. If you'd put it on a sticky note, it's memory.

---

Tips

Keep skills focused. A skill that tries to cover "all of DevOps" will be too long and too vague. A skill that covers "deploy a Python app to Fly.io" is specific enough to be genuinely useful.

Review agent-authored drafts. After a complex multi-step task, Fabric may offer a reusable skill change. Check the diff before promotion so durable workflow evidence is preserved without turning one-off behavior into active guidance.

Use categories. Organize skills into subdirectories (~/.fabric/skills/devops/, ~/.fabric/skills/research/, etc.). This keeps the list manageable and helps the agent find relevant skills faster.

Update skills when they go stale. If you use a skill and hit issues not covered by it, tell Fabric to update the skill with what you learned. Skills that aren't maintained become liabilities.

---

For the complete skills reference — frontmatter fields, conditional activation, external directories, and more — see Skills System.