Skills

A skill is a directory containing SKILL.md. fx discovers skill metadata at startup, but loads the instructions only when you or the agent invokes that skill.

Browse and invoke

Open the interactive skill catalog:

Use the source tabs and search field to filter results. Press enter to insert the selected skill into the prompt. You can also type $ in the composer to search skills directly.

Inspect one skill without invoking it:

Duplicate names are preserved. A name-only tool call works when one visible skill matches; otherwise the caller must use the advertised location.

Discovery roots

fx checks skills/ and these hidden directories from the workspace upward, stopping before your home directory:

skills/
.opencode/skills/
.codex/skills/
.claude/skills/
.agents/skills/
.claw/skills/

It then checks user roots:

~/.fx/skills/
~/.config/opencode/skills/
~/.codex/skills/
~/.claude/skills/
~/.agents/skills/
~/.claw/skills/

Additional workspace directories do not contribute skills. The primary workspace remains the only project source.

Install

Install one skill from a repository:

Install from a local directory:

add is an alias for install. Without --skill, fx installs every valid skill in the source. Managed installs always go to ~/.fx/skills/; fx never writes into another agent's directory.

Use /skills path to print the managed install root.

The agent can also install a skill with install_skill, then load it later with the skill tool.

Create and remove

Create or remove a skill in the managed skill directory:

These commands manage only ~/.fx/skills/. Remove workspace or third-party skills at their source.

File format

Each skill uses a SKILL.md file with YAML frontmatter followed by Markdown instructions:

---
name: my-skill
description: Use this when a request needs...
---

# My skill

Instructions for the agent.

name is required and must fit on one line. description is optional and may be an unquoted or quoted scalar, or a block introduced by >, >-, or |. Extra frontmatter fields are ignored, so compatible skills can carry metadata for other agents. A file without frontmatter uses its directory name.

Malformed or unreadable candidates are skipped with a warning; other skills in the same root still load.