Agent skills

What skills areCopy Anchor Link

An agent skill is a folder of instructions the daemon discovers on your machine and exposes over MCP. Each skill is a directory containing at least a SKILL.md file (YAML frontmatter + markdown body), plus optional resource files.

Agents use them on demand: they see names and short descriptions first, then call skill_load only when a task needs the full instructions. That keeps the context window small and works the same in Cursor, Claude, ChatGPT, Codex, and Flexx Agent.

RequirementsCopy Anchor Link

Skills run on the machine, not in the cloud:

1. Install or update the CLI (v0.14.9+ includes skills).
2. Keep the daemon connected (flexx service install or flexx connect).
3. The remote must advertise the skills capability (visible under Machines and the Skills page).

curl -fsSL https://cli.flexx.dev/install.sh | sh
flexx service restart   # required so the new binary is what runs
flexx version           # expect 0.14.9 or newer

If you only replace the binary and do not restart the service, the old process keeps running the previous code until restart.

Discovery rootsCopy Anchor Link

The daemon scans these folders (project roots only when a git workspace is set):

Project (nearest git root)Copy Anchor Link

Global ($HOME)Copy Anchor Link

Precedence: project roots win over global; within a tier, order is as in the tables above. Symlinked trees (for example .claude/skills → .agents/skills) are deduped by real path so the same folder is not listed twice.

An in-memory index is kept fresh with a filesystem watcher (plus a cheap rescan on list/load).

SKILL.md formatCopy Anchor Link

---
name: web-perf
description: Audit page performance and suggest concrete fixes
---

# Web performance

1. Capture a Lighthouse-style checklist for the target URL.
2. ...

• name — stable id used by skill_load (letters, digits, ., -, _).
• description — one-line summary shown in catalogs and system prompts.
• Body — full instructions; optional sibling files can be loaded by relative path.

MCP toolsCopy Anchor Link

Writes never modify project folders or third-party global roots. Clients that prompt on mutating tools (Cursor, Claude, ChatGPT, etc.) treat save/delete/import like any other write tool — there is no separate Flexx-only approval channel.

ExamplesCopy Anchor Link

List everything matching a query:

{ "name": "skill_list", "arguments": { "query": "perf" } }

Load full instructions:

{ "name": "skill_load", "arguments": { "name": "web-perf" } }

Load one resource file inside the skill folder:

{ "name": "skill_load", "arguments": { "name": "web-perf", "path": "checklist.md" } }

Import from GitHub into ~/.flexx/skills:

{
  "name": "skill_import",
  "arguments": {
    "source": "github:owner/repo/path/to/skill",
    "name": "optional-local-name"
  }
}

Flexx AgentCopy Anchor Link

When the bound machine exposes skill_list, Flex Agent injects winning skill names and short descriptions into the system prompt (bodies stay out of the prompt until skill_load). The Skills page in the dashboard shows discovery roots, tools, and which machines advertise the skills capability.

Best practicesCopy Anchor Link

• Keep descriptions specific so the model picks the right skill without loading every body.
• Prefer one skill per workflow; split huge guides into resources loaded by path.
• Put shared team skills in the repo under .flexx/skills or .agents/skills.
• Put personal preferences under ~/.flexx/skills so they survive across clones.